Registry / observability / opentelemetry-exporter-gcp-trace

opentelemetry-exporter-gcp-trace

JSON →
library1.15.0pypypi✓ verified 29d ago

The `opentelemetry-exporter-gcp-trace` library provides an OpenTelemetry `SpanExporter` implementation to send trace data to Google Cloud Trace. It is part of the larger `opentelemetry-operations-python` project maintained by Google, currently at version 1.11.0, with regular updates (typically monthly or bi-monthly) to maintain compatibility with the OpenTelemetry SDK and Google Cloud services.

pip install opentelemetry-exporter-gcp-trace opentelemetry-sdk opentelemetry-resourcedetector-gcp
INSTALL
IMPORT
SIG · OPENTELEMETRY-EXPO
O
opentelemetry-exporter-gcp-trace
observabilitypythonv1.15.0
Install
6.2s avg
Import
—
Disk
72MB
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.0 · 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 0.000s · 73.3MB
glibc
py 3.10–3.95 runs
installs and imports cleanly · install 6.2s · import 0.000s · 72MB
72MB installed
● package 72MB
Code
Verified usage

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

GcpTraceExporter
✓ from opentelemetry.exporter.gcp_trace import GcpTraceExporter
TracerProvider
✓ from opentelemetry.sdk.trace import TracerProvider
BatchSpanProcessor
✓ from opentelemetry.sdk.trace.export import BatchSpanProcessor
GcpResourceDetector
✓ from opentelemetry_resourcedetector_gcp import GcpResourceDetector

This quickstart demonstrates how to initialize the `GcpTraceExporter` and integrate it with the OpenTelemetry SDK to send traces to Google Cloud Trace. It includes the recommended `GcpResourceDetector` for automatic resource attribute population and highlights the importance of `provider.shutdown()` for complete trace export.

import os from opentelemetry import trace from opentelemetry.sdk.resources import Resource from opentelemetry.sdk.trace import TracerProvider from opentelemetry.sdk.trace.export import BatchSpanProcessor from opentelemetry.exporter.gcp_trace import GcpTraceExporter from opentelemetry_resourcedetector_gcp import GcpResourceDetector # Configure GCP authentication: # This exporter uses Application Default Credentials (ADC). # Ensure GOOGLE_APPLICATION_CREDENTIALS environment variable points to a service account key # or run on a GCP environment (VM, Cloud Run, GKE, etc.) with appropriate permissions. # For example, to use a local service account file: # export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-key.json" # 1. Detect GCP resources automatically (highly recommended) # This helps populate project ID, instance ID, etc., which are crucial for Cloud Trace. resource = GcpResourceDetector().detect().merge( Resource.create({"service.name": "my-gcp-python-app"}) ) # 2. Set up the TracerProvider with the detected resource provider = TracerProvider(resource=resource) trace.set_tracer_provider(provider) # 3. Instantiate the GCP Trace Exporter exporter = GcpTraceExporter() # 4. Set up a BatchSpanProcessor to send traces efficiently # Spans are batched and sent asynchronously. span_processor = BatchSpanProcessor(exporter) provider.add_span_processor(span_processor) # 5. Get a tracer and create spans tracer = trace.get_tracer(__name__) with tracer.start_as_current_span("parent-operation-gcp"): print("Performing some work that will be traced in GCP...") with tracer.start_as_current_span("child-operation-db"): print("Simulating a database call...") with tracer.start_as_current_span("child-operation-api"): print("Simulating an external API call...") # 6. Crucially, shut down the provider to ensure all batched spans are exported # In short-lived scripts, this step is vital. In long-running services, it's typically # handled gracefully on application shutdown. provider.shutdown() print("Traces sent to Google Cloud Trace. Check your GCP project's Trace Explorer.")
Debug
Known issues
gotchaThe GcpTraceExporter relies on Google Cloud's Application Default Credentials (ADC) for authentication. Ensure your environment is properly configured for ADC, either by setting the `GOOGLE_APPLICATION_CREDENTIALS` environment variable, or by running on a Google Cloud environment (e.g., GCE, Cloud Run, GKE) with appropriate service account permissions.
fix
Configure Application Default Credentials (ADC) for your environment. Refer to Google Cloud's authentication documentation for details.
affects: All
gotchaFor traces to appear correctly associated with your GCP project and resources, it is highly recommended to use `opentelemetry-resourcedetector-gcp`. Without it, critical resource attributes like `cloud.project.id` might be missing, causing traces to be unassociated or difficult to find in the Cloud Trace UI.
fix
Install `opentelemetry-resourcedetector-gcp` and use `GcpResourceDetector().detect()` when initializing your `TracerProvider`.
affects: All
breakingThe `v1.11.0` release introduced an upper bound on `opentelemetry-sdk` (`opentelemetry-sdk >= 1.12.0, < 2.0.0`). This ensures compatibility with breaking changes in the OpenTelemetry SDK, especially regarding logging functionality. Using an `opentelemetry-sdk` version outside this range may lead to `ImportError` or runtime issues.
fix
Ensure your `opentelemetry-sdk` version is within the compatible range specified by `opentelemetry-exporter-gcp-trace` (currently `>= 1.12.0, < 2.0.0` for 1.11.0 of the exporter).
affects: 1.11.0+
gotchaIn short-lived applications or scripts, forgetting to call `provider.shutdown()` will result in incomplete or unsent traces. `BatchSpanProcessor` buffers spans and requires an explicit shutdown to ensure all pending spans are flushed and exported before the process exits.
fix
Always call `tracer_provider.shutdown()` at the end of your application's lifecycle, especially in non-daemon processes.
affects: All
Upgrade
Version history
1.15.0latest on PyPI · released Aug 19, 2026
Audit
Dependencies
opentelemetry-sdkrequiredRequired OpenTelemetry SDK for tracing components.
google-cloud-tracerequiredGoogle Cloud Python client library for interacting with the Cloud Trace API.
google-api-corerequiredShared client library for Google APIs.
opentelemetry-resourcedetector-gcpoptionalHighly recommended for automatically populating resource attributes crucial for GCP integration.
Agent activity
31 hits · last 30 days
node
26
OpenAI (training)
3
Resources
opentelemetry-exporter-gcp-trace — pip install opentelemetry-exporter-gcp-trace · libregistry