Registry / gcp / google-cloud-trace

google-cloud-trace

JSON →
library1.20.0pypypi✓ verified 24d ago

The Google Cloud Trace API client library for Python. This library primarily provides an OpenTelemetry Span Exporter to send traces from Python applications to Google Cloud Trace. It is part of the larger `google-cloud-python` monorepo, with frequent updates across various Google Cloud services. The current version is 1.19.0.

pip install google-cloud-trace opentelemetry-sdk opentelemetry-api
INSTALL
IMPORT
SIG · GOOGLE-CLOUD-TRACE
G
google-cloud-trace
gcppythonv1.20.0
Install
5.9s avg
Import
Disk
72MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 73MB
glibc
py 3.103.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.
fix
Adopt 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.
fix
Explicitly 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).
fix
Follow 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.
fix
Rewrite 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.
fix
Ensure `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.
fix
Ensure 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`).
Agent activity
29 hits · last 30 days
node
24
OpenAI (training)
2
Resources
google-cloud-trace — pip install google-cloud-trace · libregistry