Instrument a Python application
If you need process-level telemetry for Python, follow this guide to set up the upstream OpenTelemetry SDK for Python for Application Observability.
Recommended setup for Grafana Cloud
Grafana Labs recommends setting up OpenTelemetry components, including instrumentation and an OpenTelemetry Collector distribution, using one of the Grafana Cloud onboarding workflows. These opinionated guides make it easy to get started and include all the binaries, configuration, and connection parameters you need to set up OpenTelemetry for Grafana Cloud.
Install the SDK
Before you begin, ensure you have a Python 3 development environment and a Python application to instrument.
Run the following command in your project folder:
pip install "opentelemetry-distro[otlp]"
opentelemetry-bootstrap -a installGlobal Interpreter Lock
The OpenTelemetry Python SDK uses the Global Interpreter Lock (GIL), which can cause performance issues with web servers that spawn multiple processes to serve requests in parallel.
To address this, register a post fork hook that runs after each worker process is forked.
The following code sample shows a post fork hook for Gunicorn:
import logging
from uuid import uuid4
from opentelemetry import metrics, trace
from opentelemetry.exporter.otlp.proto.grpc._log_exporter import (
OTLPLogExporter,
)
from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import (
OTLPMetricExporter,
)
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
OTLPSpanExporter,
)
# support for logs is currently experimental
from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.resources import SERVICE_INSTANCE_ID
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
# your gunicorn config here
# bind = "127.0.0.1:8000"
collector_endpoint = "http://localhost:4317"
def post_fork(server, worker):
server.log.info("Worker spawned (pid: %s)", worker.pid)
resource = Resource.create(
attributes={
# each worker needs a unique service.instance.id to distinguish the created metrics in prometheus
SERVICE_INSTANCE_ID: str(uuid4()),
"worker": worker.pid,
}
)
tracer_provider = TracerProvider(resource=resource)
tracer_provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter(endpoint=collector_endpoint)))
trace.set_tracer_provider(tracer_provider)
metrics.set_meter_provider(
MeterProvider(
resource=resource,
metric_readers=[(PeriodicExportingMetricReader(
OTLPMetricExporter(endpoint=collector_endpoint)
))],
)
)
logger_provider = LoggerProvider(resource=resource)
logger_provider.add_log_record_processor(BatchLogRecordProcessor(OTLPLogExporter(endpoint=collector_endpoint)))
logging.getLogger().addHandler(LoggingHandler(level=logging.NOTSET, logger_provider=logger_provider))Run the Gunicorn script using the following command: gunicorn app -c gunicorn.conf.py.
Note
To register a post fork hook for other web servers, such as uWSGI, add the
@postforkdecorator to your hook function.
Run your application
Run your application with the following command:
OTEL_RESOURCE_ATTRIBUTES="service.name=<name>,service.namespace=<namespace>,deployment.environment=<environment>" \
OTEL_EXPORTER_OTLP_ENDPOINT=<endpoint> \
OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf" \
opentelemetry-instrument <your_run_command>Replace variables in <...> with values specific to your application and backend. For more details, see the
OpenTelemetry service attributes documentation.
<name>: your service name, for example,shoppingcart<namespace>: a string to group related services, such asecommercefor a team that manages several services<environment>: the deployment environment, for example, theproductiondeployment tier
Some backends, such as Grafana Cloud, also require you to set authentication headers in the OTEL_EXPORTER_OTLP_HEADERS environment variable.
Example application
See the Rolldice service for a complete example setup.