OpenCensus Logging Integration

Warnings

• breaking The OpenCensus project, including `opencensus-ext-logging`, has been officially deprecated in favor of OpenTelemetry. OpenCensus will no longer receive new features or security updates, and users are strongly encouraged to migrate.
  Fix: Migrate to OpenTelemetry using its Python SDK and relevant instrumentation. OpenTelemetry provides bridges for incremental migration.
• deprecated OpenCensus Azure Monitor exporters, which commonly leverage `opencensus-ext-logging` for log correlation, are also deprecated and will be officially unsupported by September 2024.
  Fix: Migrate to the Azure Monitor OpenTelemetry Distro or the Azure Monitor OpenTelemetry exporters for continued support.
• gotcha The `opencensus-ext-logging` integration only affects Python `logging` instances created *after* `config_integration.trace_integrations(['logging'])` has been called. Loggers initialized before this configuration will not be enriched.
  Fix: Call `config_integration.trace_integrations(['logging'])` at the very beginning of your application startup, before any loggers you wish to instrument are instantiated.
• gotcha When using `opencensus-ext-logging` in conjunction with certain `logging.Handler` implementations (e.g., `AzureLogHandler` from `opencensus-ext-azure`), there have been reports of recursive logging issues, which can lead to excessive logging or application crashes.
  Fix: If encountering recursive logging with `AzureLogHandler`, try initializing it with `enable_local_storage=False`. The recommended long-term solution is to migrate to OpenTelemetry.

Install

• pip install opencensus-ext-logging Install stable version

Imports

• config_integration

  from opencensus.trace import config_integration

Quickstart

This quickstart demonstrates how to enable the OpenCensus logging integration and how log messages are enriched with `traceId` and `spanId` when an OpenCensus trace span is active. The `PrintExporter` is used to visualize the trace information, and the standard Python logging handler outputs the enriched log records.

import logging
import os
from opencensus.trace import config_integration
from opencensus.trace import tracer as tracer_module
from opencensus.trace.exporters import PrintExporter
from opencensus.trace.samplers import AlwaysOnSampler

# 1. Configure the logging integration
# This must be done *before* loggers are created for existing loggers to be affected.
config_integration.trace_integrations(['logging'])

# 2. Set up a basic Python logger
logger = logging.getLogger(__name__)
logger.setLevel(logging.INFO)
handler = logging.StreamHandler()
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - TraceId: %(traceId)s - SpanId: %(spanId)s - %(message)s')
handler.setFormatter(formatter)
logger.addHandler(handler)

# 3. Set up an OpenCensus tracer with an exporter (e.g., PrintExporter)
# This will activate trace context, making trace and span IDs available for logging.
exporter = PrintExporter()
sampler = AlwaysOnSampler()
tracer = tracer_module.Tracer(exporter=exporter, sampler=sampler)

logger.info("This log message will not have trace/span IDs yet as no span is active.")

# 4. Use the tracer to create a span to enable trace context propagation
with tracer.span(name='my_operation') as span:
    logger.info("This log message should now have trace and span IDs.")
    with tracer.span(name='sub_operation'):
        logger.warning("Another log message within a sub-span.")

logger.info("This log message is outside the span and will not have trace/span IDs from the active span.")