{"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":"python","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,"search_vec":"'1.11.0':44 'a0':45 'cadenc':56 'cloud':2,25,38,62,68 'contrib':34 'current':41 'data':22 'export':4,10,18,70 'follow':49 'gcp':11,69 'general':48 'googl':1,24,37,61,67 'google-cloud':66 'integr':63 'librari':13 'log':3,12,17,21,26,65,72 'observ':71 'opentelemetri':6,9,16,32,51,64 'opentelemetry-exporter-gcp-log':8 'oper':39 'part':29 'project':35 'provid':14 'python':33,52 'releas':47,55 'sdk':53 'send':20 'specif':58 'updat':59 'version':42","created_at":"2026-04-11T01:35:58.842789+00:00","updated_at":"2026-04-16T17:38:06.288077+00:00","problems":[{"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`.","cause":"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.","error":"ModuleNotFoundError: No module named 'opentelemetry.exporter.cloud_logging'"},{"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.","cause":"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.","error":"google.auth.exceptions.DefaultCredentialsError: Could not automatically determine credentials."},{"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.","cause":"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.","error":"google.api_core.exceptions.PermissionDenied: 403 Permission denied"},{"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.","cause":"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.","error":"Exporting failed. Dropping data."}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.15.0a0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/GoogleCloudPlatform/opentelemetry-operations-python","docs":null,"changelog":null,"pypi":"https://pypi.org/project/opentelemetry-exporter-gcp-logging/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["observability","gcp"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}