Python OpenTelemetry Instrumentation

This document contains instructions on how to set up OpenTelemetry instrumentation in your Python applications and view your application traces in SigNoz.

Requirements

• Python 3.8 or newer

python3 -m venv .venv
source .venv/bin/activate

pip install opentelemetry-distro==0.43b0
pip install opentelemetry-exporter-otlp==1.22.0

opentelemetry-bootstrap --action=install

OTEL_RESOURCE_ATTRIBUTES=service.name=<service_name> \
OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<region>.signoz.cloud:443" \
OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your-ingestion-key>" \
OTEL_EXPORTER_OTLP_PROTOCOL=grpc \
opentelemetry-instrument <your_run_command>

pip install opentelemetry-distro==0.43b0
pip install opentelemetry-exporter-otlp==1.22.0

opentelemetry-bootstrap --action=install

OTEL_RESOURCE_ATTRIBUTES=service.name=<service_name> \
OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317" \
OTEL_EXPORTER_OTLP_PROTOCOL=grpc \
opentelemetry-instrument <your_run_command>

Validating instrumentation by checking for traces

With your application running, you can verify that you’ve instrumented your application with OpenTelemetry correctly by confirming that tracing data is being reported to SigNoz.

To do this, you need to ensure that your application generates some data. Applications will not produce traces unless they are being interacted with, and OpenTelemetry will often buffer data before sending. So you need to interact with your application and wait for some time to see your tracing data in SigNoz.

Validate your traces in SigNoz:

1. Trigger an action in your app that generates a web request. Hit the endpoint a number of times to generate some data. Then, wait for some time.
2. In SigNoz, open the Services tab. Hit the Refresh button on the top right corner, and your application should appear in the list of Applications.
3. Go to the Traces tab, and apply relevant filters to see your application’s traces.

You might see other dummy applications if you’re using SigNoz for the first time. You can remove it by following the docs here.

Running applications with Gunicorn, uWSGI

For application servers which are based on pre fork model like Gunicorn, uWSGI you have to add a post_fork hook or a @postfork decorator in your configuration.

Check this documentation from OpenTelemetry on how to set it up.

Here's a working example configured with a gunicorn server with post_fork hook.

Troubleshooting your SigNoz installation

Application servers such as Uvicorn, Hypercorn, etc.

• Uvicorn with --workers flag is not supported. The work around for this is to use gunicorn with uvicorn as the worker class gunicorn -k uvicorn.workers.UvicornWorker.
• Hypercorn is not supported. There is no workaround for this. Please follow the issue https://github.com/pgjones/hypercorn/issues/215

Spans are not being reported

If spans are not being reported to SigNoz, try enabling debug exporter which writes the JSON formatted trace data to the console by setting env var OTEL_TRACES_EXPORTER=console.

OTEL_RESOURCE_ATTRIBUTES=service.name=python_app OTEL_TRACES_EXPORTER=console opentelemetry-instrument <your run command>

{
    "name": "alice",
    "context": {
        "trace_id": "0xedb7caf0c8b082a9578460a201759193",
        "span_id": "0x57cf7eee198e1fed",
        "trace_state": "[]"
    },
    "kind": "SpanKind.INTERNAL",
    "parent_id": null,
    "start_time": "2022-03-27T14:55:18.804758Z",
    "end_time": "2022-03-27T14:55:18.804805Z",
    "status": {
        "status_code": "UNSET"
    },
    "attributes": {},
    "events": [],
    "links": [],
    "resource": {
        "telemetry.sdk.language": "python",
        "telemetry.sdk.name": "opentelemetry",
        "telemetry.sdk.version": "1.10.0",
        "service.name": "my-service"
    }
}

Sample Application

• Working example where we have configured a gunicorn server with post_fork hook.