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 API and OpenTelemetry Python Metrics API.

• OpenTelemetry Python
• Configuration
• Getting started
• Application servers
  • Gunicorn
  • uWSGI
• SSL
• What's next?

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.

Option	Description
dsn	A data source that is used to connect to uptrace.dev. For example, https://<token>@uptrace.dev/<project_id>.
service_name	service.name resource attribute. For example, myservice.
service_version	service.version resource attribute. For example, 1.0.0.
deployment_environment	deployment.environment resource attribute. For example, production.
resource_attributes	Any other resource attributes.
resource	Resource 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 var	Description
UPTRACE_DSN	A data source that is used to connect to uptrace.dev. For example, https://<token>@uptrace.dev/<project_id>.
OTEL_RESOURCE_ATTRIBUTES	Key-value pairs to be used as resource attributes. For example, service.name=myservice,service.version=1.0.0.
OTEL_PROPAGATORS	Propagators 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.

• Step 0. Create an Uptrace project to obtain a DSN (connection string), for example, https://<token>@uptrace.dev/<project_id>.

• Step 1. Install uptrace-python:

pip install uptrace

• Step 2. Copy the code to main.py replacing the <dsn>:

#!/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()

• Step 3. Run the example to get a link for the generated trace:

python3 main.py
trace: https://uptrace.dev/traces/<trace_id>

• Step 4. Follow the link to view the 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_fork hook:

import uptrace

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

uWSGI

With uWSGI, use postfork 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 workaround:

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

What's next?

• Look for instrumentations and browse examples.
• Learn about Tracing API and Metrics API to create your own instrumentations.

Tutorials:

• OpenTelemetry guide for Django and PostgreSQL/MySQL
• OpenTelemetry guide for Flask and SQLAlchemy