Google Cloud Monitoring

Warnings

• breaking The `google-cloud-monitoring` library version 2.0.0 and later requires Python 3.9 or higher. Older Python versions (3.8 and below) are no longer supported.
  Fix: Upgrade your Python environment to version 3.9 or newer. Ensure your `requirements.txt` or `pyproject.toml` reflects this.
• gotcha Authentication is crucial for interacting with Google Cloud APIs. The client library uses Application Default Credentials (ADC) to find credentials. For local development, you often need to run `gcloud auth application-default login` or set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to a service account key file (though the former is generally preferred). Additionally, the project ID must be provided to the client, either explicitly via `client(project='your-project-id')` or implicitly via the `GOOGLE_CLOUD_PROJECT` environment variable.
  Fix: Follow Google Cloud's authentication guide for Python, typically using `gcloud auth application-default login` for local development or configuring service accounts/Workload Identity in production. Set the `GOOGLE_CLOUD_PROJECT` environment variable or pass the project ID directly to the client.
• gotcha When writing custom metrics, it is critical to correctly specify the `MonitoredResource` type and its associated labels. Omitting or providing incorrect resource information can lead to metrics not appearing as expected or performance issues. The `global` resource type is a common fallback for metrics not tied to a specific compute resource, but more specific types (e.g., `gce_instance`, `cloud_run_revision`) are often better.
  Fix: Always define `series.resource.type` and ensure `series.resource.labels` contains the necessary key-value pairs for the chosen resource type, as described in Google Cloud Monitoring documentation for monitored resource types.
• deprecated Older versions of the `google-cloud-monitoring` library (prior to the 2.x releases) often used `from google.cloud import monitoring` and instantiated `monitoring.Client()`. The current, generated client libraries use `from google.cloud import monitoring_v3` and `monitoring_v3.MetricServiceClient()` (or other specific clients for different Monitoring API services). The older client interface may lack newer API features and is not the recommended approach.
  Fix: Migrate your code to use the `monitoring_v3` module and its specific client classes (e.g., `MetricServiceClient`, `ServiceMonitoringServiceClient`) for the Google Cloud Monitoring API.

Install

• pip install google-cloud-monitoring Install latest version

Imports

• MetricServiceClient

  from google.cloud import monitoring_v3

  The `monitoring_v3` module provides the client for the current v3 API. Direct import of `monitoring` often refers to an older client library pattern (pre-2.0.0) which may lack features or have different interfaces.
• ServiceMonitoringServiceClient

  from google.cloud import monitoring_v3

  Used for managing service-level monitoring configurations.
• TimeSeries

  from google.cloud.monitoring_v3 import TimeSeries

  Required for creating and writing time series data points to Cloud Monitoring.

Quickstart

This quickstart demonstrates how to initialize the Google Cloud Monitoring client, optionally create a custom metric descriptor (checking if it exists first), and then write a single data point for that custom metric as a time series. Remember to replace `your-project-id` with your actual Google Cloud project ID and ensure proper authentication is set up. The `GOOGLE_CLOUD_PROJECT` environment variable is the recommended way to provide the project ID.

import os
from google.cloud import monitoring_v3
from google.protobuf import timestamp_pb2

# Set your Google Cloud Project ID using environment variable or replace 'your-project-id'
project_id = os.environ.get('GOOGLE_CLOUD_PROJECT', 'your-project-id')

if project_id == 'your-project-id':
    print("WARNING: Please set the GOOGLE_CLOUD_PROJECT environment variable or replace 'your-project-id' with your actual project ID.")

client = monitoring_v3.MetricServiceClient()
project_name = f"projects/{project_id}"

# Define a custom metric descriptor if it doesn't exist
metric_type = 'custom.googleapis.com/my_app/request_count'
metric_descriptor_name = f"{project_name}/metricDescriptors/{metric_type}"

try:
    client.get_metric_descriptor(name=metric_descriptor_name)
    print(f"Metric descriptor '{metric_type}' already exists.")
except Exception:
    print(f"Creating metric descriptor '{metric_type}'...")
    descriptor = monitoring_v3.MetricDescriptor()
    descriptor.type = metric_type
    descriptor.metric_kind = monitoring_v3.MetricDescriptor.MetricKind.GAUGE
    descriptor.value_type = monitoring_v3.MetricDescriptor.ValueType.DOUBLE
    descriptor.description = "Count of requests to my application."
    client.create_metric_descriptor(name=project_name, metric_descriptor=descriptor)
    print("Metric descriptor created.")

# Create a time series
series = monitoring_v3.TimeSeries()
series.metric.type = metric_type

# Assign to a monitored resource (e.g., 'global' for metrics not tied to a specific resource)
series.resource.type = 'global'
# For other resource types (e.g., 'gce_instance', 'cloud_run_revision'), add relevant labels:
# series.resource.labels['instance_id'] = '1234567890'
# series.resource.labels['zone'] = 'us-central1-a'

now = timestamp_pb2.Timestamp()
now.FromDatetime(timestamp_pb2.datetime_helper.utcnow())

point = monitoring_v3.Point()
point.interval.end_time = now
point.value.double_value = 42.0 # Your metric value

series.points.append(point)

# Write the time series data
try:
    client.create_time_series(name=project_name, time_series=[series])
    print(f"Successfully wrote a custom metric '{metric_type}' to Cloud Monitoring for project '{project_id}'.")
    print("You can view this metric in the Google Cloud Console under Monitoring -> Metrics Explorer.")
except Exception as e:
    print(f"Error writing time series: {e}")