Google Cloud Trace

Warnings

• gotcha The `google-cloud-trace` library primarily functions as an OpenTelemetry exporter. You should use OpenTelemetry for instrumentation (creating spans, propagating context) and then configure `CloudTraceSpanExporter` to send those traces to Google Cloud Trace, rather than directly using legacy `google.cloud.trace.Client` methods for instrumentation.
  Fix: Adopt OpenTelemetry for application instrumentation (e.g., using `opentelemetry-sdk` and `opentelemetry-api`) and integrate `google.cloud.trace_v2.exporters.CloudTraceSpanExporter`.
• gotcha Ensure your Google Cloud Project ID is correctly configured. It can be passed explicitly to `CloudTraceSpanExporter(project_id='your-project-id')` or automatically discovered if the `GOOGLE_CLOUD_PROJECT` environment variable is set or if running on GCP infrastructure.
  Fix: Explicitly pass `project_id` or set the `GOOGLE_CLOUD_PROJECT` environment variable.
• gotcha Authentication to Google Cloud Trace requires proper Google Cloud credentials. This typically involves setting the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to a service account key file, or relying on Application Default Credentials when running on GCP (e.g., GCE, Cloud Run, GKE).
  Fix: Follow standard Google Cloud authentication practices: set `GOOGLE_APPLICATION_CREDENTIALS` for local development or leverage ADC on GCP.
• breaking If migrating from older OpenCensus-based tracing to OpenTelemetry, significant code changes are required. OpenCensus is deprecated in favor of OpenTelemetry, and `google-cloud-trace` no longer directly supports OpenCensus exporters.
  Fix: Rewrite tracing instrumentation using OpenTelemetry APIs and use `CloudTraceSpanExporter` from `google.cloud.trace_v2.exporters`.

Install

• pip install google-cloud-trace opentelemetry-sdk opentelemetry-api Install with OpenTelemetry SDK

Imports

• CloudTraceSpanExporter

  from google.cloud.trace_v2.exporters import CloudTraceSpanExporter

  For modern applications, `CloudTraceSpanExporter` from `trace_v2` is the recommended way to send OpenTelemetry traces to Google Cloud Trace. Direct usage of `google.cloud.trace.Client` is less common for new instrumentations.
• TracerProvider

  from opentelemetry.sdk.trace import TracerProvider

  This is a core OpenTelemetry class, essential for configuring the tracing pipeline.
• trace

  from opentelemetry import trace

  Used to get the global tracer and manage spans.

Quickstart

This quickstart demonstrates how to set up OpenTelemetry with `google-cloud-trace` to send traces to Google Cloud Trace. It configures a `TracerProvider` with a service resource, registers the `CloudTraceSpanExporter`, and then creates a root span with a child span. Remember to replace 'your-gcp-project-id' with your actual GCP project ID or ensure the `GOOGLE_CLOUD_PROJECT` environment variable is set.

import os
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor
from opentelemetry.sdk.resources import Resource
from google.cloud.trace_v2.exporters import CloudTraceSpanExporter

# Set the Google Cloud project ID (can also be picked up from GOOGLE_CLOUD_PROJECT environment variable)
project_id = os.environ.get('GOOGLE_CLOUD_PROJECT', 'your-gcp-project-id')

# 1. Configure OpenTelemetry TracerProvider with a Resource (important for service naming in Trace)
resource = Resource.create({"service.name": "my-python-app", "service.version": "1.0.0"})
provider = TracerProvider(resource=resource)

# 2. Add the Google Cloud Trace Span Exporter
# You can specify project_id here or rely on default credentials if GOOGLE_CLOUD_PROJECT is set
cloud_trace_exporter = CloudTraceSpanExporter(project_id=project_id)
provider.add_span_processor(SimpleSpanProcessor(cloud_trace_exporter))

# 3. Set the global tracer provider
trace.set_tracer_provider(provider)

# 4. Get a tracer and create spans
tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span('my-application-span'):
    print('Doing some work...')
    with tracer.start_as_current_span('child-operation') as child_span:
        child_span.set_attribute('custom_key', 'custom_value')
        print('Doing child work...')
    print('Work finished.')

# In a real application, spans are typically sent asynchronously.
# For a short script, ensure exporter has time to send or explicitly shut down.
# provider.shutdown() # Uncomment in production to ensure all spans are exported before process exits.