OpenTelemetry Python distro for Uptrace

This document explains how to configure OpenTelemetry Python SDK to export spans and metrics to Uptrace using OTLP/HTTP.

To learn about OpenTelemetry API, see OpenTelemetry Python Tracing APIopen in new window and OpenTelemetry Python Metrics APIopen in new window.

OpenTelemetry Python

To install uptrace-python:

pip install uptrace

Configuration

You can configure Uptrace client using a DSN (Data Source Name, e.g. https://<token>@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://<token>@uptrace.dev/<project_id>",
  service_name="myservice",
  service_version="1.0.0",
  deployment_environment="production",
)

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://<token>@uptrace.dev/<project_id>.
service_nameservice.name resource attribute. For example, myservice.
service_versionservice.version resource attribute. For example, 1.0.0.
deployment_environmentdeployment.environment resource attribute. For example, production.
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://<token>@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://<token>@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/traces/<trace_id>
  • Step 4. Follow the link to view the trace:

Basic trace

Application servers

Because OpenTelemetry spawns thread to exports spans, it does not work well with application servers like Gunicorn and uWSGI that use pre-forking model to serve requests. In such cases, you should configure OpenTelemetry from post-fork hooks provided by those servers.

Gunicorn

With Gunicorn, use post_forkopen in new window hook:

import uptrace

def post_fork(server, worker):
    uptrace.configure_opentelemetry(...)

uWSGI

With uWSGI, use postforkopen in new window decorator:

from uwsgidecorators import postfork
import uptrace

@postfork
def init_tracing():
    uptrace.configure_opentelemetry(...)

SSL

If you are getting SSL errors like this:

ssl_transport_security.cc:1468] Handshake failed with fatal error SSL_ERROR_SSL: error:1000007d:SSL routines:OPENSSL_internal:CERTIFICATE_VERIFY_FAILED

Try to use different root certificates as a workaroundopen in new window:

export GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=/etc/ssl/certs/ca-certificates.crt

What's next?

Tutorials:

Last Updated: