PromQL — 18 Operations for AI Agents
PromQL rules decide when engineers get paged — Prometheus alerts, recording rules, SLO dashboards. act101 reads rule files structurally, so agents understand exactly what an alert measures before changing its threshold.
This page is the canonical reference an AI coding agent uses to refactor, query, and analyze PromQL code through the act MCP server. 18 operations available: 0 refactor, 18 query, 0 analysis. Each operation is callable from Claude Code, Cursor, Codex, OpenCode, or any MCP-compatible agent host. Click any operation for a stable anchor link suitable for citation.
Worked PromQL examples
act101 reads a PromQL expression's function calls as declarations — a top-level rate()/avg_over_time()/aggregation call, or one nested inside a binary expression like a + b, is tagged function and named for the function itself. symbols covers the identical set of calls and their metric arguments but reports every one as kind: unknown, because its rule binds the definition capture to the same leaf metric_name/function_name node the skeleton names, and PromQL's generic Identifier/Call node kinds carry no default symbol kind when no explicit kind is stated. The unit of structure in this grammar is the query expression itself: act101 does not read label matchers, range durations, or by/without grouping clauses in either query. Each example below is the verbatim output of the command shown, run against the file shown. Query outputs are pretty-printed with the timing block omitted.
Read a fleet expression's function calls as a skeleton
inverter-fleet.promql combines two rate() calls over solar_inverter_output_watts at two sites with one avg_over_time() call over solar_panel_temperature_celsius, joined by + and -.
$ act query skeleton inverter-fleet.promqlBefore
rate(solar_inverter_output_watts{site="mesa-1"}[10m]) + rate(solar_inverter_output_watts{site="mesa-2"}[10m]) - avg_over_time(solar_panel_temperature_celsius{site="mesa-1"}[1h])Output
{
"type": "Skeleton",
"declarations": [
{
"kind": "function",
"name": "rate",
"range": {
"start": {
"file": "inverter-fleet.promql",
"line": 1,
"column": 1,
"byte_offset": 0
},
"end": {
"file": "inverter-fleet.promql",
"line": 1,
"column": 54,
"byte_offset": 53
}
},
"name_range": {
"start": {
"file": "inverter-fleet.promql",
"line": 1,
"column": 1,
"byte_offset": 0
},
"end": {
"file": "inverter-fleet.promql",
"line": 1,
"column": 5,
"byte_offset": 4
}
}
},
{
"kind": "function",
"name": "rate",
"range": {
"start": {
"file": "inverter-fleet.promql",
"line": 1,
"column": 57,
"byte_offset": 56
},
"end": {
"file": "inverter-fleet.promql",
"line": 1,
"column": 110,
"byte_offset": 109
}
},
"name_range": {
"start": {
"file": "inverter-fleet.promql",
"line": 1,
"column": 57,
"byte_offset": 56
},
"end": {
"file": "inverter-fleet.promql",
"line": 1,
"column": 61,
"byte_offset": 60
}
}
},
{
"kind": "function",
"name": "avg_over_time",
"range": {
"start": {
"file": "inverter-fleet.promql",
"line": 1,
"column": 113,
"byte_offset": 112
},
"end": {
"file": "inverter-fleet.promql",
"line": 1,
"column": 178,
"byte_offset": 177
}
},
"name_range": {
"start": {
"file": "inverter-fleet.promql",
"line": 1,
"column": 113,
"byte_offset": 112
},
"end": {
"file": "inverter-fleet.promql",
"line": 1,
"column": 126,
"byte_offset": 125
}
}
}
]
}The skeleton reports three function declarations — rate twice and avg_over_time once — one for each function call nested inside the expression's binary operators; the metric names and label matchers inside each call's arguments are not read.
List the same calls and metrics as symbols
The same expression references the same three function calls and their three metric arguments.
$ act query symbols inverter-fleet.promqlBefore
rate(solar_inverter_output_watts{site="mesa-1"}[10m]) + rate(solar_inverter_output_watts{site="mesa-2"}[10m]) - avg_over_time(solar_panel_temperature_celsius{site="mesa-1"}[1h])Output
{
"type": "Symbols",
"symbols": [
{
"name": "rate",
"kind": "unknown",
"range": {
"start": {
"file": "inverter-fleet.promql",
"line": 1,
"column": 1,
"byte_offset": 0
},
"end": {
"file": "inverter-fleet.promql",
"line": 1,
"column": 5,
"byte_offset": 4
}
},
"visibility": "unknown"
},
{
"name": "solar_inverter_output_watts",
"kind": "unknown",
"range": {
"start": {
"file": "inverter-fleet.promql",
"line": 1,
"column": 6,
"byte_offset": 5
},
"end": {
"file": "inverter-fleet.promql",
"line": 1,
"column": 33,
"byte_offset": 32
}
},
"visibility": "unknown"
},
{
"name": "rate",
"kind": "unknown",
"range": {
"start": {
"file": "inverter-fleet.promql",
"line": 1,
"column": 57,
"byte_offset": 56
},
"end": {
"file": "inverter-fleet.promql",
"line": 1,
"column": 61,
"byte_offset": 60
}
},
"visibility": "unknown"
},
{
"name": "solar_inverter_output_watts",
"kind": "unknown",
"range": {
"start": {
"file": "inverter-fleet.promql",
"line": 1,
"column": 62,
"byte_offset": 61
},
"end": {
"file": "inverter-fleet.promql",
"line": 1,
"column": 89,
"byte_offset": 88
}
},
"visibility": "unknown"
},
{
"name": "avg_over_time",
"kind": "unknown",
"range": {
"start": {
"file": "inverter-fleet.promql",
"line": 1,
"column": 113,
"byte_offset": 112
},
"end": {
"file": "inverter-fleet.promql",
"line": 1,
"column": 126,
"byte_offset": 125
}
},
"visibility": "unknown"
},
{
"name": "solar_panel_temperature_celsius",
"kind": "unknown",
"range": {
"start": {
"file": "inverter-fleet.promql",
"line": 1,
"column": 127,
"byte_offset": 126
},
"end": {
"file": "inverter-fleet.promql",
"line": 1,
"column": 158,
"byte_offset": 157
}
},
"visibility": "unknown"
}
]
}symbols reports six entries — rate (twice), avg_over_time, and the metric names solar_inverter_output_watts (twice) and solar_panel_temperature_celsius — all kind: unknown, since the rule's @definition capture states no kind and PromQL's metric/function nodes carry none by default.
Query
18 query tools, the same on every supported language. Descriptions live in the shared reference: /docs/query-tools.
callers control_flow data_flow definition diagnostics effect_closure effect_summary fix_auto get_type graph import_organize interface mutations references repo_outline skeleton symbols symbols_batch