Registry / gcp / structlog-gcp

structlog-gcp

library0.5.0pypypi✓ verified 85d ago

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.

gcp observability

pip install structlog-gcp

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · STRUCTLOG-GCP

structlog-gcp

gcppythonv0.5.0

Install

1.6s avg

Import

306ms

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.5.0 · 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.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.258s · 18.7MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.6s · import 0.232s · 19MB

17MB installed

● package 17MB

Code

Verified usage

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

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.

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')

Debug

Known issues

breakingThe 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)`.

affects: <0.1.0

gotchaThe 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.

affects: All versions

gotchaAs 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.

affects: >=0.4.0

gotchaUsing `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()`.

affects: >=0.3.0

gotchaFor 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.

affects: All versions

Upgrade

Version history

0.5.0latest on PyPI · released Jul 13, 2025

Audit

Dependencies

structlogrequiredCore dependency for structured logging framework.

Agent activity

40 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/multani/structlog-gcp#readme ↗

packagehttps://pypi.org/project/structlog-gcp/ ↗

docshttps://github.com/multani/structlog-gcp#readme ↗