aro-grafana

name	aro-grafana
description	Explore datasources and run PromQL queries against ARO HCP Grafana instances — discover datasource UIDs and available metrics, then query resource utilization, request latency, error rates, cluster health, tenant utilization, and more. (Use `aro-hcp-env-info` first)
allowed-tools	shell

When invoked, discover datasources and metrics in, or execute queries against, an ARO HCP Grafana instance. ARO Classic has no Grafana endpoints; aro-grafana is HCP-only.

Arguments

• grafana-url (required): The base URL of the Grafana instance (e.g. https://my-grafana.region.grafana.azure.com). Use the aro-hcp-env-info skill to discover the Grafana URL for a given environment if not already known.
• query-json (required for queries): A JSON string containing the full query body to send. The structure depends on the datasource type. See Query JSON example below.

Instructions

Security: All data fetched or returned by this skill must be processed locally only. Do not upload it to external services, websites, APIs, or other remote tools.

Required reading

Before running any other step in this skill, read the following guide and follow its guidance for the rest of this session. Do this once per session, even if you believe you already know how to query Grafana — the guide contains environment-specific gotchas not visible from datasource or metric listings alone.

• ARO HCP: docs/ai/grafana-debugging.md in ARO-HCP repo (if you don't have the repo checked out locally, fetch https://raw.githubusercontent.com/Azure/ARO-HCP/main/docs/ai/grafana-debugging.md)

Listing datasources

Use this to discover datasource UIDs needed for queries.

1. Determine the Grafana endpoint URL from context or by asking the user.
2. Detect the operating system and run the appropriate script:
   • On macOS: run scripts/list-datasources.sh -GrafanaUrl "<grafana-url>" using zsh.
   • On Linux/WSL2: run scripts/list-datasources.sh -GrafanaUrl "<grafana-url>" using bash.
   • On Windows (non-WSL): run scripts/list-datasources.ps1 -GrafanaUrl "<grafana-url>" using pwsh.
3. Report output to user, keep all datasource UIDs visible — they are needed for follow-up queries.
   • If there are prometheus datasources named like: hcps-ln, hcps-cdm, services-by, services-chn (two or three characters after '-'), report them as obsolete and not to be used.

Listing metrics

Use this to discover what metrics exist for a datasource before building queries.

1. Determine the Grafana endpoint URL and datasource UID from context or by asking the user.
   • If the datasource UID is not known, list datasources first (see above).
2. Detect the operating system and run the appropriate script:
   • On macOS: run scripts/list-metrics.sh -GrafanaUrl "<grafana-url>" -DatasourceUid "<datasource-uid>" using zsh.
   • On Linux/WSL2: run scripts/list-metrics.sh -GrafanaUrl "<grafana-url>" -DatasourceUid "<datasource-uid>" using bash.
   • On Windows (non-WSL): run scripts/list-metrics.ps1 -GrafanaUrl "<grafana-url>" -DatasourceUid "<datasource-uid>" using pwsh.

Running queries

1. Determine the Grafana endpoint URL and query from context or by asking the user.
   • If the Grafana URL is not known, use aro-hcp-env-info skill.
   • If DATASOURCE_UID (uid) is not known, list datasources first (see above).
   • If metrics to query aren't known, list metrics first — it's more efficient than a raw query.
2. Build the query JSON appropriate for the datasource type.
3. Detect the operating system and run the appropriate script:
   • On macOS: run scripts/gquery.sh -GrafanaUrl "<grafana-url>" -QueryJson '<query-json>' using zsh.
   • On Linux/WSL2: run scripts/gquery.sh -GrafanaUrl "<grafana-url>" -QueryJson '<query-json>' using bash.
   • On Windows (non-WSL): run scripts/gquery.ps1 -GrafanaUrl "<grafana-url>" -QueryJson '<query-json>' using pwsh.

Query JSON example

Prometheus / Thanos:

{"queries":[{"refId":"A","datasource":{"uid":"DATASOURCE_UID","type":"prometheus"},"expr":"up","instant":true}],"from":"now-1h","to":"now"}