Google Cloud Monitoring

2.30.0 verified Tue May 12 auth: no python install: verified quickstart: stale

The `google-cloud-monitoring` Python client library provides programmatic access to Google Cloud Monitoring, allowing users to collect metrics, events, and metadata from Google Cloud, AWS, and other sources. It enables the creation of custom metrics, reading of time series data, and integration with Google Cloud Observability for dashboards, charts, and alerts. The library is part of the larger `google-cloud-python` ecosystem and is actively maintained, with frequent updates.

pip install google-cloud-monitoring

Common errors

error 403 Permission denied (or the resource may not exist). ↓

cause The service account or user making the API call lacks the necessary IAM permissions, or the Cloud Monitoring API is not enabled for the project.

fix

Ensure the Google Cloud Monitoring API is enabled in your Google Cloud project. Grant the required IAM roles (e.g., roles/monitoring.metricWriter, roles/monitoring.viewer, roles/monitoring.editor) to the service account or user in the IAM & Admin section of the Google Cloud Console. For local execution, verify GOOGLE_APPLICATION_CREDENTIALS points to a valid service account key with appropriate permissions.

error ImportError: cannot import name monitoring_v3 from google.cloud ↓

cause The `google-cloud-monitoring` library is either not installed, installed incorrectly, or an older, incompatible version is being used, or there is a conflict with other `google-cloud` libraries.

fix

Ensure the google-cloud-monitoring library is installed and up-to-date by running: pip install --upgrade google-cloud-monitoring. If using a virtual environment, ensure it is activated. Consider recreating your virtual environment or checking for conflicting google-cloud packages if the issue persists.

error google.api_core.exceptions.InvalidArgument: 400 One or more TimeSeries could not be written: Duplicate TimeSeries encountered. ↓

cause When writing `GAUGE` metric types, you attempted to write multiple data points for the exact same timestamp within a single `create_time_series` request for the same unique combination of metric and monitored resource.

fix

For GAUGE metrics, ensure that each Point in a TimeSeries has a unique interval.end_time. If you need to update a value, submit a new Point with a subsequent end_time. For CUMULATIVE or DELTA metrics, ensure the interval.start_time and interval.end_time are handled correctly according to the metric kind.

error google.api_core.exceptions.InvalidArgument: 400 One or more TimeSeries could not be written: Metrics cannot be written to [resource_type]. ↓

cause The `monitored_resource.type` specified when creating a custom metric or writing time series data is not a valid or writable resource type for Cloud Monitoring custom metrics.

fix

Use a valid and writable monitored resource type for custom metrics. Common valid types include global, generic_node, or generic_task. Consult the Google Cloud Monitoring documentation for a comprehensive list of supported monitored resource types for custom metrics and select one that best fits your data.

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 compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 2.10s 70.2M

3.10 slim (glibc) - - 1.06s 68M

3.11 alpine (musl) - - 2.81s 75.1M

3.11 slim (glibc) - - 1.68s 73M

3.12 alpine (musl) - - 2.77s 66.5M

3.12 slim (glibc) - - 2.02s 64M

3.13 alpine (musl) - - 2.73s 66.1M

3.13 slim (glibc) - - 2.10s 64M

3.9 alpine (musl) - - 1.92s 70.3M

3.9 slim (glibc) - - 1.22s 68M

Imports

MetricServiceClient
wrong
```
from google.cloud import monitoring
```
correct
```
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 stale last tested: 2026-04-23

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}")