Google Cloud Logging

3.15.0 verified Tue May 12 auth: no python install: verified quickstart: stale

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.

pip install google-cloud-logging

Common errors

error AttributeError: module 'google.cloud' has no attribute 'logging' ↓

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.

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.

error AttributeError: 'module' object has no attribute '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.

fix

Correct the import statement to from google.cloud import logging and then instantiate the client as client = logging.Client().

error The caller does not have permission ↓

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

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.

error AttributeError: 'Logger' object has no attribute 'log_struct' ↓

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

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.

Warnings

breaking 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. ↓

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.

gotcha 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. ↓

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.

gotcha 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. ↓

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.

deprecated 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. ↓

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.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 2.33s 70.9M

3.10 slim (glibc) - - 1.26s 69M

3.11 alpine (musl) - - 2.95s 75.8M

3.11 slim (glibc) - - 1.75s 74M

3.12 alpine (musl) - - 3.00s 67.2M

3.12 slim (glibc) - - 2.27s 65M

3.13 alpine (musl) - - 2.94s 66.8M

3.13 slim (glibc) - - 2.34s 65M

3.9 alpine (musl) - - 1.94s 71.0M

3.9 slim (glibc) - - 1.32s 69M

Imports

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.

Quickstart stale last tested: 2026-04-23

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