Google Cloud Logging

Common errors

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

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

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

• 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

• pip install google-cloud-logging Install latest version

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

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