| 1 | # Query agent alerts directly |
| 2 | |
| 3 | This guide is part of the [`query-netdata-agents`](./SKILL.md) skill. |
| 4 | Read [SKILL.md](./SKILL.md#prerequisites) first. |
| 5 | |
| 6 | For the alert REST surface (current alerts, transitions, single |
| 7 | config, the `cfg` field of an alert instance, the `options[]` |
| 8 | array on `/alerts`), see |
| 9 | [../query-netdata-cloud/query-alerts.md](../query-netdata-cloud/query-alerts.md). |
| 10 | The body and response of the agent-direct paths are identical to |
| 11 | the per-agent rows of the Cloud-proxied responses. |
| 12 | |
| 13 | Three v3 paths are available on the agent (prefer v3; v2 shares |
| 14 | the same handler; v1 `/alarms*` only on pre-v2 agents): |
| 15 | |
| 16 | | Path | Method | Purpose | |
| 17 | |---|---|---| |
| 18 | | `/api/v3/alerts` | POST | Current alerts on this host | |
| 19 | | `/api/v3/alert_transitions` | POST | Alert transition history | |
| 20 | | `/api/v3/alert_config?config=<hash>` | GET | Full configuration of one alert | |
| 21 | |
| 22 | Silencing rules, `alerts:misconfigured`, alert-config |
| 23 | generate/suggest/explain, and `alarms`/`alarms/metas` are |
| 24 | **Cloud-only** -- there is no agent-direct equivalent. See |
| 25 | [../query-netdata-cloud/query-alerts.md](../query-netdata-cloud/query-alerts.md). |
| 26 | |
| 27 | --- |
| 28 | |
| 29 | ## Use the wrapper |
| 30 | |
| 31 | ```bash |
| 32 | source "$(git rev-parse --show-toplevel)/.agents/skills/query-netdata-agents/scripts/_lib.sh" |
| 33 | agents_load_env |
| 34 | |
| 35 | # Currently-firing alerts on this host with summary + values + instances. |
| 36 | agents_query_agent \ |
| 37 | --node "$NODE_UUID" \ |
| 38 | --host "$AGENT_HOST:19999" \ |
| 39 | --machine-guid "$AGENT_MG" \ |
| 40 | POST /api/v3/alerts '{"options":["summary","values","instances"]}' |
| 41 | |
| 42 | # Transitions over the last hour. NOTE: agent /alert_transitions |
| 43 | # accepts negative `after` values too (different from cloud). |
| 44 | AFTER=$(( $(date +%s) - 3600 )) |
| 45 | NOW=$(date +%s) |
| 46 | agents_query_agent \ |
| 47 | --node "$NODE_UUID" \ |
| 48 | --host "$AGENT_HOST:19999" \ |
| 49 | --machine-guid "$AGENT_MG" \ |
| 50 | POST /api/v3/alert_transitions "{\"after\":$AFTER,\"before\":$NOW}" |
| 51 | |
| 52 | # Read a specific alert's config. Get the hash from .alert_instances[].cfg. |
| 53 | CFG="ALERT_CONFIG_HASH_UUID" # the cfg field of an alert instance |
| 54 | agents_query_agent \ |
| 55 | --node "$NODE_UUID" \ |
| 56 | --host "$AGENT_HOST:19999" \ |
| 57 | --machine-guid "$AGENT_MG" \ |
| 58 | GET "/api/v3/alert_config?config=$CFG" |
| 59 | ``` |
| 60 | |
| 61 | ## Limits and gotchas |
| 62 | |
| 63 | - **Single host.** Aggregation across nodes is Cloud's job. |
| 64 | - **Compact field names**: `cfg`, `nm`, `ctx`, `st`, `tr_i`, |
| 65 | `tr_v`, `tr_t`, `cl`, `cp`, `tp`, `to`. Spelled-out |
| 66 | cross-reference is in the cloud guide. |
| 67 | - **`config_hash_id` source**: the `cfg` field on an alert |
| 68 | instance from `/api/v3/alerts` (with `options:["instances"]`) |
| 69 | is what to pass as `config=` to `/alert_config`. |
| 70 | |
| 71 | ## See also |
| 72 | |
| 73 | - [../query-netdata-cloud/query-alerts.md](../query-netdata-cloud/query-alerts.md) |
| 74 | -- full alerts surface (Cloud + agent), including everything |
| 75 | Cloud-only (silencing, generate/suggest/explain, etc.). |