Google Cloud Resource Detector for OpenTelemetry

Warnings

• breaking Version `1.11.0` introduced an upper bound on `opentelemetry-sdk` due to logging breaking changes. Using an `opentelemetry-sdk` version newer than the specified upper bound might lead to runtime errors or unexpected behavior related to logging.
  Fix: Refer to the `pyproject.toml` or `setup.cfg` of `opentelemetry-resourcedetector-gcp` for the exact `opentelemetry-sdk` version constraints and pin your `opentelemetry-sdk` installation accordingly.
• gotcha The `GoogleCloudResourceDetector` relies on accessing the GCP metadata server (typically at `http://metadata.google.internal`). If the application is running in an environment with restricted network access, firewalls, or outside of GCP, the detection may fail or time out.
  Fix: Ensure that the application's network environment allows access to the metadata server. If running outside GCP or in a highly restricted environment, consider manually providing resource attributes or using other appropriate resource detectors.
• gotcha In `v1.3.0`, the explicit `google-auth` dependency for resource detection was removed. While this streamlines the detector, users expecting `google-auth` to be a direct dependency of the resource detector itself for other reasons might be surprised. It implies the detector primarily relies on the metadata server rather than explicit `google-auth` library calls for identity.
  Fix: If `google-auth` functionality is needed for other parts of your application (e.g., interacting with other Google Cloud APIs or using GCP-specific OpenTelemetry exporters), ensure it is installed separately.
• gotcha Prior to `v1.8.0`, there were issues with the reliable creation of resources within the detector and potentially long timeouts when reading metadata. Users on older versions might experience incomplete resource attributes or delays in startup.
  Fix: Upgrade to `opentelemetry-resourcedetector-gcp` version `1.8.0` or newer to benefit from improved resource creation reliability and shorter metadata connection timeouts.

Install

• pip install opentelemetry-sdk opentelemetry-resourcedetector-gcp Install core SDK and GCP resource detector

Imports

• GoogleCloudResourceDetector

  from opentelemetry.resourcedetector.gcp_resource_detector import GoogleCloudResourceDetector

• get_aggregated_resources

  from opentelemetry.sdk.resources import get_aggregated_resources

  Used to combine the GCP detector with other potential resource detectors.

Quickstart

This quickstart demonstrates how to initialize the OpenTelemetry `TracerProvider` with `GoogleCloudResourceDetector`. The detector runs automatically when `get_aggregated_resources` is called, querying the GCP metadata server to identify the environment and populate standard OpenTelemetry resource attributes. Ensure the code runs within a Google Cloud environment (e.g., GCE, GKE, Cloud Run) for effective detection. The example then creates a basic span, which will inherit the detected resource attributes.

import os
from opentelemetry import trace
from opentelemetry.sdk.resources import get_aggregated_resources
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
from opentelemetry.resourcedetector.gcp_resource_detector import GoogleCloudResourceDetector

# The detector automatically queries the GCP metadata server.
# Ensure your application is running in a GCP environment for full detection.
resource = get_aggregated_resources(
    [GoogleCloudResourceDetector(raise_on_error=True)]
)

# Create a TracerProvider with the detected resource
tracer_provider = TracerProvider(resource=resource)
trace.set_tracer_provider(tracer_provider)

# For demonstration, export to console. In a real application, use a GCP exporter.
span_processor = SimpleSpanProcessor(ConsoleSpanExporter())
tracer_provider.add_span_processor(span_processor)

tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("my-gcp-operation") as span:
    span.set_attribute("custom.attribute", "value")
    print(f"Span created with detected resource attributes: {resource.attributes}")
    # In a real application, this would be exported to Cloud Trace or another backend

print("Resource detection example complete.")