{"id":8677,"library":"splunk-opentelemetry","title":"Splunk OpenTelemetry Python","description":"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.","status":"active","version":"2.9.0","language":"en","source_language":"en","source_url":"https://github.com/signalfx/splunk-otel-python","tags":["opentelemetry","splunk","tracing","metrics","logs","observability","instrumentation"],"install":[{"cmd":"pip install splunk-opentelemetry","lang":"bash","label":"Standard installation"}],"dependencies":[{"reason":"Transitive dependency of OpenTelemetry components; specific version pinned to avoid conflicts/issues.","package":"protobuf","optional":false}],"imports":[{"note":"The configurator is located in the `instrumentation` submodule, not directly under `splunk_opentelemetry`.","wrong":"from splunk_opentelemetry import SplunkOpenTelemetryConfigurator","symbol":"SplunkOpenTelemetryConfigurator","correct":"from splunk_opentelemetry.instrumentation import SplunkOpenTelemetryConfigurator"},{"note":"Core OpenTelemetry API imports are directly from `opentelemetry`, as `splunk-opentelemetry` configures the underlying SDK.","symbol":"trace","correct":"from opentelemetry import trace"},{"note":"Core OpenTelemetry API imports are directly from `opentelemetry`, as `splunk-opentelemetry` configures the underlying SDK.","symbol":"metrics","correct":"from opentelemetry import metrics"}],"quickstart":{"code":"import os\nfrom opentelemetry import trace\nfrom splunk_opentelemetry.instrumentation import SplunkOpenTelemetryConfigurator\n\n# Set required environment variables for the Splunk OTLP exporter\n# In a real application, these would typically be set in the shell or deployment config.\n# For a local OpenTelemetry Collector (e.g., Splunk Distribution of OpenTelemetry Collector),\n# the endpoint might be http://localhost:4318 for HTTP or http://localhost:4317 for gRPC.\nos.environ['OTEL_SERVICE_NAME'] = os.environ.get('OTEL_SERVICE_NAME', 'my-python-app')\nos.environ['OTEL_EXPORTER_OTLP_ENDPOINT'] = os.environ.get('OTEL_EXPORTER_OTLP_ENDPOINT', 'http://localhost:4318')\nos.environ['SPLUNK_ACCESS_TOKEN'] = os.environ.get('SPLUNK_ACCESS_TOKEN', 'YOUR_SPLUNK_ACCESS_TOKEN') # Only required if sending directly to Splunk HEC\n\n# Configure the OpenTelemetry SDK for Splunk Observability Cloud\n# This initializes the TracerProvider, MeterProvider, and sets up\n# the OTLP exporter with Splunk-specific resource attributes.\n# It reads configuration from environment variables.\nSplunkOpenTelemetryConfigurator().configure()\n\n# Get a tracer configured by the Splunk OpenTelemetry SDK\ntracer = trace.get_tracer(__name__)\n\n# Perform a simple operation within a trace\nwith tracer.start_as_current_span(\"my-quickstart-operation\") as span:\n    print(f\"Starting span: {span.name}\")\n    # Add an attribute to the span\n    span.set_attribute(\"http.method\", \"GET\")\n    span.set_attribute(\"http.url\", \"/api/data\")\n\n    # Simulate some work\n    import time\n    time.sleep(0.1)\n\n    with tracer.start_as_current_span(\"inner-work\") as inner_span:\n        print(f\"  Starting inner span: {inner_span.name}\")\n        inner_span.set_attribute(\"data.size\", 1024)\n        time.sleep(0.05)\n        print(f\"  Finishing inner span: {inner_span.name}\")\n\n    print(f\"Finishing span: {span.name}\")\n\nprint(\"\\nTracing complete. Data should be sent to the configured OTLP endpoint.\")\nprint(\"Ensure an OpenTelemetry Collector or Splunk HEC is listening at the endpoint.\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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()`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure the package is installed in the active Python environment: `pip install splunk-opentelemetry`","cause":"`splunk-opentelemetry` is not installed or the Python environment is incorrect.","error":"ModuleNotFoundError: No module named 'splunk_opentelemetry'"},{"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.","cause":"OpenTelemetry Collector or Splunk HEC endpoint is misconfigured, inaccessible, or `OTEL_SERVICE_NAME` is missing, preventing telemetry export.","error":"My application is running, but no traces or metrics appear in Splunk Observability Cloud."},{"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.","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.","error":"TypeError: 'NoneType' object is not callable (often related to instrumentation)"}]}