Registry / observability / opentelemetry-exporter-gcp-logging

opentelemetry-exporter-gcp-logging

JSON →
library1.15.0a0pypypi✓ verified 28d ago

The `opentelemetry-exporter-gcp-logging` library provides an OpenTelemetry Log exporter that sends log data to Google Cloud Logging. It's part of the OpenTelemetry Python Contrib project for Google Cloud operations. The current version is 1.11.0a0, and releases generally follow the OpenTelemetry Python SDK's release cadence, with specific updates for Google Cloud integration.

pip install opentelemetry-exporter-gcp-logging
INSTALL
IMPORT
SIG · OPENTELEMETRY-EXPO
O
opentelemetry-exporter-gcp-logging
observabilitypythonv1.15.0a0
Install
6.3s avg
Import
1894ms
Disk
75MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v1.15.0a0 · 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
musl
py 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 2.282s · 75.9MB
glibc
py 3.10–3.95 runs
installs and imports cleanly · install 6.3s · import 1.506s · 74MB
75MB installed
● package 75MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

CloudLoggingExporter
✓ from opentelemetry.exporter.cloud_logging import CloudLoggingExporter

This quickstart demonstrates how to configure the `CloudLoggingExporter` to send Python logs to Google Cloud Logging. It includes examples for both the traditional RPC-based export (using `BatchLogRecordProcessor`) and the recommended structured JSON export to stdout (using `SimpleLogRecordProcessor`), which is more efficient when running in GCP environments with a Cloud Logging agent.

import logging from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler from opentelemetry.sdk._logs.export import BatchLogRecordProcessor, SimpleLogRecordProcessor from opentelemetry.sdk.resources import Resource from opentelemetry._logs import set_logger_provider from opentelemetry.exporter.cloud_logging import CloudLoggingExporter # Configure OpenTelemetry LoggerProvider resource = Resource.create( { "service.name": "my-python-app", "service.instance.id": "instance-1", } ) logger_provider = LoggerProvider(resource=resource) set_logger_provider(logger_provider) # --- Example 1: Exporting via RPC (default for older versions, or if structured_json_file is not set) --- exporter_rpc = CloudLoggingExporter(default_log_name='my_app_logs_rpc') logger_provider.add_log_record_processor(BatchLogRecordProcessor(exporter_rpc)) # --- Example 2: Exporting as structured JSON to stdout (recommended for GCP environments >= v1.11.0) --- # This is more efficient for environments with Cloud Logging agent that scrapes stdout exporter_json = CloudLoggingExporter(default_log_name='my_app_logs_json', structured_json_file=True) logger_provider.add_log_record_processor(SimpleLogRecordProcessor(exporter_json)) # Simple processor is often sufficient for stdout export # Attach OTLP handler to the root logger handler = LoggingHandler(level=logging.INFO, logger_provider=logger_provider) logging.getLogger().addHandler(handler) # Create a namespaced logger for your application # It's recommended not to use the root logger with OTLP handler directly for app logs app_logger = logging.getLogger("my_app_module") app_logger.info("This is an info log with OTel context!") app_logger.warning("A warning occurred: %s", "something went wrong") # Logs will be exported asynchronously by BatchLogRecordProcessor # For SimpleLogRecordProcessor, logs are sent immediately # It's good practice to shut down the logger provider when the application exits # This ensures all buffered logs are flushed. # In a real application, you'd typically do this in a graceful shutdown hook. logger_provider.shutdown() print("Logs sent to Cloud Logging (or stdout for structured JSON exporter).")
Debug
Known issues
breakingAs of v1.11.0a0, the `CloudLoggingExporter` defaults to outputting structured JSON to stdout via `structured_json_file=True` if `structured_json_file` is not explicitly set to `False` or if `exporter.export` is called directly without it. This changes the underlying mechanism of log export from direct RPC calls and assumes presence of a Cloud Logging agent to scrape stdout. If you relied on direct RPC behavior or are not in a compatible GCP environment, explicitly set `structured_json_file=False` or revert to an older version.
fix
If direct RPC export is needed, instantiate `CloudLoggingExporter` with `structured_json_file=False`. For GCP environments, structured JSON to stdout is generally preferred, so ensure your deployment has a suitable Cloud Logging agent configured.
affects: >=1.11.0a0
breakingThere are known compatibility constraints with newer OpenTelemetry SDK versions. `opentelemetry-exporter-gcp-logging` v1.11.0a0 has an upper bound set on `opentelemetry-sdk` due to potential breaking changes in the SDK's logging API. Exceeding the specified SDK version range can lead to runtime errors.
fix
Always check the project's `pyproject.toml` or `setup.py` (e.g., `pyproject.toml` often specifies `opentelemetry-sdk < 1.40.0, >= 1.20.0`) for the exact compatible `opentelemetry-sdk` version range and ensure your environment adheres to it. Upgrade `opentelemetry-exporter-gcp-logging` if a newer SDK version is required.
affects: All versions
gotchaEnsure the Google Cloud service account used by your application or host environment has the `roles/logging.logWriter` IAM role. Missing this permission is a common cause of logs failing to appear in Cloud Logging.
fix
Grant the `Logging Log Writer` role (`roles/logging.logWriter`) to the service account associated with your application's environment (e.g., Compute Engine default service account, GKE Workload Identity service account, or a service account key file).
affects: All versions
gotchaWhile manual resource attribute creation is shown for `Resource.create()`, consider using `opentelemetry-resourcedetector-gcp` for automatic detection of environment-specific resource attributes when running in Google Cloud environments (e.g., GCE, GKE, Cloud Run). This enriches your telemetry data automatically with valuable metadata.
fix
Install `opentelemetry-resourcedetector-gcp` and integrate it into your `LoggerProvider` setup to automatically populate resource attributes relevant to your GCP environment.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'opentelemetry.exporter.cloud_logging'
The Python package for the Google Cloud Logging exporter, `opentelemetry-exporter-gcp-logging`, is not installed or the import path is incorrect. OpenTelemetry Python SDK uses a modular structure, requiring specific exporter packages.
fix
Install the correct package using `pip install opentelemetry-exporter-gcp-logging` and ensure the import statement is `from opentelemetry.exporter.cloud_logging import CloudLoggingExporter`.
google.auth.exceptions.DefaultCredentialsError: Could not automatically determine credentials.
The application lacks valid Google Cloud authentication credentials in its environment to authenticate with GCP services. This often happens when running outside a configured GCP environment (like GCE, GKE, Cloud Run) or when `GOOGLE_APPLICATION_CREDENTIALS` is not set.
fix
Provide Google Cloud credentials by setting the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the path of a service account key JSON file, or by ensuring the code runs within a GCP environment with a properly configured service account and necessary scopes.
google.api_core.exceptions.PermissionDenied: 403 Permission denied
The authenticated Google Cloud principal (service account or user) does not have the necessary IAM permissions (e.g., `roles/logging.logWriter`) to write logs to Google Cloud Logging.
fix
Grant the appropriate IAM role, such as 'Logs Writer' (`roles/logging.logWriter`), to the service account or user trying to export logs within your Google Cloud project.
Exporting failed. Dropping data.
This message, often seen in OpenTelemetry Collector or SDK debug logs, indicates that the exporter failed to send telemetry data to Google Cloud Logging after retries and is dropping the data. Common causes include network issues, incorrect endpoint configuration, invalid or expired authentication, or hitting GCP quota limits.
fix
Enable debug logging for the OpenTelemetry SDK to get more specific error messages. Systematically check network connectivity, confirm the correct Google Cloud project ID, verify authentication credentials, ensure proper IAM permissions for the service account, and check for any network policies or firewalls blocking traffic to Cloud Logging endpoints.
Upgrade
Version history
1.15.0a0latest on PyPI · released Aug 19, 2026
Audit
Dependencies
opentelemetry-sdkrequiredCore OpenTelemetry SDK for logs, processors, and providers.
google-cloud-loggingrequiredUnderlying Google Cloud client library for interacting with Cloud Logging.
Agent activity
18 hits · last 30 days
node
14
OpenAI (training)
3
Resources