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
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: