splunk-opentelemetry 0.17.0

The Splunk distribution of OpenTelemetry Python Instrumentation provides a Python agent that automatically instruments your Python application to capture and report distributed traces to SignalFx APM.

---

Getting Started   •   Getting Involved   •   Migrating from SignalFx Python Tracing

Examples   •   Security   •   Supported Libraries   •   Troubleshooting

---

The documentation below refers to the in development version of this package. Docs for the latest version (v0.17.0) can be found here.

Splunk Distribution of OpenTelemetry Python

The Splunk distribution of OpenTelemetry Python provides multiple installable packages that automatically instruments your Python application to capture and report distributed traces to Splunk APM. Instrumentation works by patching supported libraries at runtime with an OpenTelemetry-compatible tracer to capture and export trace spans.

This Splunk distribution comes with the following defaults:

• W3C tracecontext and W3C baggage context propagation; B3 can also be configured.
• OTLP gRPC exporter configured to send spans to a locally running Splunk OpenTelemetry Connector (http://localhost:4317).
• Unlimited default limits for configuration options to support full-fidelity traces.

If you're currently using the SignalFx Tracing Library for Python and want to migrate to the Splunk Distribution of OpenTelemetry Python, see Migrate from the SignalFx Tracing Library for Python.

:construction: This project is currently in BETA. It is officially supported by Splunk. However, breaking changes MAY be introduced.

Requirements

This Splunk Distribution of OpenTelemetry requires Python 3.6 or later. If you're still using Python 2, continue using the SignalFx Tracing Library for Python.

Getting Started

To get started, install the splunk-opentelemetry[all] package, run the bootstrap script and wrap your run command with splunk-py-trace.

For example, if the runtime parameters were:

python main.py --port=8000

Then the runtime parameters should be updated to:

$ pip install splunk-opentelemetry[all]
$ splunk-py-trace-bootstrap
$ OTEL_SERVICE_NAME=my-python-app \
    splunk-py-trace python main.py --port=8000

To see the Python instrumentation in action with sample applications, see our examples.

Basic Configuration

The service name resource attribute is the only configuration option that needs to be specified. You can set it by adding a service.name attribute as shown in the example above.

A few other configuration options that may need to be changed or set are:

• Trace propagation format if not sending to other applications using W3C trace-context. For example, if other applications are instrumented with signalfx-*-tracing instrumentation. See the trace propagation configuration documentation for more information.
• Endpoint if not sending to a locally running Splunk OpenTelemetry Connector with default configuration. For example, if the SignalFx Smart Agent is used. See the exporters configuration documentation for more information.
• Environment resource attribute deployment.environment to specify what environment the span originated from. For example:

  OTEL_RESOURCE_ATTRIBUTES=deployment.environment=production
  

• Service version resource attribute service.version to specify the version of your instrumented application. For example:

  OTEL_RESOURCE_ATTRIBUTES=service.version=1.2.3
  

The deployment.environment and service.version resource attributes are not strictly required, but recommended to be set if they are available.

The OTEL_RESOURCE_ATTRIBUTES syntax is described in detail in the trace configuration section.

Supported Python Versions

The instrumentation works with Python verion 3.6 and higher. Supported libraries are listed here.

Advanced Configuration

For the majority of users, the Getting Started section is all you need. Advanced configuration documentation can be found here. In addition, special cases for instrumentation are documented here.

Manually instrument an application

Documentation on how to manually instrument a Python application is available here.

To extend the instrumentation with the OpenTelemetry Instrumentation for Python, you have to use a compatible API version.

The Splunk Distribution of OpenTelemetry Python version 0.17.0 is compatible with:

• OpenTelemetry API version 1.5.0
• OpenTelemetry SDK version 1.5.0
• OpenTelemetry Instrumentation for Python version 0.24b0

Correlating traces with logs

The Splunk Distribution of OpenTelemetry Python provides a way to correlate traces with logs. It is enabled automatically as part of the logging instrumentation.

License and versioning

The Splunk distribution of OpenTelemetry Python Instrumentation is a distribution of the OpenTelemetry Python project. It is released under the terms of the Apache Software License version 2.0. See the license file for more details.