Registry /
gcp / google-cloud-monitoring
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.
Install & Compatibility
Where this runs
tested against v2.31.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.925 runs
installs and imports cleanly · install 0.0s · import 2.387s · 71.4MB
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 5.5s · import 1.587s · 69MB
70MB installed
● package 70MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
MetricServiceClient
✓ from google.cloud import monitoring_v3
✗ from google.cloud import monitoring
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.
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}")
Debug
Known issues
breakingThe `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.fixUpgrade your Python environment to version 3.9 or newer. Ensure your `requirements.txt` or `pyproject.toml` reflects this.
affects: >=2.0.0
gotchaAuthentication 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.fixFollow 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.
affects: All
gotchaWhen 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.fixAlways 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.
affects: All
deprecatedOlder 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.fixMigrate your code to use the `monitoring_v3` module and its specific client classes (e.g., `MetricServiceClient`, `ServiceMonitoringServiceClient`) for the Google Cloud Monitoring API.
affects: <2.0.0 (older patterns)
Errors
Common errors & fixes
403 Permission denied (or the resource may not exist).
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.
fixEnsure 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.
ImportError: cannot import name monitoring_v3 from google.cloud
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.
fixEnsure 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.
google.api_core.exceptions.InvalidArgument: 400 One or more TimeSeries could not be written: Duplicate TimeSeries encountered.
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.
fixFor `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.
google.api_core.exceptions.InvalidArgument: 400 One or more TimeSeries could not be written: Metrics cannot be written to [resource_type].
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.
fixUse 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.
Audit
Dependencies
No dependency data recorded yet.