signoz-explaining-alerts
Describe what an existing SigNoz alert rule does in plain language — the signal it watches, the threshold and evaluation behavior, the notification routing, and a one-line fire-frequency summary so the user knows whether the alert has been active. Make sure to use this skill whenever the user asks "what does this alert do", "explain alert X", "walk me through this rule", "how does my [Y] alert work", "is this alert configured correctly", or otherwise asks for an interpretation of an existing alert's configuration. Static explanation only — for diagnosing a specific firing incident, use `signoz-investigating-alerts`.
SigNoz · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add SigNoz/agent-skills --skill signoz-explaining-alertsAbout this skill
name: signoz-explaining-alerts
description: >
Describe what an existing SigNoz alert rule does in plain language:
the signal it watches, the threshold and evaluation behavior, the
notification routing, and a one-line fire-frequency summary so the user
knows whether the alert has been active. Make sure to use this skill
whenever the user asks "what does this alert do", "explain alert X",
"walk me through this rule", "how does my [Y] alert work", "is this
alert configured correctly", or otherwise asks for an interpretation
of an existing alert's configuration. Static explanation only; for
diagnosing a specific firing incident, use signoz-investigating-alerts.
argument-hint:
Alert Explain
Decode an existing SigNoz alert's configuration into a plain-language
explanation. The skill is read-only and stays focused on the rule
itself: what it watches, when it fires, where it notifies. A single
line of fire-frequency data is included to ground the explanation, but
this skill does not investigate any specific fire; that is
signoz-investigating-alerts's job.
Prerequisites
This skill calls SigNoz MCP server tools (signoz_get_alert,
signoz_list_alert_rules, signoz_get_alert_history). Before running
the workflow, confirm the signoz_* tools are available. If they are
not, run signoz-mcp-setup first to initialize or repair the MCP connection.
Do not guess at alert configuration from the rule name alone.
When to use
Use this skill when the user wants to:
- Understand or interpret an existing alert rule.
- Confirm what signal an alert watches and at what threshold.
- Audit whether an alert is reasonably configured.
- Translate raw alert JSON into operational language.
Do NOT use when the user wants to:
- Create a new alert →
signoz-creating-alerts. - Diagnose why an alert fired or correlate signals around a fire window
→
signoz-investigating-alerts. - Modify an existing alert → call
signoz_update_alertdirectly.
Required inputs
| Input | Required | Source if missing |
|---|---|---|
| Alert identifier (rule ID or name) | yes | $ARGUMENTS, recent context, or fuzzy match |
If the input is missing or ambiguous, this skill is best-effort (not strict; read-only operations are cheap to recover from):
- Call
signoz_list_alert_rules, paginate through every page, and find the closest name match. - State the interpretation in the response: "Interpreting your request as alert 'High Error Rate - Checkout' (id 42). If you meant a different one, tell me the name or id."
- Proceed with the explanation. The user can correct after.
Workflow
Step 1: Resolve the alert
If the user provided a rule ID (UUID or legacy numeric ID), skip to Step 2. Otherwise:
- Call
signoz_list_alert_rulesand paginate every page:pagination.hasMoreis true until the full list is walked. - Match by name (case-insensitive substring). If multiple match, present the candidates and ask which one (interactive) or pick the closest and flag the assumption (autonomous).
Step 2: Fetch the full configuration
Call signoz_get_alert with the rule id. This is mandatory: the
list response does not include the full condition / thresholds /
notification settings, and explanations based on the name alone are
guesses.
Step 3: Pull a one-line fire-frequency summary
First call signoz_get_alert_history with timeRange: "7d",
state: "firing", order: "desc", and a large limit. Continue only when
data.nextCursor exists (the completeness note also reports hasMore: true):
pass that value as cursor, replace timeRange with the note's resolved
absolute start and end, and preserve the same state, filter, and order.
Stop when nextCursor is absent / the note reports hasMore: false. Never use
offset or infer completeness from page fullness.
History state accepts inactive, pending, recovering, firing, nodata,
or disabled. For "resolved" / "recovered", use state: "inactive";
resolved is not a value; recovering is a transient keep-firing state, not resolution.
Derive a single rule-level line from the complete set. History rows are emitted
per label-group fingerprint, so never equate row count with alert-fire count.
Count distinct rule transitions where overallStateChanged: true and
overallState: "firing" (deduplicate rows from the same transition timestamp):
Fired N times in the last 7d (last fire: ).
If the user asks about a particular service/host/group instead, partition by
fingerprint and count that series' rows where stateChanged: true and
state: "firing"; include its labels and call the result a series fire, not
a rule-wide fire. A grouped rule can have many series transitions while the
overall rule remains continuously firing.
If the alert never fired in the window, say so explicitly: "Has not fired in the last 7d." If the alert is disabled, mention that separately; disabled rules can still have earlier fires in the lookback.
This single line grounds the explanation. Do not drill into specific
fires here; that's signoz-investigating-alerts.
Step 4: Build the explanation
The single most useful thing for the user is a tight summary. Lead with a TL;DR that directly answers the question they asked, not a generic alert summary. The TL;DR is the only thing some users will read; burying their answer under a fixed template forces them to scroll for what they wanted in the first place.
Match the TL;DR shape to the user's question:
-
"What does this alert do?" / "Explain X": describe what fires:
TL;DR: Fires when
<condition>for<scope>, notifies<channel>.<fire-frequency line>. -
"Is it configured correctly?" / "Audit this" / "Anything I should change?": lead with the verdict and the top 1–3 changes, not the description of what fires:
TL;DR: Mostly well-configured, but recommend: