# structlog-cloudrun
A [structlog](https://www.structlog.org/) processor for Google Cloud Run logging.
This package provides a structured logging processor that formats log entries to be compatible with Google Cloud Logging when running on Cloud Run.
## Features
- Converts structlog events to Google Cloud Logging format
- Maps Python log levels to Cloud Logging severity levels
- Automatic UTC timestamp generation
- Separates log messages and structured data appropriately
## Installation
Install using pip:
```bash
pip install structlog-cloudrun
```
Or using uv:
```bash
uv add structlog-cloudrun
```
## Quick Start
```python
import structlog
from structlog_cloudrun import CloudRunProcessor
# Configure structlog with CloudRunProcessor
structlog.configure(
processors=[
structlog.contextvars.merge_contextvars,
structlog.processors.add_log_level,
CloudRunProcessor(),
structlog.processors.JSONRenderer(),
],
cache_logger_on_first_use=True,
)
# Use structured logging
logger = structlog.get_logger()
logger.info("User logged in", user_id="12345", method="oauth")
```
This will output JSON formatted for Google Cloud Logging:
```json
{
"severity": "INFO",
"timestamp": "2023-12-07T10:30:00.000000Z",
"textPayload": "User logged in",
"jsonPayload": {
"user_id": "12345",
"method": "oauth"
}
}
```
## Log Format
The processor converts structlog events into Google Cloud Logging's `LogEntry` format:
- **severity**: Mapped from Python log levels (DEBUG, INFO, WARNING, ERROR, CRITICAL)
- **timestamp**: UTC timestamp in ISO format
- **textPayload**: The main log message (from the `event` field)
- **jsonPayload**: All other structured data from the log event
## Severity Mapping
| Python Level | Cloud Logging Severity |
| ------------ | ---------------------- |
| notset | DEFAULT |
| debug | DEBUG |
| info | INFO |
| notice | NOTICE |
| warning | WARNING |
| error | ERROR |
| critical | CRITICAL |
## Requirements
- Python 3.11+
- structlog 25.0.0+
Raw data
{
"_id": null,
"home_page": null,
"name": "structlog-cloudrun",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "cloud-run, gcp, google-cloud, logging, structlog",
"author": null,
"author_email": "Sam Yao <turisesonia@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/9e/8f/920df2714de5096b205f343b84dec91f4421d84c0e2af9c842b1e7786698/structlog_cloudrun-0.1.0.tar.gz",
"platform": null,
"description": "# structlog-cloudrun\n\nA [structlog](https://www.structlog.org/) processor for Google Cloud Run logging.\n\nThis package provides a structured logging processor that formats log entries to be compatible with Google Cloud Logging when running on Cloud Run.\n\n## Features\n\n- Converts structlog events to Google Cloud Logging format\n- Maps Python log levels to Cloud Logging severity levels\n- Automatic UTC timestamp generation\n- Separates log messages and structured data appropriately\n\n## Installation\n\nInstall using pip:\n\n```bash\npip install structlog-cloudrun\n```\n\nOr using uv:\n\n```bash\nuv add structlog-cloudrun\n```\n\n## Quick Start\n\n```python\nimport structlog\nfrom structlog_cloudrun import CloudRunProcessor\n\n# Configure structlog with CloudRunProcessor\nstructlog.configure(\n processors=[\n structlog.contextvars.merge_contextvars,\n structlog.processors.add_log_level,\n CloudRunProcessor(),\n structlog.processors.JSONRenderer(),\n ],\n cache_logger_on_first_use=True,\n)\n\n# Use structured logging\nlogger = structlog.get_logger()\nlogger.info(\"User logged in\", user_id=\"12345\", method=\"oauth\")\n```\n\nThis will output JSON formatted for Google Cloud Logging:\n\n```json\n{\n \"severity\": \"INFO\",\n \"timestamp\": \"2023-12-07T10:30:00.000000Z\",\n \"textPayload\": \"User logged in\",\n \"jsonPayload\": {\n \"user_id\": \"12345\",\n \"method\": \"oauth\"\n }\n}\n```\n\n## Log Format\n\nThe processor converts structlog events into Google Cloud Logging's `LogEntry` format:\n\n- **severity**: Mapped from Python log levels (DEBUG, INFO, WARNING, ERROR, CRITICAL)\n- **timestamp**: UTC timestamp in ISO format\n- **textPayload**: The main log message (from the `event` field)\n- **jsonPayload**: All other structured data from the log event\n\n## Severity Mapping\n\n| Python Level | Cloud Logging Severity |\n| ------------ | ---------------------- |\n| notset | DEFAULT |\n| debug | DEBUG |\n| info | INFO |\n| notice | NOTICE |\n| warning | WARNING |\n| error | ERROR |\n| critical | CRITICAL |\n\n## Requirements\n\n- Python 3.11+\n- structlog 25.0.0+\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A structlog processor for Google Cloud Run logging.",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/yourusername/structlog-cloudrun",
"Issues": "https://github.com/yourusername/structlog-cloudrun/issues",
"Repository": "https://github.com/yourusername/structlog-cloudrun"
},
"split_keywords": [
"cloud-run",
" gcp",
" google-cloud",
" logging",
" structlog"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "24b2bf04fa41222034b5e22e83545d6c77bb80a9bbbab15b88e1644a3803869e",
"md5": "4920bf7cf3c1bdb5247426d0953d0cbb",
"sha256": "8ae7f799c7d4fac088bf9124b859a818f7cb1c802627663320c3b096de1f6ac2"
},
"downloads": -1,
"filename": "structlog_cloudrun-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4920bf7cf3c1bdb5247426d0953d0cbb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 3721,
"upload_time": "2025-09-17T08:38:14",
"upload_time_iso_8601": "2025-09-17T08:38:14.291931Z",
"url": "https://files.pythonhosted.org/packages/24/b2/bf04fa41222034b5e22e83545d6c77bb80a9bbbab15b88e1644a3803869e/structlog_cloudrun-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9e8f920df2714de5096b205f343b84dec91f4421d84c0e2af9c842b1e7786698",
"md5": "b321d2ad2f415d111350731ded0c154a",
"sha256": "72a35af9bfd755d7b65d71589a4f5a38153183d41c26b14c81e1c0ad001508f7"
},
"downloads": -1,
"filename": "structlog_cloudrun-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "b321d2ad2f415d111350731ded0c154a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 27601,
"upload_time": "2025-09-17T08:38:15",
"upload_time_iso_8601": "2025-09-17T08:38:15.629415Z",
"url": "https://files.pythonhosted.org/packages/9e/8f/920df2714de5096b205f343b84dec91f4421d84c0e2af9c842b1e7786698/structlog_cloudrun-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-17 08:38:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "structlog-cloudrun",
"github_not_found": true,
"lcname": "structlog-cloudrun"
}
JSON
