Install & Compatibility
Where this runs
tested against v3.16.3 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 2.152s · 72.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 6.7s · import 1.376s · 71MB
71MB installed
● package 71MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ from google.cloud import logging
Used to create a client for interacting with the Logging API.
CloudLoggingHandler
✓ from google.cloud.logging.handlers import CloudLoggingHandler
Used for explicit, advanced configuration of the logging handler, especially for environments where structured logging to stdout/stderr isn't automatically handled.
Resource
✓ from google.cloud.logging.resource import Resource
Needed when manually defining a monitored resource for log entries, useful for specific cloud functions or custom environments.
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.
import google.cloud.logging
import logging
import os
# For local execution, ensure Application Default Credentials are set up.
# E.g., by running `gcloud auth application-default login` or setting GOOGLE_APPLICATION_CREDENTIALS.
# For deployments on GCP (e.g., Cloud Run, GKE, Compute Engine), credentials are often automatic.
# Optional: Set the project ID explicitly if not running on GCP or if default is incorrect.
# project_id = os.environ.get('GOOGLE_CLOUD_PROJECT', 'your-gcp-project-id')
client = google.cloud.logging.Client()
# Attaches a Cloud Logging handler to the root Python logger.
# All standard Python logging calls (e.g., logging.info, logging.error)
# will now be sent to Google Cloud Logging.
# In serverless environments (Cloud Functions, Cloud Run, GKE), this often
# defaults to StructuredLogHandler, which writes JSON to stdout/stderr.
client.setup_logging(log_level=logging.INFO)
# Use Python's standard logging to send logs
logging.info('This is an info message via standard Python logging.')
logging.warning('This is a warning message with some data.', extra={'json_fields': {'user_id': '123', 'session': 'abc'}})
logging.error('An error occurred!')
# To use the Cloud Logging client directly for more control (e.g., custom log names, resources)
logger = client.logger(name='my-custom-log', labels={'source': 'quickstart'})
logger.log_text('This is a direct log entry to my-custom-log.')
logger.log_struct(
{'message': 'Structured log entry!', 'severity': 'DEBUG', 'component': 'backend'},
severity='DEBUG'
)
print('Logs sent to Google Cloud Logging.')
Debug
Known issues
breakingVersion 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.fixRefer 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.
affects: <3.0.0
gotchaWhen 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.fixExplicitly 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.
affects: All versions (environment dependent)
gotchaProper 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.fixEnsure 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.
affects: All versions
deprecatedPython 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.fixUpgrade 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.
affects: <=1.15.1
Errors
Common errors & fixes
AttributeError: module 'google.cloud' has no attribute 'logging'
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.
fixEnsure `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.
AttributeError: 'module' object has no attribute 'Client'
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.
fixCorrect the import statement to `from google.cloud import logging` and then instantiate the client as `client = logging.Client()`.
The caller does not have permission
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).
fixGrant 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.
AttributeError: 'Logger' object has no attribute 'log_struct'
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`.
fixIf 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. Upgrade
Version history
3.16.3latest on PyPI · released Aug 24, 2026
Audit
Dependencies
PythonrequiredRequires Python version 3.9 or higher.