Install & Compatibility
Where this runs
tested against v1.20.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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 73MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.9s · import 0.000s · 71MB
72MB installed
● package 72MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
CloudTraceSpanExporter
✓ from google.cloud.trace_v2.exporters import CloudTraceSpanExporter
✗ from google.cloud.trace import Client
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.
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.
Debug
Known issues
gotchaThe `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.fixAdopt OpenTelemetry for application instrumentation (e.g., using `opentelemetry-sdk` and `opentelemetry-api`) and integrate `google.cloud.trace_v2.exporters.CloudTraceSpanExporter`.
affects: All versions (especially since OpenTelemetry became the standard for tracing)
gotchaEnsure 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.fixExplicitly pass `project_id` or set the `GOOGLE_CLOUD_PROJECT` environment variable.
affects: All versions
gotchaAuthentication 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).fixFollow standard Google Cloud authentication practices: set `GOOGLE_APPLICATION_CREDENTIALS` for local development or leverage ADC on GCP.
affects: All versions
breakingIf 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.fixRewrite tracing instrumentation using OpenTelemetry APIs and use `CloudTraceSpanExporter` from `google.cloud.trace_v2.exporters`.
affects: Older projects using OpenCensus transitioning to current `google-cloud-trace`
breakingThe required module `google.cloud.trace_v2.exporters` was not found. This typically indicates that the `google-cloud-trace` library (which provides this module as part of its OpenTelemetry integration) is not installed, or an incompatible version is installed. Ensure `google-cloud-trace` is properly installed.fixEnsure `google-cloud-trace` is installed in your environment (e.g., `pip install google-cloud-trace`). If it is already installed, verify that the installed version provides the `google.cloud.trace_v2.exporters` module. You may need to upgrade `pip install --upgrade google-cloud-trace` or specify a compatible version.
affects: All versions
breakingThe `google-cloud-trace` library must be installed to use its components like `CloudTraceSpanExporter`. The `ModuleNotFoundError` suggests the library is not available in the current environment.fixEnsure the `google-cloud-trace` library is installed by running `pip install google-cloud-trace` or including it in your project's dependencies (e.g., `requirements.txt`).
affects: All versions
Upgrade
Version history
1.20.0latest on PyPI · released Jun 22, 2026
Audit
Dependencies
opentelemetry-apirequiredRequired for OpenTelemetry API interfaces (e.g., `trace.get_tracer`).
opentelemetry-sdkrequiredRequired for OpenTelemetry SDK components (e.g., `TracerProvider`, `SimpleSpanProcessor`).