OpenTelemetry Python distribution for Uptrace

1.41.0 · active · verified Fri Apr 17

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.

Common errors

```
No spans are visible in Uptrace despite running the application.
```
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.

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.
```
ModuleNotFoundError: No module named 'uptrace'
```
cause The `uptrace` package is not installed in the active Python environment.

fix Install the package using `pip install uptrace` in the correct virtual environment where your application is running.
```
ImportError: cannot import name 'configure_opentelemetry' from 'opentelemetry.sdk.trace' (or similar OpenTelemetry path)
```
cause `configure_opentelemetry` is a convenience function provided specifically by the `uptrace` distribution, not a standard component of the core `opentelemetry-sdk`.

fix Import `configure_opentelemetry` directly from the `uptrace` package: `from uptrace import configure_opentelemetry`.

Warnings

gotcha 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.
Fix: Call `opentelemetry.trace.get_tracer_provider().shutdown()` (and `metrics.get_meter_provider().shutdown()` if using metrics) before your application exits.
gotcha 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.
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>`.
gotcha 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.
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.

Install

pip install uptrace Install Uptrace OpenTelemetry distribution

Imports

configure_opentelemetry
wrong:
```
from opentelemetry.sdk.trace import configure_opentelemetry
```
correct:
```
from uptrace import configure_opentelemetry
```
`configure_opentelemetry` is a Uptrace-specific helper, not part of the core OpenTelemetry SDK.

Quickstart

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.

import os
from uptrace import configure_opentelemetry
from opentelemetry import trace

# Retrieve Uptrace DSN from environment variable, or use a dummy for demonstration.
# Replace with your actual Uptrace DSN (e.g., from your Uptrace project settings).
# Example DSN format: "http://<token>@<host>:14101/<project_id>"
dsn = os.environ.get("UPTRACE_DSN")

if not dsn:
    print("WARNING: UPTRACE_DSN environment variable is not set.")
    print("Using a dummy DSN for demonstration purposes. No traces will be sent to Uptrace.")
    # This dummy DSN will not send data to Uptrace.
    # In a real application, you should always provide a valid DSN.
    dsn = "http://user:pass@127.0.0.1:14101/0"

# Configure OpenTelemetry with Uptrace
# The service_name is crucial for identifying your application in Uptrace.
configure_opentelemetry(
    dsn=dsn,
    service_name="my-python-app"
)

# Get a tracer instance
tracer = trace.get_tracer(__name__)

# Create and activate a root span
print("Starting a traced operation...")
with tracer.start_as_current_span("my-root-operation"): # Create a root span
    print("Inside 'my-root-operation'")
    # Simulate some work by creating a nested span
    with tracer.start_as_current_span("my-sub-operation"): # Create a child span
        print("Inside 'my-sub-operation': doing some work...")

print("Operation complete. Attempting to send traces to Uptrace (if DSN is valid).")

# It's crucial to shut down the tracer provider to ensure all buffered spans
# are flushed and exported to Uptrace before the application exits.
# In long-running applications or web frameworks, this is often handled
# automatically by framework integrations or application shutdown hooks.
trace.get_tracer_provider().shutdown()
print("Tracer provider shut down.")

view raw JSON →