Metadata-Version: 2.3
Name: cloudwatch-plugin-otel
Version: 0.1.0
Summary: Amazon CloudWatch plugin for OpenTelemetry
Project-URL: Homepage, https://github.com/aws-observability/aws-otel-python-instrumentation/tree/main/cloudwatch-plugin-otel
Author: Amazon Web Services
License: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Requires-Dist: opentelemetry-api>=1.42.0
Requires-Dist: opentelemetry-instrumentation>=0.63b0
Requires-Dist: opentelemetry-sdk>=1.42.0
Requires-Dist: opentelemetry-semantic-conventions>=0.63b0
Requires-Dist: typing-extensions>=4.5.0
Provides-Extra: test
Description-Content-Type: text/markdown

# cloudwatch-plugin-otel

Amazon CloudWatch plugin for OpenTelemetry.

## Span metrics

The span metrics instrumentor registers a span processor that emits:

- `traces.span.metrics.calls`, a counter incremented once per ended span.
- `traces.span.metrics.duration`, a histogram of span duration in seconds.

Both metrics use the `cloudwatch.plugin.otel.span_metrics` instrumentation
scope. They include `service.name`, `span.name`, `span.kind`, `status.code`, and
supported HTTP, RPC, database, messaging, and error semantic-convention
attributes when those attributes are present on the span.

The instrumentor also wraps the active root sampler. A `DROP` decision becomes
`RECORD_ONLY`, allowing the span processor to derive metrics without changing
which spans are exported.

### Usage

Installing this package registers `SpanMetricsInstrumentor` as an
`opentelemetry_instrumentor` entry point. It is loaded automatically when the
application runs with OpenTelemetry auto-instrumentation:

```shell
opentelemetry-instrument python app.py
```

It can also be enabled programmatically:

```python
from plugins.opentelemetry.cloudwatch import SpanMetricsInstrumentor

SpanMetricsInstrumentor().instrument()
```

Pass `tracer_provider` or `meter_provider` to `instrument()` when using
application-managed providers:

```python
SpanMetricsInstrumentor().instrument(
    tracer_provider=tracer_provider,
    meter_provider=meter_provider,
)
```

The connector binds its meter when it is created. Configure the global
`MeterProvider`, or pass `meter_provider`, before instrumenting so the derived
metrics are recorded.

## License

This project is licensed under the Apache-2.0 License. See [LICENSE](./LICENSE).
