Python OpenTelemetry Instrumentation Guide

Gunicorn works out of the box. No extra setup needed unless you use the --preload flag. If you do use --preload, see the post_fork hook example.

uWSGI requires one of these options:

• Add lazy-apps = true to your uWSGI config (recommended, simplest fix)
• Or implement a post_fork hook (see example)

Why don't traces appear in SigNoz?

Check environment variables are set:

echo $OTEL_EXPORTER_OTLP_ENDPOINT
echo $OTEL_RESOURCE_ATTRIBUTES

Verify network connectivity:

# For SigNoz Cloud
curl -v https://ingest.<region>.signoz.cloud:443/v1/traces

Enable console exporter to verify spans are being created:

OTEL_TRACES_EXPORTER=console opentelemetry-instrument <your_run_command>

If you see JSON span output in your terminal but traces don't appear in SigNoz, the issue is with export configuration (endpoint, auth, or network). If no output appears, the instrumentation isn't capturing your requests.

Why do multi-worker servers (Uvicorn, Gunicorn) drop spans?

Application servers that spawn multiple worker processes require special handling because the OpenTelemetry SDK isn't fork-safe.

• Uvicorn with --workers flag is not supported. Use Gunicorn with Uvicorn workers instead:

  opentelemetry-instrument gunicorn -k uvicorn.workers.UvicornWorker main:app
  

• Hypercorn/Unicorn are not supported due to fork-safety issues. See the Hypercorn/Unicorn tab for details and workarounds.
• Gunicorn with --preload or uWSGI need extra config. See Running with Gunicorn or uWSGI.

Hot reload breaks instrumentation

Don't run your app in reloader/hot-reload mode. For Flask, avoid FLASK_ENV=development. For Django, use --noreload. For Uvicorn/FastAPI, don't use --reload.

Database calls not showing in traces

Auto-instrumentation detects and instruments common database libraries. Ensure you've run opentelemetry-bootstrap --action=install after installing your database drivers.

PostgreSQL note: psycopg2 is preferred over psycopg2-binary for auto-instrumentation. If you must use psycopg2-binary, you may need to use manual instrumentation with Psycopg2Instrumentor().instrument(skip_dep_check=True).

Common database instrumentations installed by bootstrap:

• PostgreSQL: opentelemetry-instrumentation-psycopg2
• MySQL: opentelemetry-instrumentation-pymysql or opentelemetry-instrumentation-mysql
• MongoDB: opentelemetry-instrumentation-pymongo
• Redis: opentelemetry-instrumentation-redis
• SQLAlchemy: opentelemetry-instrumentation-sqlalchemy

Check supported versions for compatibility with your library versions.

What is the OpenTelemetry Collector?

Think of the OTel Collector as a middleman between your app and SigNoz. Instead of your application sending data directly to SigNoz, it sends everything to the Collector first, which then forwards it along.

Why use it?

• Cleaning up data — Filter out noisy traces you don't care about, or remove sensitive info before it leaves your servers.
• Keeping your app lightweight — Let the Collector handle batching, retries, and compression instead of your application code.
• Adding context automatically — The Collector can tag your data with useful info like which Kubernetes pod or cloud region it came from.
• Future flexibility — Want to send data to multiple backends later? The Collector makes that easy without changing your app.

See Switch from direct export to Collector for step-by-step instructions to convert your setup.

For more details, see Why use the OpenTelemetry Collector? and the Collector configuration guide.