Monitoring Query
Scannednpx machina-cli add skill yu-iskw/google-cloud-observability-plugin/monitoring-query --openclawMetrics Query (API)
Retrieve time-series data for a specific metric using the Cloud Monitoring API.
Purpose
Analyze resource utilization and performance trends by fetching raw or aggregated data points.
Inputs
project(optional): The Google Cloud project ID to query metrics from.metric_type(required): The metric type to query (e.g.,compute.googleapis.com/instance/cpu/utilization).filter(optional): Additional filters for the query (e.g.,resource.labels.instance_id="12345").start_time(optional): The start of the time interval (RFC3339). Defaults to 1 hour ago.end_time(optional): The end of the time interval (RFC3339). Defaults to now.page_size(optional): Maximum number of points to return.
Behavior
-
Identify the target project ID (referred to as
[PROJECT_ID]). Ifprojectis provided as an input, use it. Otherwise, retrieve the active project ID usinggcloud config get-value project. -
Obtain an authentication token using
gcloud auth print-access-token. -
Construct the filter string:
metric.type="[METRIC_TYPE]"plus any additional filters. -
Call the Monitoring API via
curl:curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/timeSeries?filter=[FILTER]&interval.startTime=[START_TIME]&interval.endTime=[END_TIME]&pageSize=[PAGE_SIZE]" -
If
start_timeorend_timeare not provided, calculate them relative to current UTC time.
Output
Returns a JSON object containing the time-series data points.
References
Source
git clone https://github.com/yu-iskw/google-cloud-observability-plugin/blob/main/skills/monitoring-query/SKILL.mdView on GitHub Overview
This skill retrieves time-series data for a specific metric using the Cloud Monitoring API. It enables you to analyze resource utilization and performance trends by fetching raw or aggregated data points within a defined interval, with optional filters and pagination.
How This Skill Works
The process identifies the target project (from input or the active gcloud config), authenticates with gcloud to obtain an access token, constructs a filter string using metric.type and optional filters, and then queries the Cloud Monitoring API via curl. It returns a JSON payload containing the time-series data points, honoring optional start_time, end_time, and page_size parameters (defaulting to 1 hour ago to now if not provided).
When to Use It
- When you need time-series data for a specific metric in a Google Cloud project
- When debugging resource utilization like CPU, memory, or network metrics
- When fetching data for a defined time interval with optional filters
- When building dashboards or automation that rely on Monitoring API data
- When exporting or auditing metric data for analysis or alerts
Quick Start
- Step 1: Set inputs - project (optional), metric_type, filter (optional), start_time (optional), end_time (optional), page_size (optional)
- Step 2: Authenticate and build the curl command using gcloud auth print-access-token and the metrics filter
- Step 3: Run the curl request and parse the JSON response for time-series data
Best Practices
- Always provide metric_type and, if possible, a precise filter to narrow results
- Use RFC3339 formatted start_time and end_time for reliability
- Rely on the default 1-hour window if times are omitted, but adjust for your use case
- Respect page_size and implement pagination to retrieve large time-series sets
- Validate responses and handle API errors, timeouts, and rate limits gracefully
Example Use Cases
- Query CPU utilization for compute.googleapis.com/instance/cpu/utilization over the last hour in a specific project
- Fetch disk read bytes for a particular VM instance using a resource.labels.instance_id filter
- Pull network throughput statistics for all instances in a project during business hours with a filter
- Compare time-series data between two intervals to detect anomalies or trends
- Feed retrieved time-series into a dashboard or alerting system for monitoring
