Structlog Google Cloud Logging Processors

Warnings

• breaking The API for building processors changed significantly in v0.1.0. The `StructlogGCP` class was removed, and `build_processors` became a top-level function.
  Fix: Replace `gcp_logs = structlog_gcp.StructlogGCP(); structlog.configure(processors=gcp_logs.build_processors())` with `processors = structlog_gcp.build_processors(); structlog.configure(processors=processors)`.
• gotcha The library primarily formats logs to stdout in Google Cloud Logging's JSON format. It does NOT automatically send logs to the Google Cloud Logging API. An external agent (e.g., in GKE, Cloud Run, Cloud Functions) is expected to collect and send these stdout logs.
  Fix: Understand that `structlog-gcp` is a formatter, not a sender. Ensure your deployment environment is configured to collect and forward stdout logs to Google Cloud Logging.
• gotcha As of v0.4.0, when logging an event within an exception handler using `logger.$LEVEL(..., exception=exc)`, the log level will be the one specified by the caller (e.g., `info`, `warning`), rather than always overriding to `CRITICAL`.
  Fix: Review exception logging logic to ensure desired log levels are explicitly set or understood. If `CRITICAL` is always needed for exceptions, set the level explicitly.
• gotcha Using `structlog_gcp.build_gcp_processors()` (introduced in v0.3.0) provides only GCP-specific processors, omitting standard structlog processors like a JSON renderer. This requires manual addition of a JSON renderer and other desired base processors to function correctly.
  Fix: If using `build_gcp_processors()`, explicitly add a JSON renderer (e.g., `structlog.processors.JSONRenderer()`) and any other necessary processors to your chain. For default behavior, continue using `structlog_gcp.build_processors()`.
• gotcha For an exception to be reported to Google Error Reporting, the exception object itself must be passed to the logger (e.g., `logger.error('message', exception=e)` or `logger.exception('message')`). Simply logging the exception's string representation will not trigger Error Reporting.
  Fix: Always pass the actual exception object using the `exception` keyword argument or use `logger.exception()` for automatic Error Reporting integration.

Install

• pip install structlog-gcp Install structlog-gcp

Imports

• build_processors

  from structlog_gcp import build_processors

• build_gcp_processors

  from structlog_gcp import build_gcp_processors

  For advanced users needing fine-grained control; requires manual addition of a JSON renderer.

Quickstart

Configures structlog to use the Google Cloud Logging compatible processors. Logs are printed to stdout as JSON, suitable for ingestion by Google Cloud Logging. Exceptions passed with `exception=e` are formatted for Google Error Reporting.

import structlog
import structlog_gcp
import os

# Configure structlog with GCP processors
processors = structlog_gcp.build_processors(
    service=os.environ.get('K_SERVICE', 'my-app-service'),
    version=os.environ.get('K_REVISION', 'v1.0.0')
)

structlog.configure(processors=processors)

logger = structlog.get_logger().bind(request_id='abc-123')

logger.info('User login successful', username='testuser', user_id=123)

try:
    1 / 0
except ZeroDivisionError as e:
    logger.error('An error occurred during calculation', error_type='division_by_zero', exception=e)
    logger.warning('This warning will not be reported to Error Reporting if exception object is not passed.')

# Example of binding context variables (requires 'structlog.contextvars.merge_contextvars' in processors)
# logger.bind(correlation_id='xyz-456')
# logger.info('Operation step completed')