{"id":497,"library":"google-cloud-logging","title":"Google Cloud Logging","description":"The `google-cloud-logging` client library for Python allows developers to interact with the Google Cloud Logging API. It facilitates sending and retrieving log entries, managing log sinks, and integrating with Python's standard `logging` module. The library is actively maintained by Google, with version 3.15.0 being the latest, and releases frequently align with updates across the broader Google Cloud Python ecosystem.","status":"active","version":"3.15.0","language":"python","source_language":"en","source_url":"https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-logging","tags":["google-cloud","logging","observability","gcp","cloud-logging"],"install":[{"cmd":"pip install google-cloud-logging","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Requires Python version 3.9 or higher.","package":"Python","optional":false}],"imports":[{"note":"Used to create a client for interacting with the Logging API.","symbol":"Client","correct":"from google.cloud import logging"},{"note":"Used for explicit, advanced configuration of the logging handler, especially for environments where structured logging to stdout/stderr isn't automatically handled.","symbol":"CloudLoggingHandler","correct":"from google.cloud.logging.handlers import CloudLoggingHandler"},{"note":"Needed when manually defining a monitored resource for log entries, useful for specific cloud functions or custom environments.","symbol":"Resource","correct":"from google.cloud.logging.resource import Resource"}],"quickstart":{"code":"import google.cloud.logging\nimport logging\nimport os\n\n# For local execution, ensure Application Default Credentials are set up.\n# E.g., by running `gcloud auth application-default login` or setting GOOGLE_APPLICATION_CREDENTIALS.\n# For deployments on GCP (e.g., Cloud Run, GKE, Compute Engine), credentials are often automatic.\n\n# Optional: Set the project ID explicitly if not running on GCP or if default is incorrect.\n# project_id = os.environ.get('GOOGLE_CLOUD_PROJECT', 'your-gcp-project-id')\nclient = google.cloud.logging.Client()\n\n# Attaches a Cloud Logging handler to the root Python logger.\n# All standard Python logging calls (e.g., logging.info, logging.error)\n# will now be sent to Google Cloud Logging.\n# In serverless environments (Cloud Functions, Cloud Run, GKE), this often\n# defaults to StructuredLogHandler, which writes JSON to stdout/stderr.\nclient.setup_logging(log_level=logging.INFO)\n\n# Use Python's standard logging to send logs\nlogging.info('This is an info message via standard Python logging.')\nlogging.warning('This is a warning message with some data.', extra={'json_fields': {'user_id': '123', 'session': 'abc'}})\nlogging.error('An error occurred!')\n\n# To use the Cloud Logging client directly for more control (e.g., custom log names, resources)\nlogger = client.logger(name='my-custom-log', labels={'source': 'quickstart'})\nlogger.log_text('This is a direct log entry to my-custom-log.')\nlogger.log_struct(\n    {'message': 'Structured log entry!', 'severity': 'DEBUG', 'component': 'backend'},\n    severity='DEBUG'\n)\n\nprint('Logs sent to Google Cloud Logging.')","lang":"python","description":"This quickstart demonstrates how to initialize the `google-cloud-logging` client and integrate it with Python's standard `logging` module. It also shows how to directly use the client for more granular control over log entries, including structured logging. For local development, ensure Application Default Credentials are configured, or explicitly provide a project ID."},"warnings":[{"fix":"Refer to the official 'v3.0.0 Migration Guide' for detailed instructions on updating your code, especially regarding client initialization, structured logging, and direct API usage. The library now natively supports structured JSON logging to stdout/stderr in serverless environments, which may change previous log handling strategies.","message":"Version 3.0.0 introduced significant breaking changes, including major interface updates, enhanced structured logging capabilities, and improved metadata autodetection. Code written for versions prior to 3.0.0 will likely require modification.","severity":"breaking","affected_versions":"<3.0.0"},{"fix":"Explicitly configure standard Python `logging` handlers to send `INFO` and `DEBUG` level logs to `sys.stdout` and `ERROR`/`CRITICAL` logs to `sys.stderr`. For custom loggers, set `logger.propagate = False` to prevent duplicate logs if handlers are attached to both the custom logger and its ancestors.","message":"When running in certain Google Cloud environments (e.g., GKE, Cloud Run, Vertex AI Endpoints), logs directed to `stderr` by default Python `StreamHandler`s are often interpreted by Cloud Logging as `ERROR` severity, regardless of their original level (e.g., `INFO`). This can lead to misleading log severities in the console.","severity":"gotcha","affected_versions":"All versions (environment dependent)"},{"fix":"Ensure the service account associated with your application (or your user account for local testing) has at least the `Logs Writer` role (`roles/logging.logWriter`). Verify network connectivity to `logging.googleapis.com` (firewall rules). For local setup, run `gcloud auth application-default login` or set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to a service account key file.","message":"Proper IAM permissions are crucial. If logs are not appearing in Cloud Logging, the service account or user credentials used by your application may lack the necessary `roles/logging.logWriter` role. For local development, Application Default Credentials (ADC) must be correctly set up.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade your Python environment to version 3.9 or newer. If you must use an older Python version, pin the `google-cloud-logging` dependency to `1.15.1` or an earlier compatible version, but be aware that it will not receive further updates or security patches.","message":"Python versions 2.7 and older are no longer supported. The last version compatible with Python 2.7 was `google-cloud-logging==1.15.1`. Current versions (>=2.0.0) require Python 3.9 or higher.","severity":"deprecated","affected_versions":"<=1.15.1"}],"env_vars":null,"last_verified":"2026-05-12T14:21:54.390Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Ensure `google-cloud-logging` is installed and up-to-date using `pip install --upgrade google-cloud-logging`. If issues persist, try reinstalling in a clean virtual environment.","cause":"The `google-cloud-logging` library is not correctly installed, or there's a package conflict where the `google.cloud` namespace does not properly expose the `logging` submodule.","error":"AttributeError: module 'google.cloud' has no attribute 'logging'"},{"fix":"Correct the import statement to `from google.cloud import logging` and then instantiate the client as `client = logging.Client()`.","cause":"This error occurs when trying to instantiate the `Client` object directly from the `google.cloud` module (e.g., `google.cloud.Client()`) instead of from the specific `google.cloud.logging` module.","error":"AttributeError: 'module' object has no attribute 'Client'"},{"fix":"Grant the 'Logs Writer' role (`roles/logging.logWriter`) to the service account or user associated with your application in the Google Cloud project's IAM settings. For reading logs, grant the 'Logs Viewer' role.","cause":"The service account or user credentials used by your application lack the necessary Identity and Access Management (IAM) permissions to perform the requested logging operation (e.g., writing logs).","error":"The caller does not have permission"},{"fix":"If you want to use structured logging with `log_struct`, create a specific logger client using `logger = client.logger('my_log_name')` and call `logger.log_struct()` on it. If using the standard Python `logging` module, pass structured data as a dictionary in the `extra` argument, or ensure your output is JSON to be parsed as structured logs by Cloud Run/Functions agents.","cause":"This typically happens when attempting to call `log_struct` on a standard Python `logging.Logger` instance after integrating `google-cloud-logging` with `client.setup_logging()`. The `log_struct` method is part of the `google.cloud.logging.Logger` object obtained via `client.logger()`, not the standard library's `Logger`.","error":"AttributeError: 'Logger' object has no attribute 'log_struct'"}],"ecosystem":"pypi","meta_description":null,"install_score":95,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.33,"mem_mb":29.6,"disk_size":"70.9M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.26,"mem_mb":23.7,"disk_size":"69M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.95,"mem_mb":31.2,"disk_size":"75.8M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.75,"mem_mb":25.9,"disk_size":"74M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3,"mem_mb":30.9,"disk_size":"67.2M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.27,"mem_mb":25.7,"disk_size":"65M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.94,"mem_mb":31.4,"disk_size":"66.8M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.34,"mem_mb":26.1,"disk_size":"65M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.94,"mem_mb":29.3,"disk_size":"71.0M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.32,"mem_mb":23.5,"disk_size":"69M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}