OpenTelemetry Python distro for Uptrace

uptrace-pythonopen in new window configures opentelemetry-pythonopen in new window to export spans and metrics to Uptrace using OpenTelemetry protocol (OTLP).

Installation

To install uptrace-python:

pip install uptrace

Configuration

You can configure Uptrace client using a DSN (Data Source Name, e.g. https://<key>@uptrace.dev/<project_id>) from the project settings page. Add the following code to the app main file (manage.py for Django):

import uptrace
from opentelemetry import trace

# copy your project DSN here or use UPTRACE_DSN env var
uptrace.configure_opentelemetry(dsn="https://<key>@uptrace.dev/<project_id>")
tracer = trace.get_tracer("app_or_package_name", "1.0.0")

The following configuration options are supported.

OptionDescription
dsnA data source that is used to connect to uptrace.dev. For example, https://<key>@uptrace.dev/<project_id>.
service_nameservice.name resource attribute. For example, myservice.
service_versionservice.version resource attribute. For example, 1.0.0.
resource_attributesAny other resource attributes.
resourceResource contains attributes representing an entity that produces telemetry. Resource attributes are copied to all spans and events.

You can also use environment variables to configure the client:

Env varDescription
UPTRACE_DSNA data source that is used to connect to uptrace.dev. For example, https://<key>@uptrace.dev/<project_id>.
OTEL_RESOURCE_ATTRIBUTESKey-value pairs to be used as resource attributes. For example, service.name=myservice,service.version=1.0.0.
OTEL_PROPAGATORSPropagators to be used as a comma separated list. The default is tracecontext,baggage.

Getting started

Install OpenTelemetry distro, generate your first trace, and click the link in your terminal to open Uptrace. All it takes is a minute of your time.

pip install uptrace
#!/usr/bin/env python3

import uptrace
from opentelemetry import trace

# Configure OpenTelemetry with sensible defaults.
uptrace.configure_opentelemetry(
    # copy your project DSN here or use UPTRACE_DSN env var
    dsn="https://<key>@uptrace.dev/<project_id>",
    service_name="myservice",
    service_version="1.0.0",
)

# Create a tracer. Usually, tracer is a global variable.
tracer = trace.get_tracer("app_or_package_name", "1.0.0")

# Create a root span (a trace) to measure some operation.
with tracer.start_as_current_span("main-operation") as main:
    with tracer.start_as_current_span("child1-of-main") as child1:
        child1.set_attribute("key1", "value1")
        child1.record_exception(ValueError("error1"))

    with tracer.start_as_current_span("child2-of-main") as child2:
        child2.set_attribute("key2", "value2")
        child2.set_attribute("key3", 123.456)

    print("trace:", uptrace.trace_url(main))

# Send buffered spans and free resources.
trace.get_tracer_provider().shutdown()
python3 main.py
trace: https://uptrace.dev/search/<project_id>?q=<trace_id>
  • Step 4. Follow the link to view the trace:

Basic trace

What's next?