> For the complete documentation index, see [llms.txt](https://adatrack.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://adatrack.gitbook.io/docs/documentation/features/alerting.md).

# Alerting Engine

AdaTrack's **Alerting Engine** allows you to monitor your telemetry data and receive instant notifications when specific conditions are met. While [Geofencing](/docs/documentation/features/geofencing.md) handles spatial triggers, the Alerting Engine monitors sensor data, device state, and battery health.

### How it Works

1. **Ingestion:** A UDP packet arrives and is decoded into a JSON object.
2. **Evaluation:** The Alerting Engine immediately checks the decoded data against your active **Telemetry Rules**.
3. **Trigger:** If the conditions are met (and the rule is not in its cooldown period), an alert event is recorded.
4. **Dispatch:** If the rule has a notification channel configured, the alert is sent to that channel (Slack, Email, Webhook, etc.). Rules without a channel still fire — they can trigger workflows without sending a notification.

### Telemetry Rules

A **Telemetry Rule** defines the logic for triggering an alert. You can create these rules through our no-code builder.

#### Rule Components:

* **Scope:** The specific **Device** or **Device Profile** the rule applies to.
* **Logic Gate:** Use `AND` or `OR` to combine multiple conditions.
* **Conditions:** The actual logic (e.g., `temperature > 50` AND `battery < 10`).
* **Severity:** Categorize alerts as `Info`, `Warning`, or `Critical`.
* **Cooldown:** The minimum time to wait before triggering the same alert again (prevents notification spam).
* **Notification Channel** *(optional):* Where to send the alert. Leave blank to use the rule purely as a [workflow trigger](/docs/documentation/features/workflows.md) without sending any notification.

### Condition Operators

The Alerting Engine supports several operators for comparing telemetry fields:

| Operator   | Description                                         | Example                  |
| ---------- | --------------------------------------------------- | ------------------------ |
| `equals`   | Exact match (string or number).                     | `status == "error"`      |
| `>`        | Greater than.                                       | `temperature > 40`       |
| `<`        | Less than.                                          | `voltage < 3.2`          |
| `contains` | Checks if a string contains a substring.            | `msg contains "failure"` |
| `exists`   | Checks if a specific key is present in the payload. | `exists error_code`      |

### Alert Channels

AdaTrack supports multiple destinations for your alerts:

* **Email:** Receive detailed alerts with a link to the device's live position.
* **Slack:** Direct notifications to a specific channel using Webhooks.
* **Webhooks:** Send a POST request with the alert payload to any external service or custom API.
* **Telegram:** Receive instant notifications via a Telegram Bot.

### Acknowledging & Snoozing Alerts

Fired alerts don't have to sit in your feed forever. From the **Alert Feed** dashboard widget you can:

* **Acknowledge** an alert to mark it as seen and handled — it's flagged with an "Acknowledged" badge for anyone else viewing the same dashboard.
* **Snooze** an alert for 15 minutes, 1 hour, 4 hours, or 24 hours if you're already aware of the issue and don't want it competing for attention right now.

Both actions sync instantly to every open dashboard tab, and are also available from the Chat Bot plugin via the `/ack <short-id>` and `/snooze <short-id> <duration>` commands.

### Custom Message Templates

You can customize the text of your notifications using **Message Templates**. These allow you to inject real-time data into the alert message:

* `Device {device_name} is overheating! Current temp: {temperature} C.`
* `Warning: Low battery detected on {device_id}. Remaining: {battery}%`

### Best Practices

* **Set Appropriate Cooldowns:** For sensors that report frequently (e.g., every 30 seconds), set a cooldown of 30-60 minutes to avoid flooding your inbox.
* **Use Severity Levels:** Configure different channels for different severities. For example, send `Info` alerts to Slack and `Critical` alerts to both Slack and Email.
* **Validate with Test Packets:** Use a simulator or a test device to trigger your rules and ensure the notifications are formatted as expected before deploying to your entire fleet.