Google Cloud Monitoring Exporter for OpenTelemetry

Common errors

• ModuleNotFoundError: No module named 'opentelemetry.exporter.gcp_monitoring'

  cause The `opentelemetry-exporter-gcp-monitoring` package is not installed in the current Python environment.
  fix Install the package using pip: `pip install opentelemetry-exporter-gcp-monitoring`

• google.auth.exceptions.DefaultCredentialsError: Could not automatically determine credentials.

  cause The application failed to find valid Google Cloud credentials in the environment or could not infer them (e.g., `GOOGLE_APPLICATION_CREDENTIALS` not set, or not running on GCP with default service account).
  fix Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the path of your service account key file, or ensure the application is running in an environment with default credentials (e.g., GCE, Cloud Run, GKE) with appropriate permissions.

• google.api_core.exceptions.PermissionDenied: 7 PERMISSION_DENIED: The caller does not have permission

  cause The Google Cloud service account or user credentials used by the application lack the necessary IAM permissions (e.g., `monitoring.metricWriter` role) to write metrics to Google Cloud Monitoring.
  fix Grant the `Monitoring Metric Writer` role (`roles/monitoring.metricWriter`) to the service account or user identity being used by your application in Google Cloud IAM.

• TypeError: __init__() missing 1 required positional argument: 'metric_readers'

  cause This error occurs when instantiating `opentelemetry.sdk.metrics.MeterProvider` without providing the required `metric_readers` argument, which became mandatory in newer versions of the OpenTelemetry Python SDK (e.g., v1.0.0+).
  fix Instantiate `MeterProvider` with a list of `MetricReader` instances, such as a `PeriodicExportingMetricReader` configured with your `GCPMonitoringMetricsExporter`. Example: ```python from opentelemetry.sdk.metrics import MeterProvider from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader from opentelemetry.exporter.gcp_monitoring import GCPMonitoringMetricsExporter exporter = GCPMonitoringMetricsExporter() reader = PeriodicExportingMetricReader(exporter, export_interval_millis=5000) meter_provider = MeterProvider(metric_readers=[reader]) ```

Warnings

• breaking Version 1.11.0a0 introduced an upper bound on `opentelemetry-sdk` due to potential breaking changes related to logging exporters. If you are also using OpenTelemetry logging components, ensure careful version management to avoid conflicts.
  Fix: Review the exact version constraints and ensure your `opentelemetry-sdk` version is within the specified bounds for all OpenTelemetry components you are using.
• gotcha Proper Google Cloud authentication is required for the exporter to send metrics. The library relies on `google-auth` to find credentials, typically through `GOOGLE_APPLICATION_CREDENTIALS` environment variable, `gcloud` CLI defaults, or service account attached to the VM/environment.
  Fix: Configure your Google Cloud credentials correctly in your environment (e.g., `export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json` or `gcloud auth application-default login`).
• gotcha OpenTelemetry Resource attributes are mapped to Google Cloud Monitoring MonitoredResource labels. Incorrect or missing critical resource attributes (e.g., `service.name`, `service.namespace`) can lead to metrics not appearing or being incorrectly categorized in Cloud Monitoring.
  Fix: Always define a `Resource` with meaningful attributes that align with GCP's monitored resource types and labels. Consult GCP documentation for standard resource types.
• gotcha The `PeriodicExportingMetricReader` exports metrics at a specified interval. If your application exits before an export interval completes or before a manual `shutdown()` or `force_flush()` call, recent metrics may not be sent to Cloud Monitoring.
  Fix: For short-lived applications or on application shutdown, ensure you call `meter_provider.shutdown()` or `meter_provider.force_flush()` to guarantee all buffered metrics are exported. For long-running apps, configure an appropriate `export_interval_millis`.

Install

• pip install opentelemetry-exporter-gcp-monitoring Install latest version

Imports

• CloudMonitoringMetricsExporter

  from opentelemetry.exporter.gcp_monitoring import CloudMonitoringMetricsExporter

Quickstart

This quickstart demonstrates how to configure the `CloudMonitoringMetricsExporter` to send custom metrics to Google Cloud Monitoring. It sets up a `MeterProvider` with a `PeriodicExportingMetricReader` to automatically export metrics at a defined interval. Ensure your Google Cloud authentication (e.g., `GOOGLE_APPLICATION_CREDENTIALS` environment variable or default application credentials) is properly configured for the exporter to work. Resource attributes are crucial as they map to GCP monitored resource labels.

import os
import time
from opentelemetry import metrics
from opentelemetry.exporter.gcp_monitoring import CloudMonitoringMetricsExporter
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader

# Ensure your Google Cloud credentials are set up (e.g., via GOOGLE_APPLICATION_CREDENTIALS)
# os.environ['GOOGLE_APPLICATION_CREDENTIALS'] = '/path/to/your/key.json'

# Configure Resource attributes (these map to GCP MonitoredResource labels)
resource = Resource.create(
    {
        "service.name": os.environ.get('SERVICE_NAME', 'my-gcp-metrics-service'),
        "service.namespace": os.environ.get('SERVICE_NAMESPACE', 'default'),
        "service.instance.id": os.environ.get('SERVICE_INSTANCE_ID', 'instance-1'),
    }
)

# Configure the exporter and metric reader
exporter = CloudMonitoringMetricsExporter()
reader = PeriodicExportingMetricReader(
    exporter,
    export_interval_millis=5000, # Export every 5 seconds
    export_timeout_millis=30000 # Timeout after 30 seconds
)

meter_provider = MeterProvider(metric_readers=[reader], resource=resource)
metrics.set_meter_provider(meter_provider)

# Create a meter from the global meter provider
meter = metrics.get_meter(__name__)

# Create a counter instrument
counter = meter.create_counter(
    "my_app_requests_total",
    description="Total number of application requests",
    unit="1",
)

# Record some measurements
print("Recording metrics...")
for i in range(5):
    counter.add(1, {"http_method": "GET", "http_status": "200"})
    counter.add(1, {"http_method": "POST", "http_status": "201"})
    print(f"  Added metrics batch {i+1}")
    time.sleep(2) # Sleep to allow multiple export intervals

print("Metrics sent to Google Cloud Monitoring. Check your dashboard.")

# Flush and shutdown the provider to ensure all metrics are exported
meter_provider.shutdown()
print("Metric provider shut down.")