{"id":6901,"library":"structlog-gcp","title":"Structlog Google Cloud Logging Processors","description":"structlog-gcp is a Python library that provides a set of structlog processors designed to output logs in the Google Cloud Logging format. It is intended for applications running in Google Cloud environments like GKE or Cloud Functions, facilitating easy integration with Google Cloud Logging and Error Reporting. The library, currently at version 0.5.0, has an active development cycle with regular releases addressing bug fixes and new features.","status":"active","version":"0.5.0","language":"en","source_language":"en","source_url":"https://github.com/multani/structlog-gcp","tags":["structlog","google cloud","gcp","logging","cloud logging","error reporting"],"install":[{"cmd":"pip install structlog-gcp","lang":"bash","label":"Install structlog-gcp"}],"dependencies":[{"reason":"Core dependency for structured logging framework.","package":"structlog","optional":false}],"imports":[{"symbol":"build_processors","correct":"from structlog_gcp import build_processors"},{"note":"For advanced users needing fine-grained control; requires manual addition of a JSON renderer.","symbol":"build_gcp_processors","correct":"from structlog_gcp import build_gcp_processors"}],"quickstart":{"code":"import structlog\nimport structlog_gcp\nimport os\n\n# Configure structlog with GCP processors\nprocessors = structlog_gcp.build_processors(\n    service=os.environ.get('K_SERVICE', 'my-app-service'),\n    version=os.environ.get('K_REVISION', 'v1.0.0')\n)\n\nstructlog.configure(processors=processors)\n\nlogger = structlog.get_logger().bind(request_id='abc-123')\n\nlogger.info('User login successful', username='testuser', user_id=123)\n\ntry:\n    1 / 0\nexcept ZeroDivisionError as e:\n    logger.error('An error occurred during calculation', error_type='division_by_zero', exception=e)\n    logger.warning('This warning will not be reported to Error Reporting if exception object is not passed.')\n\n# Example of binding context variables (requires 'structlog.contextvars.merge_contextvars' in processors)\n# logger.bind(correlation_id='xyz-456')\n# logger.info('Operation step completed')","lang":"python","description":"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."},"warnings":[{"fix":"Replace `gcp_logs = structlog_gcp.StructlogGCP(); structlog.configure(processors=gcp_logs.build_processors())` with `processors = structlog_gcp.build_processors(); structlog.configure(processors=processors)`.","message":"The API for building processors changed significantly in v0.1.0. The `StructlogGCP` class was removed, and `build_processors` became a top-level function.","severity":"breaking","affected_versions":"<0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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`.","severity":"gotcha","affected_versions":">=0.4.0"},{"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()`.","message":"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.","severity":"gotcha","affected_versions":">=0.3.0"},{"fix":"Always pass the actual exception object using the `exception` keyword argument or use `logger.exception()` for automatic Error Reporting integration.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}