{"id":1498,"library":"google-cloud-trace","title":"Google Cloud Trace","description":"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.","status":"active","version":"1.19.0","language":"en","source_language":"en","source_url":"https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-trace","tags":["google cloud","tracing","observability","opentelemetry","cloud trace"],"install":[{"cmd":"pip install google-cloud-trace opentelemetry-sdk opentelemetry-api","lang":"bash","label":"Install with OpenTelemetry SDK"}],"dependencies":[{"reason":"Required for OpenTelemetry API interfaces (e.g., `trace.get_tracer`).","package":"opentelemetry-api","optional":false},{"reason":"Required for OpenTelemetry SDK components (e.g., `TracerProvider`, `SimpleSpanProcessor`).","package":"opentelemetry-sdk","optional":false}],"imports":[{"note":"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.","wrong":"from google.cloud.trace import Client","symbol":"CloudTraceSpanExporter","correct":"from google.cloud.trace_v2.exporters import CloudTraceSpanExporter"},{"note":"This is a core OpenTelemetry class, essential for configuring the tracing pipeline.","symbol":"TracerProvider","correct":"from opentelemetry.sdk.trace import TracerProvider"},{"note":"Used to get the global tracer and manage spans.","symbol":"trace","correct":"from opentelemetry import trace"}],"quickstart":{"code":"import os\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import SimpleSpanProcessor\nfrom opentelemetry.sdk.resources import Resource\nfrom google.cloud.trace_v2.exporters import CloudTraceSpanExporter\n\n# Set the Google Cloud project ID (can also be picked up from GOOGLE_CLOUD_PROJECT environment variable)\nproject_id = os.environ.get('GOOGLE_CLOUD_PROJECT', 'your-gcp-project-id')\n\n# 1. Configure OpenTelemetry TracerProvider with a Resource (important for service naming in Trace)\nresource = Resource.create({\"service.name\": \"my-python-app\", \"service.version\": \"1.0.0\"})\nprovider = TracerProvider(resource=resource)\n\n# 2. Add the Google Cloud Trace Span Exporter\n# You can specify project_id here or rely on default credentials if GOOGLE_CLOUD_PROJECT is set\ncloud_trace_exporter = CloudTraceSpanExporter(project_id=project_id)\nprovider.add_span_processor(SimpleSpanProcessor(cloud_trace_exporter))\n\n# 3. Set the global tracer provider\ntrace.set_tracer_provider(provider)\n\n# 4. Get a tracer and create spans\ntracer = trace.get_tracer(__name__)\n\nwith tracer.start_as_current_span('my-application-span'):\n    print('Doing some work...')\n    with tracer.start_as_current_span('child-operation') as child_span:\n        child_span.set_attribute('custom_key', 'custom_value')\n        print('Doing child work...')\n    print('Work finished.')\n\n# In a real application, spans are typically sent asynchronously.\n# For a short script, ensure exporter has time to send or explicitly shut down.\n# provider.shutdown() # Uncomment in production to ensure all spans are exported before process exits.","lang":"python","description":"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."},"warnings":[{"fix":"Adopt OpenTelemetry for application instrumentation (e.g., using `opentelemetry-sdk` and `opentelemetry-api`) and integrate `google.cloud.trace_v2.exporters.CloudTraceSpanExporter`.","message":"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.","severity":"gotcha","affected_versions":"All versions (especially since OpenTelemetry became the standard for tracing)"},{"fix":"Explicitly pass `project_id` or set the `GOOGLE_CLOUD_PROJECT` environment variable.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Follow standard Google Cloud authentication practices: set `GOOGLE_APPLICATION_CREDENTIALS` for local development or leverage ADC on GCP.","message":"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).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Rewrite tracing instrumentation using OpenTelemetry APIs and use `CloudTraceSpanExporter` from `google.cloud.trace_v2.exporters`.","message":"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.","severity":"breaking","affected_versions":"Older projects using OpenCensus transitioning to current `google-cloud-trace`"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}