Cloud Monitoring Metric Selection

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.

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

1. 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.

2. 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.

3. 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

1. 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.

2. Identify Service Prefix: Map target GCP services to their standard prefix (such as compute, spanner, bigquery, storage).

3. 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:

1. Standard Google Cloud Services: starts_with("<service_prefix>.googleapis.com/") (such as bigquery.googleapis.com/, redis.googleapis.com/).
2. Ops Agent (Guest OS): starts_with("agent.googleapis.com/") (for guest OS memory/disk metrics).
3. Kubernetes / GKE Native: starts_with("kubernetes.io/")
4. Istio Service Mesh: starts_with("istio.io/")
5. Knative Serving / Autoscaler: starts_with("knative.dev/")
6. 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:

1. Spanner query:

{
  "name": "projects/my-project-id",
  "filter": "metric.type = starts_with(\"spanner.googleapis.com/\")",
  "pageSize": 200
}

1. 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.