cloud-monitoring-metric-selection

Files (2)

• SKILL.md
• attribution.md · references/

SKILL.md (first lines)

# 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](references/attribution.md). 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

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.

        ```json
        "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/")`.

From google/skills, Apache-2.0.

More from google/skills