Registry / observability / opentelemetry-instrumentation-logging

opentelemetry-instrumentation-logging

JSON →
library0.61b0pypypiunverified

The `opentelemetry-instrumentation-logging` library provides automatic instrumentation for Python's standard `logging` module. It converts native Python log messages into OpenTelemetry logs, enabling correlation with traces and metrics, and facilitates their export to an observability backend. Part of the `opentelemetry-python-contrib` project, this library is currently in beta (version 0.61b0) and undergoes regular releases as part of the broader OpenTelemetry Python ecosystem.

observabilityhttp-networking
pip install opentelemetry-instrumentation-logging opentelemetry-sdk opentelemetry-exporter-otlp
Install & Compatibility
Where this runs
tested against v0.63b1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.930 runs
installs and imports cleanly · install 0.0s · import 0.420s · 52MB
glibc
py 3.103.930 runs
installs and imports cleanly · install 4.9s · import 0.384s · 50MB
49MB installed
● package 49MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

LoggingInstrumentor
from opentelemetry.instrumentation.logging import LoggingInstrumentor
LoggerProvider
from opentelemetry.sdk._logs import LoggerProvider
BatchLogRecordProcessor
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
OTLPLogExporter
from opentelemetry.exporter.otlp.proto.grpc._log_exporter import OTLPLogExporter

This quickstart demonstrates how to set up `opentelemetry-instrumentation-logging` to capture standard Python log messages and export them. It configures a `LoggerProvider` with a `ConsoleLogRecordExporter` for easy viewing, enables the `LoggingInstrumentor` to inject trace context, and shows a log message emitted within an active span for correlation.

import logging from opentelemetry import trace from opentelemetry._logs import set_logger_provider from opentelemetry.sdk._logs import LoggerProvider from opentelemetry.sdk._logs.export import BatchLogRecordProcessor, ConsoleLogRecordExporter from opentelemetry.sdk.resources import Resource from opentelemetry.instrumentation.logging import LoggingInstrumentor # Configure a basic logger logging.basicConfig(level=logging.INFO) logger = logging.getLogger(__name__) # 1. Configure OpenTelemetry Resource resource = Resource.create({ "service.name": "my-python-logging-app", "service.instance.id": "instance-1" }) # 2. Configure LoggerProvider with a processor and exporter # For demonstration, using ConsoleLogRecordExporter to print to stdout # In a real application, you'd use OTLPLogExporter or another backend exporter. log_exporter = ConsoleLogRecordExporter() log_processor = BatchLogRecordProcessor(log_exporter) logger_provider = LoggerProvider(resource=resource) logger_provider.add_log_record_processor(log_processor) set_logger_provider(logger_provider) # 3. Instrument the standard logging module # set_logging_format=True enables trace context injection into log format LoggingInstrumentor().instrument(set_logging_format=True) # 4. Use standard logging, which will now be captured by OpenTelemetry logger.info("This is a regular Python log message.") # 5. Demonstrate log correlation with an active trace span tracer = trace.get_tracer("my-tracer") with tracer.start_as_current_span("my-operation") as span: span.set_attribute("operation.id", "xyz123") logger.warning("This log message is inside a span, so it should be correlated.") # 6. Shut down the logger provider to ensure all logs are exported logger_provider.shutdown() print("Logs sent to console (or configured exporter).")
opentelemetry-instrument --version
Debug
Known issues
breakingThe library is currently in beta (`0.x.y` versioning). While stable for many use cases, its API is subject to change, and breaking changes may occur in minor or patch releases.
fix
Review release notes for each update. Pin dependencies to specific versions (`==0.x.y`) in production to control updates.
affects: All 0.x.y beta versions
gotchaCalling `LoggingInstrumentor().uninstrument()` can corrupt the standard Python `logging` module's log factory linked list, potentially breaking other logging handlers or custom log record factories that were set after `LoggingInstrumentor`.
fix
Avoid calling `uninstrument()` if possible. If dynamic instrumentation/uninstrumentation is strictly necessary, carefully evaluate its impact on other logging components and consider alternative approaches like logging filters or custom loggers that do not rely on modifying the global log factory. Refer to GitHub Issue #3808 for context.
affects: All 0.x.y beta versions (at least up to 0.61b0)
gotchaIf you manually call `logging.basicConfig()` and are not relying on the `OTEL_PYTHON_LOG_CORRELATION` environment variable to configure the logging format, you *must* ensure `LoggingInstrumentor().instrument()` is called *before* `logging.basicConfig()` to avoid `KeyError` exceptions when attempting to inject trace context variables.
fix
Ensure `LoggingInstrumentor().instrument(set_logging_format=True)` is called early in your application's startup, prior to any custom `logging.basicConfig()` calls that use trace context variables (e.g., `%(otelTraceID)s`).
affects: All 0.x.y beta versions
deprecatedThis package provides a logging handler to replace a deprecated `LoggingHandler` previously available in `opentelemetry-sdk`. If `opentelemetry-instrumentation-logging` is installed, you should *not* set the `OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED` environment variable to `true`, as this variable is intended for the *deprecated* SDK handler and can cause confusion or conflicts.
fix
Install `opentelemetry-instrumentation-logging` and call `LoggingInstrumentor().instrument()` (or rely on auto-instrumentation). Avoid using the `OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED` environment variable if you are using this package.
affects: Versions where `opentelemetry-sdk` deprecated its internal `LoggingHandler`.
gotchaSimply installing `opentelemetry-instrumentation-logging` and calling `instrument()` is not sufficient to export logs. You must also configure a `LoggerProvider`, add a `LogRecordProcessor`, and specify a `LogExporter` (e.g., `OTLPLogExporter`) to direct your OpenTelemetry logs to an observability backend.
fix
Always follow the OpenTelemetry logging setup by creating a `Resource`, `LoggerProvider`, `LogRecordProcessor`, and `LogExporter`, and setting the global logger provider via `set_logger_provider()`.
affects: All versions
Upgrade
Version history
0.63b1latest on PyPI
Audit
Dependencies
opentelemetry-apirequiredCore OpenTelemetry API for defining telemetry.
opentelemetry-sdkrequiredCore OpenTelemetry SDK for processing and exporting telemetry.
opentelemetry-exporter-otlpoptionalCommon exporter for sending logs via OTLP (OpenTelemetry Protocol).
Agent activity
9 hits · last 30 days
ahrefsbot
3
node
2
Amazon
1
googlebot
1
seranking-bot
1
Resources