Splunk OpenTelemetry Python

2.9.0 · active · verified Thu Apr 16

The `splunk-opentelemetry` Python distribution provides automatic and manual instrumentation for Python applications, collecting traces, metrics, and logs using OpenTelemetry. It bundles OpenTelemetry SDK and API components, along with exporters and instrumentations specifically configured for Splunk Observability Cloud. The current version is 2.9.0, with regular releases tied to upstream OpenTelemetry Python component updates.

Common errors

```
ModuleNotFoundError: No module named 'splunk_opentelemetry'
```
cause `splunk-opentelemetry` is not installed or the Python environment is incorrect.

fix Ensure the package is installed in the active Python environment: `pip install splunk-opentelemetry`
```
My application is running, but no traces or metrics appear in Splunk Observability Cloud.
```
cause OpenTelemetry Collector or Splunk HEC endpoint is misconfigured, inaccessible, or `OTEL_SERVICE_NAME` is missing, preventing telemetry export.

fix Verify `OTEL_EXPORTER_OTLP_ENDPOINT` (e.g., `http://localhost:4318` or your Collector's address) and `OTEL_SERVICE_NAME` are correctly set. Check network connectivity to the endpoint and ensure the collector or HEC is running and configured to receive OTLP data.
```
TypeError: 'NoneType' object is not callable (often related to instrumentation)
```
cause This error can occur if auto-instrumentation fails to patch correctly, if programmatic instrumentation is attempted before the SDK is fully configured, or due to conflicts with other instrumentation packages.

fix Ensure `splunk-py-trace` is used as the entry point for auto-instrumentation (e.g., `splunk-py-trace python your_app.py`). If using programmatic instrumentation, ensure `SplunkOpenTelemetryConfigurator().configure()` is called early in your application's lifecycle, preferably before any other OTel setup.

Warnings

breaking Version 2.0.0 introduced significant breaking changes, including a complete rewrite of the API and underlying instrumentation. Direct usage of `opentelemetry-sdk` components might need adjustment, and the overall instrumentation approach changed.
Fix: Consult the [v2 Release Notes](https://github.com/signalfx/splunk-otel-python/blob/v2/VERSION_2_RELEASE_NOTES.md) and migrate to the new `SplunkOpenTelemetryConfigurator` for programmatic setup or use `splunk-py-trace` for auto-instrumentation.
gotcha Configuration of the OpenTelemetry SDK (e.g., OTLP endpoint, service name, access token) relies heavily on environment variables (e.g., `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_SERVICE_NAME`, `SPLUNK_ACCESS_TOKEN`). Misconfiguration or missing variables will result in no telemetry being exported or being exported to the wrong location.
Fix: Always ensure the necessary `OTEL_` and `SPLUNK_` environment variables are correctly set in the application's environment before startup or before calling `SplunkOpenTelemetryConfigurator().configure()`.
gotcha There are two main ways to instrument: automatic via `splunk-py-trace` (which wraps your application command) and programmatic using `SplunkOpenTelemetryConfigurator.configure()` and manual instrumentation. Mixing these can lead to unexpected behavior or double instrumentation.
Fix: For simple scripts or applications, `splunk-py-trace` is often sufficient. For complex applications (e.g., Flask/Django), programmatic configuration and manual instrumentation, possibly alongside specific OTel framework instrumentations, provides more control. Choose one primary method.
gotcha The `splunk-opentelemetry` package frequently upgrades its underlying OpenTelemetry Python dependencies (API and SDK). This means that if you rely on specific OTel API features or have other OTel-related packages installed, there might be version conflicts or unexpected changes in behavior between `splunk-opentelemetry` releases.
Fix: Periodically review the release notes for `splunk-opentelemetry` and the upstream OpenTelemetry Python project. Ensure all OTel-related packages in your environment are compatible. Pinning `splunk-opentelemetry` to a minor version can help manage this.

Install

pip install splunk-opentelemetry Standard installation

Imports

SplunkOpenTelemetryConfigurator
wrong:
```
from splunk_opentelemetry import SplunkOpenTelemetryConfigurator
```
correct:
```
from splunk_opentelemetry.instrumentation import SplunkOpenTelemetryConfigurator
```
The configurator is located in the `instrumentation` submodule, not directly under `splunk_opentelemetry`.
trace
```
from opentelemetry import trace
```
Core OpenTelemetry API imports are directly from `opentelemetry`, as `splunk-opentelemetry` configures the underlying SDK.
metrics
```
from opentelemetry import metrics
```
Core OpenTelemetry API imports are directly from `opentelemetry`, as `splunk-opentelemetry` configures the underlying SDK.

Quickstart

This quickstart demonstrates programmatic initialization of the Splunk OpenTelemetry Python SDK and a simple traced operation. Ensure that `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_SERVICE_NAME`, and optionally `SPLUNK_ACCESS_TOKEN` environment variables are set before running, pointing to your OpenTelemetry Collector or Splunk HEC endpoint.

import os
from opentelemetry import trace
from splunk_opentelemetry.instrumentation import SplunkOpenTelemetryConfigurator

# Set required environment variables for the Splunk OTLP exporter
# In a real application, these would typically be set in the shell or deployment config.
# For a local OpenTelemetry Collector (e.g., Splunk Distribution of OpenTelemetry Collector),
# the endpoint might be http://localhost:4318 for HTTP or http://localhost:4317 for gRPC.
os.environ['OTEL_SERVICE_NAME'] = os.environ.get('OTEL_SERVICE_NAME', 'my-python-app')
os.environ['OTEL_EXPORTER_OTLP_ENDPOINT'] = os.environ.get('OTEL_EXPORTER_OTLP_ENDPOINT', 'http://localhost:4318')
os.environ['SPLUNK_ACCESS_TOKEN'] = os.environ.get('SPLUNK_ACCESS_TOKEN', 'YOUR_SPLUNK_ACCESS_TOKEN') # Only required if sending directly to Splunk HEC

# Configure the OpenTelemetry SDK for Splunk Observability Cloud
# This initializes the TracerProvider, MeterProvider, and sets up
# the OTLP exporter with Splunk-specific resource attributes.
# It reads configuration from environment variables.
SplunkOpenTelemetryConfigurator().configure()

# Get a tracer configured by the Splunk OpenTelemetry SDK
tracer = trace.get_tracer(__name__)

# Perform a simple operation within a trace
with tracer.start_as_current_span("my-quickstart-operation") as span:
    print(f"Starting span: {span.name}")
    # Add an attribute to the span
    span.set_attribute("http.method", "GET")
    span.set_attribute("http.url", "/api/data")

    # Simulate some work
    import time
    time.sleep(0.1)

    with tracer.start_as_current_span("inner-work") as inner_span:
        print(f"  Starting inner span: {inner_span.name}")
        inner_span.set_attribute("data.size", 1024)
        time.sleep(0.05)
        print(f"  Finishing inner span: {inner_span.name}")

    print(f"Finishing span: {span.name}")

print("\nTracing complete. Data should be sent to the configured OTLP endpoint.")
print("Ensure an OpenTelemetry Collector or Splunk HEC is listening at the endpoint.")

view raw JSON →