Python OpenTelemetry¶
OpenTelemetry (OTel) records information about an application's behavior and sends it to an observability system. This skill explains which telemetry to record, how to add it to Python code, and how to control its cost and exposure of sensitive data.
Use framework and client instrumentation for standard operations such as HTTP requests and database calls. Add manual instrumentation for business operations those integrations cannot describe. The OpenTelemetry Collector receives and processes telemetry; an observability backend stores it and provides queries and visualization.
Signal Selection¶
| Question | Primitive | Typical use |
|---|---|---|
| How often, how slow, how much? | Metric | Rates, error ratios, latency distributions, saturation, alerts |
| Where did this operation spend time or fail? | Trace composed of spans | Request paths, dependency latency, causality across services |
| What discrete event happened, with what details? | Log record | Diagnosis, operational milestones, failures outside a request |
| What happened at a point within this operation? | Span event | A bounded milestone or exception attached to a span |
| Which approved context must travel downstream? | Baggage | Small, non-sensitive context propagated between services |
| Which code consumes CPU or memory? | Profile | Hot functions, allocations, continuous performance analysis |
These primitives serve different purposes. Metrics should measure all relevant operations even when only some traces are retained. Logs can include trace IDs to connect diagnostic details to an operation. Metric exemplars provide similar links for selected measurements without creating a separate time series for each trace.
Baggage carries context between services; it is not itself an exported record. A span event belongs to a trace, while a log record can describe an event independently of a trace.
Reference Map¶
Load only the page needed for the task:
- Application bootstrap, dependencies, resources, OTLP, framework integration, deployment, or shutdown: setup and lifecycle.
- Span boundaries, kinds, events, links, errors, propagation, or sampling: traces.
- Counter versus histogram versus gauge, observable instruments, dimensions, aggregation, or exemplars: metrics.
- Python logging integration, structured events, trace correlation, export, or duplicate records: logs.
- Cross-service metadata, context attachment, trust boundaries, or accidental context leakage: baggage.
- CPU or memory attribution and the emerging OTel profiling signal: profiles.
Shared Concepts¶
OpenTelemetry separates the code that records telemetry from the SDK that processes and exports it. The setup page explains SDK components such as providers, processors, and readers. Across signals, distinguish these kinds of metadata:
| Concept | What it describes | Example |
|---|---|---|
| Resource | The service or instance producing telemetry | service.name=checkout |
| Instrumentation scope | The code responsible for recording telemetry | checkout.telemetry |
| Span or log attribute | A fact about one operation or event | checkout.outcome=success |
| Metric attribute | A group of measurements to aggregate separately | Successes versus failures |
| Baggage | Context made available to downstream services | An approved traffic class |
Configuration Defaults¶
Configure the SDK once during application startup and shut it down after the final application work. Choose either explicit SDK setup or a zero-code launcher that sets it up for you. Reusable libraries record telemetry through the API and named Python loggers; they do not configure global providers or export destinations.
Use a stable service.name and the same resource identity across signals. Give the instrumentation a fixed scope name, such as checkout.telemetry, rather than a name that changes per request.
Export traces and logs in batches, and metrics at regular intervals. This keeps network export off the request path. Prefer the OpenTelemetry Protocol (OTLP) through a Collector; direct backend export is reasonable when deployment constraints justify it. Supply credentials through deployment configuration, not source code.
Record only approved fields. Do not capture payloads, tokens, query parameters, SQL parameters, or exception messages indiscriminately. Limit the possible values of metric attributes and decide which context may leave the service. Sampling reduces volume; it does not make sensitive data safe to export.
What to Verify¶
A telemetry change should answer the intended operational question and demonstrate delivery from the application to the backend. Verify the selected signals using representative successful and failed operations: span relationships, metric values and units, log-to-trace links, and final export during shutdown.
Also check behavior when the Collector is unavailable. Application work should continue, and export timeouts, queues, and shutdown waits should stay within configured limits.
Tests can use providers local to the test and in-memory exporters or readers without changing global configuration or contacting a backend. Inspect recorded fields for sensitive data and count records to detect duplicate instrumentation. State which package versions were checked: logs, community instrumentation packages, semantic conventions, and profiles have different stability guarantees.
Primary sources