OpenTelemetry Python Distro

Warnings

• gotcha OpenTelemetry Python, including `opentelemetry-distro`, is largely in beta. While tracing APIs are relatively stable, metrics and logging APIs are still evolving. This means breaking changes can occur between minor versions.
  Fix: Review release notes carefully before upgrading. Test new versions thoroughly in non-production environments.
• gotcha The `opentelemetry-distro` configures a default OTLP SpanExporter, which attempts to send data to an OpenTelemetry Collector (by default on `http://localhost:4317` or `grpc://localhost:4317`). If no Collector is running or accessible, telemetry will not be exported.
  Fix: Ensure an OpenTelemetry Collector is running and accessible from your application. Configure the `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable if your Collector is at a different address or port.
• breaking When using web frameworks like Flask or Django, running in debug mode with an enabled reloader (e.g., `app.run(debug=True)`) can conflict with auto-instrumentation, causing it to fail.
  Fix: Disable the reloader when using auto-instrumentation. For Flask, set `use_reloader=False` (e.g., `app.run(debug=True, use_reloader=False)`). For Django, use the `--noreload` flag when starting your application.
• gotcha The generic `opentelemetry-distro` provides default configurations. If you intend to use a vendor-specific OpenTelemetry distribution (e.g., AWS Distro for OpenTelemetry, Azure Monitor OpenTelemetry Distro), ensure you install and use *that specific distro* as it often includes tailored exporters, resource detectors, and instrumentations for the target backend. Mixing distros or expecting generic distro to have vendor-specific features is a common mistake.
  Fix: Identify your target observability backend and consult its specific OpenTelemetry documentation. Install the appropriate vendor-specific distro if one exists and is recommended.

Install

• pip install opentelemetry-distro[otlp] opentelemetry-instrumentation opentelemetry-bootstrap -a install Basic Installation with OTLP Exporter and Auto-instrumentation

Imports

• Auto-instrumentation via opentelemetry-instrument

  opentelemetry-instrument python my_app.py

  The `opentelemetry-distro` package is primarily used via the `opentelemetry-instrument` command-line wrapper, which applies auto-instrumentation at runtime based on discovered libraries and the distro's configuration.

Quickstart

To quickly get started, install `opentelemetry-distro[otlp]` and then run `opentelemetry-bootstrap -a install` to automatically install instrumentations for detected libraries. Then, run your application using the `opentelemetry-instrument` wrapper script. This example demonstrates a simple Flask application that makes an HTTP request, which will be automatically traced. Ensure an OpenTelemetry Collector is running to receive telemetry data. For Flask/Django, set `use_reloader=False` (Flask) or use `--noreload` (Django) to avoid instrumentation issues.

import os
import requests
from flask import Flask

app = Flask(__name__)

@app.route("/hello")
def hello_world():
    return "Hello, World!"

@app.route("/external")
def call_external():
    # This call should be traced automatically if requests is instrumented
    response = requests.get("http://localhost:5001/hello")
    return f"Called external service: {response.text}"

if __name__ == '__main__':
    # Run this app with: opentelemetry-instrument python app.py
    # Ensure an OpenTelemetry Collector is running on localhost:4317 or configure OTEL_EXPORTER_OTLP_ENDPOINT
    # (e.g., docker run -p 4317:4317 -p 4318:4318 otel/opentelemetry-collector:latest --config=/etc/otel-collector-config.yaml)
    # The collector config should include otlp receiver and a logging/debug exporter.
    app.run(port=5001, debug=False, use_reloader=False)