# ALERTS

> Inspect and configure webhook alerting, and send test alerts.

URL: https://docs.hotkv.com/commands/alerts/

```
ALERTS INFO
ALERTS TEST [info | warning | critical] [message ...]
ALERTS SETURL url
ALERTS SETSEVERITY info | warning | critical
ALERTS ON
ALERTS OFF
```

- Group: Observability
- Complexity: O(1)
- HotKV Cloud: Performance and Scale plans
- On-Premise: requires the enterprise-observability license feature

`ALERTS` manages the alerts HotKV sends to a webhook: Slack, Discord and
Telegram webhooks get messages formatted for them (recognized from the
URL's host), and any other HTTPS URL gets a generic JSON payload. Alerts
are sent in the background, so a slow webhook never delays commands. The
settings live under `[alerts]` in `hotkv.toml` (`alerts.*` in
`hotkv.conf`). The `SETURL`, `SETSEVERITY`, `ON` and `OFF` subcommands
apply at once and also save the change to the server's configuration file,
so it survives a restart; the reply warns you if saving failed.

## Subcommands

| Subcommand | Effect |
| --- | --- |
| `INFO` | Show the alerting configuration and delivery counters (see below). |
| `TEST [severity] [message ...]` | Send a test alert, to check that the webhook works. The severity defaults to the current minimum, so the test is not filtered out; the words after it form the message. |
| `SETURL url` | Set the webhook URL. `""` turns alerting off. The counters start again from 0. |
| `SETSEVERITY level` | Send only alerts of this severity or higher: `info`, `warning` or `critical` (`warn` and `crit` also work). |
| `ON`, `OFF` | Turn alerting on or off without changing the URL (`ENABLE` and `DISABLE` also work). |

The URL must use `https://`, be at most 1024 characters, contain no user
name or password, and by default must not point to a private, loopback,
link-local or cloud metadata address (set `block_private_networks = false`
under `[alerts]` to allow those).

## ALERTS INFO fields

A flat array of field and value pairs, in RESP2 and RESP3:

| Field | Type | Meaning |
| --- | --- | --- |
| `enabled` | Integer | `1` when alerts are sent: a URL is set and alerting is on |
| `flag_enabled` | Integer | The on/off switch of `ON` and `OFF` |
| `webhook_url` | Bulk string | The URL, or `(not configured)` |
| `provider` | Bulk string | `slack`, `discord`, `telegram` or `generic` |
| `supported_providers` | Bulk string | `slack,discord,telegram,generic` |
| `min_severity` | Bulk string | `info`, `warning` or `critical` |
| `alerts_sent` | Integer | Alerts delivered |
| `alerts_failed` | Integer | Alerts the webhook did not accept |
| `alerts_dropped` | Integer | Alerts dropped because the queue was full |
| `alerts_rate_limited` | Integer | Alerts not sent because of the rate limit |
| `alerts_deduped` | Integer | Repeats of a recent alert that were not sent again |
| `alerts_filtered` | Integer | Alerts below the minimum severity |
| `alerts_queued` | Integer | Alerts waiting to be sent |

## Return value

`INFO` replies as above. The others reply with a simple string that starts
with `OK`:

| Subcommand | Reply |
| --- | --- |
| `TEST` | `OK test alert queued (check ALERTS INFO counters for delivery result)` |
| `SETURL` | `OK webhook url updated`, or `OK alerting disabled` for `""` |
| `SETSEVERITY` | `OK min_severity updated` |
| `ON`, `OFF` | `OK alerting enabled`, `OK alerting disabled` |

When the change applies but cannot be written to the configuration file, the
reply is `OK runtime applied (warning: <reason>)`. Errors:

| Case | Error |
| --- | --- |
| `TEST` with no webhook URL | `ERR alerting is not enabled - configure alerts-webhook-url first` |
| `TEST` with an unknown severity | `ERR unknown severity '<level>' - expected one of: info \| warning \| critical` |
| `TEST` not sent (below the minimum, rate limited, a repeat, queue full, or alerting off) | `ERR test alert rejected: <reason>` |
| `SETURL` with a URL that is not allowed | `ERR webhook URL must use https:// scheme`, or another message naming the problem |
| `SETSEVERITY` with an unknown level | `ERR min_severity must be one of: info, warning, critical` |
| Unknown subcommand | `ERR unknown ALERTS subcommand '<name>' - try ALERTS INFO, TEST, SETURL, SETSEVERITY, ON or OFF` |
| No license that includes `enterprise-observability` | `NOLICENSE enterprise-observability requires a HotKV license. Contact sales@hotkv.com` |

## Examples

```
127.0.0.1:6379> ALERTS SETURL https://hooks.slack.com/services/T000/B000/XXXX
OK webhook url updated
127.0.0.1:6379> ALERTS SETSEVERITY warning
OK min_severity updated
127.0.0.1:6379> ALERTS TEST critical Disk almost full on cache-01
OK test alert queued (check ALERTS INFO counters for delivery result)
127.0.0.1:6379> ALERTS TEST info
(error) ERR test alert rejected: severity 'info' is below the configured minimum (warning) - lower ALERTS SETSEVERITY or pick a higher severity
127.0.0.1:6379> ALERTS SETURL http://hooks.example.com/alert
(error) ERR webhook URL must use https:// scheme
127.0.0.1:6379> ALERTS OFF
OK alerting disabled
```

## Compatibility

HotKV-only command. `ALERTS` cannot be called from a script.

## See also

[OBSERVE](https://docs.hotkv.com/commands/observe/index.md), [INFO](https://docs.hotkv.com/commands/info/index.md)