{"id":2625,"library":"opentelemetry-exporter-gcp-logging","title":"Google Cloud Logging exporter for OpenTelemetry","description":"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.","status":"active","version":"1.11.0a0","language":"en","source_language":"en","source_url":"https://github.com/GoogleCloudPlatform/opentelemetry-operations-python/tree/main/opentelemetry-exporter-gcp-logging","tags":["opentelemetry","logging","google-cloud","gcp","exporter","observability","logs"],"install":[{"cmd":"pip install opentelemetry-exporter-gcp-logging","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core OpenTelemetry SDK for logs, processors, and providers.","package":"opentelemetry-sdk"},{"reason":"Underlying Google Cloud client library for interacting with Cloud Logging.","package":"google-cloud-logging"}],"imports":[{"symbol":"CloudLoggingExporter","correct":"from opentelemetry.exporter.cloud_logging import CloudLoggingExporter"}],"quickstart":{"code":"import logging\nfrom opentelemetry.sdk._logs import LoggerProvider, LoggingHandler\nfrom opentelemetry.sdk._logs.export import BatchLogRecordProcessor, SimpleLogRecordProcessor\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry._logs import set_logger_provider\nfrom opentelemetry.exporter.cloud_logging import CloudLoggingExporter\n\n# Configure OpenTelemetry LoggerProvider\nresource = Resource.create(\n    {\n        \"service.name\": \"my-python-app\",\n        \"service.instance.id\": \"instance-1\",\n    }\n)\n\nlogger_provider = LoggerProvider(resource=resource)\nset_logger_provider(logger_provider)\n\n# --- Example 1: Exporting via RPC (default for older versions, or if structured_json_file is not set) ---\nexporter_rpc = CloudLoggingExporter(default_log_name='my_app_logs_rpc')\nlogger_provider.add_log_record_processor(BatchLogRecordProcessor(exporter_rpc))\n\n# --- Example 2: Exporting as structured JSON to stdout (recommended for GCP environments >= v1.11.0) ---\n# This is more efficient for environments with Cloud Logging agent that scrapes stdout\nexporter_json = CloudLoggingExporter(default_log_name='my_app_logs_json', structured_json_file=True)\nlogger_provider.add_log_record_processor(SimpleLogRecordProcessor(exporter_json)) # Simple processor is often sufficient for stdout export\n\n# Attach OTLP handler to the root logger\nhandler = LoggingHandler(level=logging.INFO, logger_provider=logger_provider)\nlogging.getLogger().addHandler(handler)\n\n# Create a namespaced logger for your application\n# It's recommended not to use the root logger with OTLP handler directly for app logs\napp_logger = logging.getLogger(\"my_app_module\")\napp_logger.info(\"This is an info log with OTel context!\")\napp_logger.warning(\"A warning occurred: %s\", \"something went wrong\")\n\n# Logs will be exported asynchronously by BatchLogRecordProcessor\n# For SimpleLogRecordProcessor, logs are sent immediately\n\n# It's good practice to shut down the logger provider when the application exits\n# This ensures all buffered logs are flushed.\n# In a real application, you'd typically do this in a graceful shutdown hook.\nlogger_provider.shutdown()\nprint(\"Logs sent to Cloud Logging (or stdout for structured JSON exporter).\")","lang":"python","description":"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."},"warnings":[{"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.","message":"As 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.","severity":"breaking","affected_versions":">=1.11.0a0"},{"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.","message":"There 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.","severity":"breaking","affected_versions":"All versions"},{"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).","message":"Ensure 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Install `opentelemetry-resourcedetector-gcp` and integrate it into your `LoggerProvider` setup to automatically populate resource attributes relevant to your GCP environment.","message":"While 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}