Send Python application data to Observe

“Zero-code” auto-instrumentation for Python is not viable, due to common usages of Gunicorn / uvicorn process forking patterns. opentelemetry-instrument doesn’t work reliably across these frameworks and can lead to unnecessary turnaround time.

Instead, we recommend one-line programmatic auto-instrumentation:

  1. This gives you more control over initializing it early in your code.

  2. Easily pluggable into process fork calls in popular frameworks like Gunicorn / uvicorn.

  3. Makes it compatible with OpenLLMetry instrumentation for LLM Explorer.

For more information about Gunicorn / uWSGI, see Works with Fork Process Models in the OpenTelemetry Python documentation.

To view the list of auto-instrumented libraries and compatible versions, see bootstrap_gen.py in the OpenTelemetry documentation on GitHub.

To manually instrument custom logic, see Instrumentation in the OpenTelemetry documentation.

Instrument your Python application

Perform the following steps to instrument your Python application.

  1. Install the required library dependencies:

pip install opentelemetry-distro opentelemetry-exporter-otlp

  1. Import and initialize the auto-instrumentor in the app’s entrypoint. Note that OpenTelemetry should take precedence all other processes.

from opentelemetry.instrumentation import auto_instrumentation

auto_instrumentation.initialize()

  1. Set the following environment variables. Replace the placeholders such as ${YOUR_SERVICE_NAME} with the actual information from your environment.

OTEL_SERVICE_NAME=${YOUR_SERVICE_NAME}
OTEL_RESOURCE_ATTRIBUTES=deployment.environment=${YOUR_APP_ENVIRONMENT}
OTEL_EXPORTER_OTLP_ENDPOINT=http://${YOUR_OBSERVE_AGENT_ENDPOINT}:4318 
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORTER=otlp 
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true

Run your instrumented app

opentelemetry-instrument \
    python myapp.py

Next steps

Navigate to Traces in your Observe tenant to view traces from your application.

Troubleshooting

What to do if you encounter the following issues:

  • Your application data is not reaching Observe

  • Your ports are blocked by a firewall

  • You are getting duplicate spans in Observe

My application data is not reaching Observe

If your data is not showing up in Observe, first verify that Observe Agent is receiving data from your application. See Troubleshooting the Observe Agent.

Common reasons why the Observe agent is not receiving traces from your application:

Ports blocked by firewall

Ensure that any firewalls within the same network as your app and collector are configured to allow traffic on ports 4317 and 4318. The application instrumentation uses these ports to communicate with the Observe agent.

I am getting duplicate spans in Observe

If you’re seeing multiple spans with the same span_id in the Trace Explorer, the cause may be the following:

  • Multiple layers of OTel instrumentation for the same spans

  • Multiple exporters configured (either in your Agent, OTel collector, or application code) that point to Observe

  • Some other pathway in your environment is duplicating data (e.g., proxy or load balancer)