Install & Compatibility
Where this runs
tested against v1.41.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 1.058s · 52.2MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 5.1s · import 0.674s · 50MB
50MB installed
● package 50MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
configure_opentelemetry
✓ from uptrace import configure_opentelemetry
✗ from opentelemetry.sdk.trace import configure_opentelemetry
`configure_opentelemetry` is a Uptrace-specific helper, not part of the core OpenTelemetry SDK.
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.")
uptrace --version
Errors
Common errors & fixes
No spans are visible in Uptrace despite running the application.
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.
fix1. 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'
The `uptrace` package is not installed in the active Python environment.
fixInstall 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)
`configure_opentelemetry` is a convenience function provided specifically by the `uptrace` distribution, not a standard component of the core `opentelemetry-sdk`.
fixImport `configure_opentelemetry` directly from the `uptrace` package: `from uptrace import configure_opentelemetry`.
Upgrade
Version history
1.41.0latest on PyPI · released Apr 16, 2026
Audit
Dependencies
No dependency data recorded yet.