{"id":1605,"library":"opentelemetry-exporter-gcp-trace","title":"Google Cloud Trace Exporter for OpenTelemetry","description":"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.","status":"active","version":"1.11.0","language":"en","source_language":"en","source_url":"https://github.com/GoogleCloudPlatform/opentelemetry-operations-python/tree/main/opentelemetry-exporter-gcp-trace","tags":["opentelemetry","gcp","google-cloud","trace","exporter","observability","tracing"],"install":[{"cmd":"pip install opentelemetry-exporter-gcp-trace opentelemetry-sdk opentelemetry-resourcedetector-gcp","lang":"bash","label":"Install core exporter and recommended resource detector"}],"dependencies":[{"reason":"Required OpenTelemetry SDK for tracing components.","package":"opentelemetry-sdk","optional":false},{"reason":"Google Cloud Python client library for interacting with the Cloud Trace API.","package":"google-cloud-trace","optional":false},{"reason":"Shared client library for Google APIs.","package":"google-api-core","optional":false},{"reason":"Highly recommended for automatically populating resource attributes crucial for GCP integration.","package":"opentelemetry-resourcedetector-gcp","optional":true}],"imports":[{"symbol":"GcpTraceExporter","correct":"from opentelemetry.exporter.gcp_trace import GcpTraceExporter"},{"symbol":"TracerProvider","correct":"from opentelemetry.sdk.trace import TracerProvider"},{"symbol":"BatchSpanProcessor","correct":"from opentelemetry.sdk.trace.export import BatchSpanProcessor"},{"symbol":"GcpResourceDetector","correct":"from opentelemetry_resourcedetector_gcp import GcpResourceDetector"}],"quickstart":{"code":"import os\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import BatchSpanProcessor\nfrom opentelemetry.exporter.gcp_trace import GcpTraceExporter\nfrom opentelemetry_resourcedetector_gcp import GcpResourceDetector\n\n# Configure GCP authentication:\n# This exporter uses Application Default Credentials (ADC).\n# Ensure GOOGLE_APPLICATION_CREDENTIALS environment variable points to a service account key\n# or run on a GCP environment (VM, Cloud Run, GKE, etc.) with appropriate permissions.\n# For example, to use a local service account file:\n# export GOOGLE_APPLICATION_CREDENTIALS=\"/path/to/your/service-account-key.json\"\n\n# 1. Detect GCP resources automatically (highly recommended)\n# This helps populate project ID, instance ID, etc., which are crucial for Cloud Trace.\nresource = GcpResourceDetector().detect().merge(\n    Resource.create({\"service.name\": \"my-gcp-python-app\"})\n)\n\n# 2. Set up the TracerProvider with the detected resource\nprovider = TracerProvider(resource=resource)\ntrace.set_tracer_provider(provider)\n\n# 3. Instantiate the GCP Trace Exporter\nexporter = GcpTraceExporter()\n\n# 4. Set up a BatchSpanProcessor to send traces efficiently\n# Spans are batched and sent asynchronously.\nspan_processor = BatchSpanProcessor(exporter)\nprovider.add_span_processor(span_processor)\n\n# 5. Get a tracer and create spans\ntracer = trace.get_tracer(__name__)\n\nwith tracer.start_as_current_span(\"parent-operation-gcp\"):\n    print(\"Performing some work that will be traced in GCP...\")\n    with tracer.start_as_current_span(\"child-operation-db\"):\n        print(\"Simulating a database call...\")\n    with tracer.start_as_current_span(\"child-operation-api\"):\n        print(\"Simulating an external API call...\")\n\n# 6. Crucially, shut down the provider to ensure all batched spans are exported\n# In short-lived scripts, this step is vital. In long-running services, it's typically\n# handled gracefully on application shutdown.\nprovider.shutdown()\nprint(\"Traces sent to Google Cloud Trace. Check your GCP project's Trace Explorer.\")","lang":"python","description":"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."},"warnings":[{"fix":"Configure Application Default Credentials (ADC) for your environment. Refer to Google Cloud's authentication documentation for details.","message":"The 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.","severity":"gotcha","affected_versions":"All"},{"fix":"Install `opentelemetry-resourcedetector-gcp` and use `GcpResourceDetector().detect()` when initializing your `TracerProvider`.","message":"For 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.","severity":"gotcha","affected_versions":"All"},{"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).","message":"The `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.","severity":"breaking","affected_versions":"1.11.0+"},{"fix":"Always call `tracer_provider.shutdown()` at the end of your application's lifecycle, especially in non-daemon processes.","message":"In 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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}