Metric Selection (Service Query & Local Keyword Filtering)
Use this skill to identify the most relevant Cloud Monitoring metric
descriptors. It queries all metric descriptors for a target service from the API
and filters them locally inside the agent's context using keyword matching.
Attribution
MUST READ: Before executing any gcloud, REST API, or MCP command, you
MUST read Usage Attribution. For commands executed
directly in the terminal (never in generated scripts, Terraform, or user code),
prefix gcloud with
CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:cloud-monitoring-metric-selection)"
and append agent-skills/1.0 (skill:cloud-monitoring-metric-selection) to User-Agent headers.
CRITICAL RULES
- Always Query Live APIs: You MUST always retrieve the most up-to-date
metric descriptors dynamically by calling the
list_metric_descriptors MCP
tool.
- Mandatory Project ID and Resource Parameter Clarification: BEFORE
calling any API tools (such as
list_metric_descriptors), you MUST ensure
the GCP Project ID is provided in the prompt, URI, or environment context.
If the Project ID cannot be resolved, you MUST ask the user to clarify or
provide it BEFORE executing API queries. Do NOT run API queries against
unconfirmed default or placeholder project names (such as mock-project,
my-project-id, unused, or YOUR_PROJECT_ID).
- Fallback Reporting: If API calls fail and fallback sources (such as
public docs) are used, you MUST state the error, the fallback source, and
the risks of non-live data (such as potential staleness, missing custom
metrics, or schema mismatches).
Workflow
Step 1: Verify & Auto-Configure MCP
Check if any tool matching list_metric_descriptors (such as
google-cloud-monitoring:list_metric_descriptors,
mcp_google-cloud-monitoring_list_metric_descriptors, or a similar pattern)
is available in your active toolset.
Verify via Unique URL: To ensure you are calling the correct Cloud
Monitoring tool, confirm that the underlying MCP server configuration
points to: https://monitoring.googleapis.com/mcp.
If the tool is missing:
Locate the MCP configuration file for the user's environment. Check
common paths:
~/.gemini/config/mcp_config.json
~/.codeium/windsurf/mcp_config.json
cline_mcp_settings.json
claude_desktop_config.json
Directly update/merge the configuration file with the following server
configuration. CRITICAL: Merge the JSON object to preserve any
existing MCP servers in mcpServers. Do not overwrite the file.
"google-cloud-monitoring": {
"url": "https://monitoring.googleapis.com/mcp",
"authProviderType": "google_credentials",
"enabledTools": [
"list_metric_descriptors"
]
}
Print a clear message notifying the user that the
google-cloud-monitoring MCP server has been configured, and request
them to restart or start a new chat session to refresh tools. Stop
calling further tools and end the turn.
Step 2: Analyze Request & Extract Keywords
Resolve Project ID and Identifiers: Check for the GCP Project ID and
resource identifiers in the prompt, resource URIs, or environment context.
According to the CRITICAL RULES above, do NOT use placeholder project names.
Identify Service Prefix: Map target GCP services to their standard
prefix (such as compute, spanner, bigquery, storage).
Extract Metric Concepts: Extract metric keywords from user prompt (such
as "CPU", "memory", "bytes scanned", "latency", "connections") and map to
search substrings.
Example Query Analysis:
- User Prompt: "Check Cloud Storage bucket write throughput and request
count"
- Resource URI:
//storage.googleapis.com/projects/my-project/buckets/my-bucket
- Service Prefix:
storage (mapped to storage.googleapis.com)
- Metric Keywords:
write, throughput, request, count
- Mapped Substrings:
write, throughput, request_count, count
Step 3: Query Metric Descriptors via list_metric_descriptors Tool
Query all metric descriptors for each identified service prefix using the
list_metric_descriptors MCP tool (using pageSize: 200). Because Cloud
Monitoring filters do not allow combining multiple metric.type restrictions
with OR, you must initiate a separate query for each identified service
prefix (either sequentially or in parallel).
If any response includes a nextPageToken, you MUST make consecutive follow-up
calls passing pageToken until all remaining descriptors for that prefix are
retrieved before filtering.
Filter Pattern Construction: Map the target service domain to its appropriate
prefix style:
- Standard Google Cloud Services:
starts_with("<service_prefix>.googleapis.com/") (such as
bigquery.googleapis.com/, redis.googleapis.com/).
- Ops Agent (Guest OS):
starts_with("agent.googleapis.com/") (for guest
OS memory/disk metrics).
- Kubernetes / GKE Native:
starts_with("kubernetes.io/")
- Istio Service Mesh:
starts_with("istio.io/")
- Knative Serving / Autoscaler:
starts_with("knative.dev/")
- Custom / External Metrics: Use
starts_with("custom.googleapis.com/")
or starts_with("external.googleapis.com/").
Example Tool Call Payload: If both Spanner and Compute Engine are targeted in
the request, execute these two tool calls:
- Spanner query:
{
"name": "projects/my-project-id",
"filter": "metric.type = starts_with(\"spanner.googleapis.com/\")",
"pageSize": 200
}
- Compute Engine query:
{
"name": "projects/my-project-id",
"filter": "metric.type = starts_with(\"compute.googleapis.com/\")",
"pageSize": 200
}
Call the list_metric_descriptors tool with these payloads.
Step 4: Local Filtering & Fallback Protocol
Aggregate all descriptors returned from Step 3, and filter them locally inside
your LLM context:
- Keyword Filtering: Filter the list by matching your target metric
keywords (such as "cpu", "latency") against the
type, displayName, and
description fields of the descriptors.
- Resource Alignment: Check if the metric contains labels matching the
target resource granularity (such as checking for a
database label if
targeting a database resource). Do not attempt to dynamically match resource
type strings directly, as Cloud Monitoring resource mappings (like
Spanner databases mapping to spanner_instance) can be counter-intuitive.
Troubleshooting & API Fallbacks
If any tool call fails, times out, or returns empty results, use these
strategies:
- Case A: API Syntax Error: Examine the error message, correct the filter
syntax, and retry.
- Case B: Timeout / Rate Limits: Retry the call once with a smaller page
size (such as
pageSize: 20).
- Case C: Unrecoverable Failure / Empty List:
- Verify if the target service is enabled in the project.
- Search Google Cloud public documentation to verify standard metrics for
the service.
Step 5: Output Selected Metrics
For each service domain, return only the 5-15 key metrics directly relevant to
the user's intent.
You MUST report the selected metrics in clean Markdown tables, grouped by
service (that is, one table per service prefix). The table MUST include the
following columns: "Metric Type", "Display Name", "Description", "Metric Kind",
"Value Type", "Unit", and "Monitored Resource Types". Map the fields from the
Cloud Monitoring list_metric_descriptors tool call response objects
directly to the table columns:
- Metric Type: Map to the
type field (for example,
spanner.googleapis.com/instance/cpu/utilization).
- Display Name: Map to the
displayName field.
- Description: Map to the
description field.
- Metric Kind: Map to the
metricKind field (for example, GAUGE,
DELTA, CUMULATIVE).
- Value Type: Map to the
valueType field (for example, INT64,
DOUBLE, DISTRIBUTION, BOOL).
- Unit: Map to the
unit field (for example, 1, By, s, ms).
- Monitored Resource Types: Map to the
monitoredResourceTypes list field
(for example, ["spanner_instance"]).
Example Output Table:
| Metric Type |
Display Name |
Description |
Metric Kind |
Value Type |
Unit |
Monitored Resource Types |
spanner.googleapis.com/instance/cpu/utilization |
Instance CPU Utilization |
Fraction of allocated CPU currently in use. |
GAUGE |
DOUBLE |
1 |
["spanner_instance"] |
Reference Documentation & Links
1---2description: Retrieve, query, and identify relevant Cloud Monitoring metric descriptors on Google Cloud for a service or resource (such as Compute Engine, Spanner, BigQuery, Cloud Run, Cloud SQL, Pub/Sub, Cloud Storage, etc.). Use when asked to find, list, search, or discover GCP metric types, names, kind/value schemas, or descriptors.3metadata:4 source: https://skillmd.com/skills/h3y6e/cloud-monitoring-metric-selection5 category: CloudObservabilityAndMonitoring6 github-path: skills/cloud/cloud-monitoring-metric-selection7 github-ref: refs/heads/main8 github-repo: https://github.com/google/skills9 github-tree-sha: 65f518e9b65c9bfe6a7df73b707184fe729e748510 version: 1.0.211name: cloud-monitoring-metric-selection12---1314# Metric Selection (Service Query & Local Keyword Filtering)1516Use this skill to identify the most relevant Cloud Monitoring metric17descriptors. It queries all metric descriptors for a target service from the API18and filters them locally inside the agent's context using keyword matching.1920## Attribution2122**MUST READ**: Before executing any `gcloud`, REST API, or MCP command, you23MUST read [Usage Attribution](references/attribution.md). For commands executed24directly in the terminal (never in generated scripts, Terraform, or user code),25prefix `gcloud` with26`CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:cloud-monitoring-metric-selection)"`27and append `agent-skills/1.0 (skill:cloud-monitoring-metric-selection)` to `User-Agent` headers.2829## CRITICAL RULES3031* **Always Query Live APIs**: You MUST always retrieve the most up-to-date32 metric descriptors dynamically by calling the `list_metric_descriptors` MCP33 tool.34* **Mandatory Project ID and Resource Parameter Clarification**: BEFORE35 calling any API tools (such as `list_metric_descriptors`), you MUST ensure36 the GCP Project ID is provided in the prompt, URI, or environment context.37 If the Project ID cannot be resolved, you MUST ask the user to clarify or38 provide it BEFORE executing API queries. Do NOT run API queries against39 unconfirmed default or placeholder project names (such as `mock-project`,40 `my-project-id`, `unused`, or `YOUR_PROJECT_ID`).41* **Fallback Reporting**: If API calls fail and fallback sources (such as42 public docs) are used, you MUST state the error, the fallback source, and43 the risks of non-live data (such as potential staleness, missing custom44 metrics, or schema mismatches).4546## Workflow4748### Step 1: Verify & Auto-Configure MCP49501. Check if any tool matching `list_metric_descriptors` (such as51 `google-cloud-monitoring:list_metric_descriptors`,52 `mcp_google-cloud-monitoring_list_metric_descriptors`, or a similar pattern)53 is available in your active toolset.542. **Verify via Unique URL**: To ensure you are calling the correct Cloud55 Monitoring tool, confirm that the underlying MCP server configuration56 points to: **`https://monitoring.googleapis.com/mcp`**.573. If the tool is **missing**:5859 * Locate the MCP configuration file for the user's environment. Check60 common paths:61 - `~/.gemini/config/mcp_config.json`62 - `~/.codeium/windsurf/mcp_config.json`63 - `cline_mcp_settings.json`64 - `claude_desktop_config.json`65 * Directly update/merge the configuration file with the following server66 configuration. **CRITICAL**: Merge the JSON object to preserve any67 existing MCP servers in `mcpServers`. Do not overwrite the file.6869 ```json70 "google-cloud-monitoring": {71 "url": "https://monitoring.googleapis.com/mcp",72 "authProviderType": "google_credentials",73 "enabledTools": [74 "list_metric_descriptors"75 ]76 }77 ```7879 * Print a clear message notifying the user that the80 `google-cloud-monitoring` MCP server has been configured, and request81 them to restart or start a new chat session to refresh tools. Stop82 calling further tools and end the turn.8384### Step 2: Analyze Request & Extract Keywords85861. **Resolve Project ID and Identifiers**: Check for the GCP Project ID and87 resource identifiers in the prompt, resource URIs, or environment context.88 According to the CRITICAL RULES above, do NOT use placeholder project names.89902. **Identify Service Prefix**: Map target GCP services to their standard91 prefix (such as `compute`, `spanner`, `bigquery`, `storage`).92933. **Extract Metric Concepts**: Extract metric keywords from user prompt (such94 as "CPU", "memory", "bytes scanned", "latency", "connections") and map to95 search substrings.9697*Example Query Analysis:*9899* **User Prompt**: "Check Cloud Storage bucket write throughput and request100 count"101* **Resource URI**:102 `//storage.googleapis.com/projects/my-project/buckets/my-bucket`103* **Service Prefix**: `storage` (mapped to `storage.googleapis.com`)104* **Metric Keywords**: `write`, `throughput`, `request`, `count`105* **Mapped Substrings**: `write`, `throughput`, `request_count`, `count`106107### Step 3: Query Metric Descriptors via list_metric_descriptors Tool108109Query all metric descriptors for each identified service prefix using the110`list_metric_descriptors` MCP tool (using `pageSize: 200`). Because Cloud111Monitoring filters do not allow combining multiple `metric.type` restrictions112with `OR`, you must **initiate a separate query for each identified service113prefix** (either sequentially or in parallel).114115If any response includes a `nextPageToken`, you MUST make consecutive follow-up116calls passing `pageToken` until all remaining descriptors for that prefix are117retrieved before filtering.118119*Filter Pattern Construction:* Map the target service domain to its appropriate120prefix style:1211221. **Standard Google Cloud Services**:123 `starts_with("<service_prefix>.googleapis.com/")` (such as124 `bigquery.googleapis.com/`, `redis.googleapis.com/`).1252. **Ops Agent (Guest OS)**: `starts_with("agent.googleapis.com/")` (for guest126 OS memory/disk metrics).1273. **Kubernetes / GKE Native**: `starts_with("kubernetes.io/")`1284. **Istio Service Mesh**: `starts_with("istio.io/")`1295. **Knative Serving / Autoscaler**: `starts_with("knative.dev/")`1306. **Custom / External Metrics**: Use `starts_with("custom.googleapis.com/")`131 or `starts_with("external.googleapis.com/")`.132133*Example Tool Call Payload:* If both Spanner and Compute Engine are targeted in134the request, execute these two tool calls:1351361. Spanner query:137138```json139{140 "name": "projects/my-project-id",141 "filter": "metric.type = starts_with(\"spanner.googleapis.com/\")",142 "pageSize": 200143}144```1451461. Compute Engine query:147148```json149{150 "name": "projects/my-project-id",151 "filter": "metric.type = starts_with(\"compute.googleapis.com/\")",152 "pageSize": 200153}154```155156Call the `list_metric_descriptors` tool with these payloads.157158### Step 4: Local Filtering & Fallback Protocol159160Aggregate all descriptors returned from Step 3, and filter them locally inside161your LLM context:1621631. **Keyword Filtering**: Filter the list by matching your target metric164 keywords (such as "cpu", "latency") against the `type`, `displayName`, and165 `description` fields of the descriptors.1662. **Resource Alignment**: Check if the metric contains labels matching the167 target resource granularity (such as checking for a `database` label if168 targeting a database resource). Do not attempt to dynamically match resource169 type strings directly, as Cloud Monitoring resource mappings (like170 Spanner databases mapping to `spanner_instance`) can be counter-intuitive.171172#### Troubleshooting & API Fallbacks173174If any tool call fails, times out, or returns empty results, use these175strategies:176177* **Case A: API Syntax Error**: Examine the error message, correct the filter178 syntax, and retry.179* **Case B: Timeout / Rate Limits**: Retry the call once with a smaller page180 size (such as `pageSize: 20`).181* **Case C: Unrecoverable Failure / Empty List**:182 1. Verify if the target service is enabled in the project.183 2. Search Google Cloud public documentation to verify standard metrics for184 the service.185186### Step 5: Output Selected Metrics187188For each service domain, return only the 5-15 key metrics directly relevant to189the user's intent.190191You MUST report the selected metrics in clean Markdown tables, grouped by192service (that is, one table per service prefix). The table MUST include the193following columns: "Metric Type", "Display Name", "Description", "Metric Kind",194"Value Type", "Unit", and "Monitored Resource Types". Map the fields from the195Cloud Monitoring `list_metric_descriptors` tool call response objects196directly to the table columns:197198* **Metric Type**: Map to the `type` field (for example,199 `spanner.googleapis.com/instance/cpu/utilization`).200* **Display Name**: Map to the `displayName` field.201* **Description**: Map to the `description` field.202* **Metric Kind**: Map to the `metricKind` field (for example, `GAUGE`,203 `DELTA`, `CUMULATIVE`).204* **Value Type**: Map to the `valueType` field (for example, `INT64`,205 `DOUBLE`, `DISTRIBUTION`, `BOOL`).206* **Unit**: Map to the `unit` field (for example, `1`, `By`, `s`, `ms`).207* **Monitored Resource Types**: Map to the `monitoredResourceTypes` list field208 (for example, `["spanner_instance"]`).209210*Example Output Table:*211212Metric Type | Display Name | Description | Metric Kind | Value Type | Unit | Monitored Resource Types213:------------------------------------------------ | :----------------------- | :------------------------------------------ | :---------- | :--------- | :--- | :-----------------------214`spanner.googleapis.com/instance/cpu/utilization` | Instance CPU Utilization | Fraction of allocated CPU currently in use. | GAUGE | DOUBLE | 1 | `["spanner_instance"]`215216## Reference Documentation & Links217218* **Cloud Monitoring Metric List**:219 [GCP Metrics Documentation](https://cloud.google.com/monitoring/api/metrics_gcp)220* **MetricDescriptor MCP Tool Reference**:221 [MCP Tools Reference: monitoring.googleapis.com](https://docs.cloud.google.com/monitoring/api/ref_v3_mcp/mcp/tools_list/list_metric_descriptors)222* **Monitoring Filter Syntax Guide**:223 [Monitoring Filters](https://cloud.google.com/monitoring/api/v3/filters)