Registry / observability / uptrace

uptrace

JSON →
library1.41.0pypypi✓ verified 86d ago

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.

pip install uptrace
INSTALL
IMPORT
SIG · UPTRACE
U
uptrace
observabilitypythonv1.41.0
Install
5.1s avg
Import
866ms
Disk
50MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 1.058s · 52.2MB
glibc
py 3.103.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
Debug
Known issues
gotchaOpenTelemetry 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.
affects: All
gotchaIncorrect 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>`.
affects: All
gotchaAutomatic 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.
affects: All
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.
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'
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)
`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`.
Upgrade
Version history
1.41.0latest on PyPI · released Apr 16, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
19 hits · last 30 days
node
18
OpenAI (training)
1
Resources
uptrace — pip install uptrace · libregistry