Google Cloud Trace Exporter for OpenTelemetry

Warnings

• gotcha 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.
  Fix: Configure Application Default Credentials (ADC) for your environment. Refer to Google Cloud's authentication documentation for details.
• gotcha 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.
  Fix: Install `opentelemetry-resourcedetector-gcp` and use `GcpResourceDetector().detect()` when initializing your `TracerProvider`.
• breaking 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.
  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).
• gotcha 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.
  Fix: Always call `tracer_provider.shutdown()` at the end of your application's lifecycle, especially in non-daemon processes.

Install

• pip install opentelemetry-exporter-gcp-trace opentelemetry-sdk opentelemetry-resourcedetector-gcp Install core exporter and recommended resource detector

Imports

• 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

Quickstart

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.")