{"id":10329,"library":"uptrace","title":"OpenTelemetry Python distribution for Uptrace","description":"Uptrace provides an OpenTelemetry Python distribution that simplifies the setup of tracing and metrics for Python applications. It pre-configures the OpenTelemetry SDK to send data to the Uptrace backend, making it easier to instrument your code and gain visibility into your application's performance. The current version is 1.41.0, and it follows a regular release cadence, often aligning with OpenTelemetry SDK updates.","status":"active","version":"1.41.0","language":"en","source_language":"en","source_url":"https://github.com/uptrace/uptrace-python","tags":["observability","opentelemetry","tracing","metrics","monitoring","apm"],"install":[{"cmd":"pip install uptrace","lang":"bash","label":"Install Uptrace OpenTelemetry distribution"}],"dependencies":[],"imports":[{"note":"`configure_opentelemetry` is a Uptrace-specific helper, not part of the core OpenTelemetry SDK.","wrong":"from opentelemetry.sdk.trace import configure_opentelemetry","symbol":"configure_opentelemetry","correct":"from uptrace import configure_opentelemetry"}],"quickstart":{"code":"import os\nfrom uptrace import configure_opentelemetry\nfrom opentelemetry import trace\n\n# Retrieve Uptrace DSN from environment variable, or use a dummy for demonstration.\n# Replace with your actual Uptrace DSN (e.g., from your Uptrace project settings).\n# Example DSN format: \"http://<token>@<host>:14101/<project_id>\"\ndsn = os.environ.get(\"UPTRACE_DSN\")\n\nif not dsn:\n    print(\"WARNING: UPTRACE_DSN environment variable is not set.\")\n    print(\"Using a dummy DSN for demonstration purposes. No traces will be sent to Uptrace.\")\n    # This dummy DSN will not send data to Uptrace.\n    # In a real application, you should always provide a valid DSN.\n    dsn = \"http://user:pass@127.0.0.1:14101/0\"\n\n# Configure OpenTelemetry with Uptrace\n# The service_name is crucial for identifying your application in Uptrace.\nconfigure_opentelemetry(\n    dsn=dsn,\n    service_name=\"my-python-app\"\n)\n\n# Get a tracer instance\ntracer = trace.get_tracer(__name__)\n\n# Create and activate a root span\nprint(\"Starting a traced operation...\")\nwith tracer.start_as_current_span(\"my-root-operation\"): # Create a root span\n    print(\"Inside 'my-root-operation'\")\n    # Simulate some work by creating a nested span\n    with tracer.start_as_current_span(\"my-sub-operation\"): # Create a child span\n        print(\"Inside 'my-sub-operation': doing some work...\")\n\nprint(\"Operation complete. Attempting to send traces to Uptrace (if DSN is valid).\")\n\n# It's crucial to shut down the tracer provider to ensure all buffered spans\n# are flushed and exported to Uptrace before the application exits.\n# In long-running applications or web frameworks, this is often handled\n# automatically by framework integrations or application shutdown hooks.\ntrace.get_tracer_provider().shutdown()\nprint(\"Tracer provider shut down.\")","lang":"python","description":"This quickstart demonstrates how to configure the Uptrace OpenTelemetry distribution, obtain a tracer, and create a simple hierarchy of spans. It correctly handles the Uptrace DSN via an environment variable or a dummy value for demonstration, and includes the essential `shutdown()` call for short-lived applications to ensure traces are exported."},"warnings":[{"fix":"Call `opentelemetry.trace.get_tracer_provider().shutdown()` (and `metrics.get_meter_provider().shutdown()` if using metrics) before your application exits.","message":"OpenTelemetry SDK needs explicit shutdown: If your application is short-lived (e.g., a script or CLI tool), you must explicitly shut down the OpenTelemetry TracerProvider (and similarly for Metrics and Logs providers) to ensure all buffered spans and metrics are flushed and exported to Uptrace before the process exits.","severity":"gotcha","affected_versions":"All"},{"fix":"Verify the `UPTRACE_DSN` environment variable is correctly set or passed as the `dsn` argument to `uptrace.configure_opentelemetry`. The DSN should be obtained from your Uptrace project settings and follow the format `http://<token>@<host>:14101/<project_id>`.","message":"Incorrect or missing Uptrace DSN: If traces or metrics are not appearing in Uptrace, the most common cause is an incorrect or missing Uptrace DSN. The DSN tells the SDK where to send the data.","severity":"gotcha","affected_versions":"All"},{"fix":"Refer to Uptrace's documentation for framework-specific integrations. This typically involves using the `opentelemetry-instrument` command or manual setup of OpenTelemetry WSGI/ASGI middleware or framework-specific plugins.","message":"Automatic tracing for web frameworks requires specific integrations. Simply calling `uptrace.configure_opentelemetry` is not enough for automatic instrumentation of HTTP requests in popular frameworks like Flask, Django, or FastAPI.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"1. Check `UPTRACE_DSN` environment variable or `dsn` argument in `configure_opentelemetry`. 2. Ensure `opentelemetry.trace.get_tracer_provider().shutdown()` is called before application exit, especially for short-lived scripts. 3. Check application logs for any errors from the OpenTelemetry exporter.","cause":"The Uptrace DSN is incorrect or missing, the OpenTelemetry SDK was not shut down properly for a short-lived process, or there are network issues preventing export.","error":"No spans are visible in Uptrace despite running the application."},{"fix":"Install the package using `pip install uptrace` in the correct virtual environment where your application is running.","cause":"The `uptrace` package is not installed in the active Python environment.","error":"ModuleNotFoundError: No module named 'uptrace'"},{"fix":"Import `configure_opentelemetry` directly from the `uptrace` package: `from uptrace import configure_opentelemetry`.","cause":"`configure_opentelemetry` is a convenience function provided specifically by the `uptrace` distribution, not a standard component of the core `opentelemetry-sdk`.","error":"ImportError: cannot import name 'configure_opentelemetry' from 'opentelemetry.sdk.trace' (or similar OpenTelemetry path)"}]}