OpenTelemetry Instrumentation for Logging

opentelemetry-instrumentation-logging automatically instruments Python’s standard logging module so log records carry OpenTelemetry trace context. Once installed, it patches the active log record factory to attach otelSpanID, otelTraceID, otelTraceSampled, and otelServiceName attributes to every log record emitted while a span is active.

This lets log lines be correlated with distributed traces in an observability backend without hand-wiring trace IDs into log statements. It supports both an opt-in inject_trace_context mode that adds the attributes silently, and a set_logging_format mode that also reconfigures the root logging format to print those attributes inline.

What You Get

• A LoggingInstrumentor that patches the stdlib logging record factory
• Opt-in injection of otelSpanID, otelTraceID, otelTraceSampled, and otelServiceName onto log records
• Automatic logging.basicConfig() reconfiguration via set_logging_format=True
• An auto-installed logging handler that forwards records to the OpenTelemetry SDK’s logger provider
• Environment-variable configuration (OTEL_PYTHON_LOG_CORRELATION, OTEL_PYTHON_LOG_LEVEL, etc.) alongside code-based options

Common Use Cases

• Correlating application log lines with distributed traces in an observability backend
• Adding trace/span IDs to logs without changing every log call site
• Feeding structured application logs into an OpenTelemetry Collector pipeline
• Standardizing log correlation across microservices that share OTel instrumentation

Under The Hood

Architecture — the instrumentor subclasses BaseInstrumentor from opentelemetry-instrumentation and, on _instrument(), wraps the stdlib’s logging.getLogRecordFactory() with a closure that stamps trace/span identifiers from get_current_span() onto each new LogRecord before restoring the original factory on _uninstrument(); a separate _setup_logging_handler() (in handler.py) optionally attaches a handler that forwards records to the configured LoggerProvider. Tech Stack — pure Python, depending only on opentelemetry-api, opentelemetry-instrumentation, and opentelemetry-semantic-conventions from the same monorepo, with no external runtime dependencies; built with hatchling and versioned in lockstep with the rest of the contrib release train. Code Quality — covered by three test files (test_handler.py, test_logging.py, test_logging_handler_recursion.py) totaling over 1,400 lines, including a dedicated regression test for handler recursion, plus a benchmarks/ directory measuring the logging handler’s overhead. API Design — a single LoggingInstrumentor().instrument(...) call with clearly named boolean flags (inject_trace_context, set_logging_format) keeps adoption to one line for the common case, while environment variables mirror every code-level option for container/config-driven deployments.