Metadata-Version: 2.5
Name: splunk-opentelemetry
Version: 2.13.2
Project-URL: Documentation, https://github.com/signalfx/splunk-otel-python#readme
Project-URL: Issues, https://github.com/signalfx/splunk-otel-python/issues
Project-URL: Source, https://github.com/signalfx/splunk-otel-python
License-Expression: Apache-2.0
License-File: LICENSE.txt
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
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
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.10
Requires-Dist: opentelemetry-api==1.45.1
Requires-Dist: opentelemetry-configuration==0.66b1
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc==1.45.1
Requires-Dist: opentelemetry-exporter-otlp-proto-http==1.45.1
Requires-Dist: opentelemetry-instrumentation-logging==0.66b1
Requires-Dist: opentelemetry-instrumentation-system-metrics==0.66b1
Requires-Dist: opentelemetry-instrumentation==0.66b1
Requires-Dist: opentelemetry-opamp-client==0.4b0
Requires-Dist: opentelemetry-propagator-b3==1.45.1
Requires-Dist: opentelemetry-sdk==1.45.1
Requires-Dist: opentelemetry-semantic-conventions==0.66b1
Requires-Dist: protobuf>=6.33.5
Requires-Dist: wrapt>=2.5.0
Provides-Extra: secureapp
Requires-Dist: secureapp-python-agent>=26.10.0; extra == 'secureapp'
Description-Content-Type: text/markdown

# Splunk Distribution of OpenTelemetry Python

[![PyPI - Version](https://img.shields.io/pypi/v/splunk-opentelemetry.svg)](https://pypi.org/project/splunk-opentelemetry)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/splunk-opentelemetry.svg)](https://pypi.org/project/splunk-opentelemetry)

The Splunk Distribution of OpenTelemetry Python extends
[OpenTelemetry Python](https://github.com/open-telemetry/opentelemetry-python) to automatically instrument Python
applications and export traces, metrics, and logs to Splunk Observability Cloud. It patches supported libraries at
runtime with OpenTelemetry-compatible instrumentation and provides Splunk-specific configuration defaults.

This distribution comes with the following defaults:

- [OTLP gRPC exporters](https://opentelemetry-python.readthedocs.io/en/latest/exporter/otlp/otlp.html)
  configured to send traces, metrics, and logs to a locally running
  [Splunk OpenTelemetry Collector](https://github.com/signalfx/splunk-otel-collector)
  (`http://localhost:4317`).
- Unlimited default limits for
  [configuration options](https://docs.splunk.com/Observability/gdi/get-data-in/application/python/configuration/advanced-python-otel-configuration.html)
  to support full-fidelity traces.
- [System metrics instrumentation](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-system-metrics).
- Python logging instrumentation.

## Requirements

The Splunk Distribution of OpenTelemetry Python requires Python 3.10 or later. Supported
libraries are listed
[here](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation).

## Get started

For complete instructions on how to get started with the Splunk Distribution of OpenTelemetry Python, see
[Instrument a Python application for Splunk Observability Cloud](https://quickdraw.splunk.com/redirect/?product=Observability&version=current&location=python.application) in the official documentation.

For the standard OpenTelemetry setup, install the Splunk Distribution of OpenTelemetry Python in your application
environment. The distribution configures OTLP exporters for traces, metrics, and logs, includes system metrics
instrumentation, and enables Python logging instrumentation.

```bash
pip install splunk-opentelemetry
```

Install instrumentation packages for the libraries your application uses:

```bash
opentelemetry-bootstrap -a install
```

Then run your application with `opentelemetry-instrument`:

```bash
OTEL_SERVICE_NAME=my-python-service opentelemetry-instrument python app.py
```

By default, OTLP exporters send telemetry to a locally running
[Splunk OpenTelemetry Collector](https://github.com/signalfx/splunk-otel-collector)
at `http://localhost:4317`. To send telemetry directly to Splunk Observability
Cloud instead, set `SPLUNK_REALM` and `SPLUNK_ACCESS_TOKEN` before starting your
application. `SPLUNK_REALM` configures direct ingest endpoints for traces and
metrics.

## Declarative configuration

The distribution includes experimental support for the OpenTelemetry declarative
configuration file format. Set `OTEL_CONFIG_FILE` to the path of the YAML
configuration file when you start the instrumented application:

```bash
OTEL_CONFIG_FILE=/path/to/config.yaml opentelemetry-instrument python app.py
```

See the [basic declarative configuration example](docs/examples/declarative-config.yaml),
which exports traces, metrics, and logs to a local Collector at `http://localhost:4317`.

This support configures upstream OpenTelemetry SDK components. The GDI
`distribution.splunk` configuration block is not supported yet. Configure
exporters, including their endpoints and authentication headers, in the YAML file.
OpAMP does not report the declarative file as effective configuration and cannot
manage it remotely yet.

## Profiling

The Splunk Distribution of OpenTelemetry Python supports continuous profiling and
call graph profiling. Both modes export profiling data through OpenTelemetry logs
for correlation with traces in Splunk APM. See [Profiling](docs/profiling.md) for
configuration and limitations.

## Optional: Cisco SecureApp

To also install the [Cisco SecureApp](https://pypi.org/project/secureapp-python-agent/)
OpenTelemetry extension, specify the `secureapp` extra:

```bash
pip install "splunk-opentelemetry[secureapp]"
```

This extra installs the SecureApp Python agent, which reports runtime Python
package dependencies through OpenTelemetry logs.

SecureApp dependency logs use the `secureapp` instrumentation scope. Collector
deployments must route those logs to the SecureApp event ingest endpoint
(`/v3/event`) and add the SecureApp instrumentation header on the outbound
exporter. See [docs/secureapp.md](docs/secureapp.md) for setup details and
[docs/examples/secureapp-collector-config.yaml](docs/examples/secureapp-collector-config.yaml)
for a collector example.

## Fleet management with OpAMP

The Splunk Distribution of OpenTelemetry Python provides OpAMP support. When enabled, the OpAMP client connects to the
configured endpoint and reports the Python agent's status and settings. Agents connected to Splunk Observability Cloud
appear on the Fleet Management page.

Set `SPLUNK_OPAMP_ENABLED=true` to enable OpAMP. The default OpAMP endpoint is a local Splunk OpenTelemetry Collector.
See [OpAMP](docs/opamp.md) for setup, configuration, and limits.

## License

The Splunk Distribution of OpenTelemetry Python is a distribution of
[OpenTelemetry Python](https://github.com/open-telemetry/opentelemetry-python). It is licensed under the terms of the
Apache Software License version 2.0. See [the license file](./LICENSE.txt) for more details.
