# Set up alerts

Configure triggers to receive email, webhook, or push notifications when your machines need attention. Triggers fire when specific events occur, such as a sensor reading crossing a threshold, a machine going offline, or error logs appearing.

## Types of alerts

| Trigger type          | Fires when                                      | Use case                                               |
|-----------------------|-------------------------------------------------|-------------------------------------------------------|
| Telemetry sync        | Data syncs from a machine to the cloud         | Know when any data arrives                             |
| Conditional telemetry  | Synced data meets a condition you define       | CPU above 80%, temperature below freezing, battery under 20% |
| Machine logs          | Error, warning, or info logs appear             | Catch errors without watching the LOGS tab               |
| Part online           | A machine part comes online                     | Know when a machine reconnects after maintenance       |
| Part offline          | A machine part goes offline                     | Respond to unexpected disconnections                   |

## Prerequisites

##### A running machine connected to Viam.

Add a new machine on [Viam](https://app.viam.com/).
On the machine’s page, follow the setup instructions to install `viam-server` on the computer you’re using for your project.
Wait until your machine has successfully connected to Viam.

## Alert on telemetry

To alert on sensor data, you need three things: a sensor producing data, the data management service capturing and syncing that data, and a trigger that fires when the data arrives or meets a condition.

### Add a performance sensor

To monitor machine health metrics like CPU usage, memory, and temperature, add a performance metrics sensor.

- [Linux](https://docs.viam.com/monitor/alert/#tabset-monitoralert-1-0)
- [macOS](https://docs.viam.com/monitor/alert/#tabset-monitoralert-1-1)

On your machine’s **CONFIGURE** page, click the **+** icon next to your machine part and select **Blocks**.
Search for and add the `hwmonitor:cpu_monitor` model from the [`sbc-hwmonitor`](https://app.viam.com/module/rinzlerlabs/sbc-hwmonitor) module.

You can add additional sensors for memory, temperature, and other metrics.
See the [`sbc-hwmonitor` module page](https://app.viam.com/module/rinzlerlabs/sbc-hwmonitor) for the full list.

First install [`telegraf`](https://github.com/influxdata/telegraf):

```sh
brew install telegraf
```

On your machine’s **CONFIGURE** page, click the **+** icon next to your machine part and select **Component**.
Search for and add the [`viam-sensor:telegrafsensor` model](https://github.com/viam-modules/viam-telegraf-sensor).

You can add additional sensors for other metrics.
See the [`viam-telegraf-sensor` module page](https://app.viam.com/module/viam/viam-telegraf-sensor) for the full list.

Click **Save**, then click **Test** at the bottom of the sensor configuration card to verify readings are coming through.

### Configure data capture

1. On your sensor’s configuration card, click the **Data Capture** button.
2. If you see a “Data management service missing” banner, click **Create data management service**, click **Save**, navigate back to your sensor, and click the **Data Capture** button again.
3. Select `Readings` from the **Method** dropdown and set the **Frequency** to `0.05` Hz (once every 20 seconds).
4. Click **Save**.

To verify data is syncing, click the **…** menu on the sensor card and select **View captured data**.
Wait a minute for data to capture and sync, then refresh.

### Configure the trigger

1. Go to the **CONFIGURE** tab.
Click **+** in the left sidebar and select **Trigger**.
2. Enter a name and click **Create**.
3. In the **Type** dropdown, choose:
   - **Data has been synced to the cloud**: fires whenever data of the selected types syncs.
   - **Conditional data ingestion**: fires when synced data meets a condition you define. Choose the target component and method, then add a condition with a key, operator, and value. For example, to alert when CPU usage exceeds 50%: select your cpu-monitor component, Readings method, key `cpu`, operator `greater than`, value `50`.
4. Add notification methods:
   - **Email specific addresses**: toggle on, add addresses, set alert frequency.
   - **Email all machine owners**: toggle on, set alert frequency.
   - **Webhook**: click **Add webhook**, enter your cloud function URL, set alert frequency.
   - **Push notifications**: click **Add push notifications**, choose the target mobile app, add recipient email addresses or enable notifications for all machine owners, and set alert frequency.  Recipients must be machine owners or operators.
5. Click **Save**.

### Stop data capture

If this is a test, stop data capture to avoid charges for syncing unwanted data. In the **Data capture** section of your sensor’s configuration, toggle the switch to **Off** and click **Save**.

## Alert on machine logs

Configure a trigger that fires when machine logs of a specified level appear. Viam checks for matching logs once per hour.

1. Go to the **CONFIGURE** tab.
Click **+** in the left sidebar and select **Trigger**.
2. Enter a name and click **Create**.
3. Select **Conditional logs ingestion** as the trigger **Type**.
4. Select the log levels to alert on: **Error**, **Warn**, or **Info**.
5. Add notification methods (email, webhook, or push notification) and set the alert frequency.
6. Click **Save**.

## Alert on machine status

### Part online

1. Go to the **CONFIGURE** tab.
Click **+** in the left sidebar and select **Trigger**.
2. Enter a name and click **Create**.
3. Select **Part is online** as the trigger **Type**.
4. Add notification methods.
5. Click **Save**.

Part online triggers fire on every state transition, so you receive a notification each time the part comes online.

### Part offline

1. Go to the **CONFIGURE** tab.
Click **+** in the left sidebar and select **Trigger**.
2. Enter a name and click **Create**.
3. Select **Part is offline** as the trigger **Type**.
4. Add notification methods.
5. Click **Save**.

Part offline triggers fire on every state transition, so you receive a notification each time the part goes offline.

Viam uses a 60-second buffer before declaring a part offline. This prevents false alerts from brief network interruptions.

## Manage alert frequency

For data and conditional triggers, each notification method has a `seconds_between_notifications` setting that controls the minimum time between consecutive alerts. If a trigger fires more frequently than this interval, Viam suppresses the extra notifications.

- **Safety thresholds**: 60-300 seconds
- **Operational alerts** (elevated CPU, low battery): 300-600 seconds
- **Informational alerts** (data sync confirmations): 3600 seconds or more

### Use the CLI

You can also manage triggers from the command line:

```sh
viam machines part add-trigger --part <part-name-or-id>
```

```sh
viam machines part delete-trigger --part <part-name-or-id> --name <trigger-name>
```

## Other alert types

- For alerts based on data sync events (not tied to machine health), see [Trigger on data events](https://docs.viam.com/data/trigger-on-data/).
- For alerts when an ML model detects specific objects or classifications, see [Alert on detections](https://docs.viam.com/vision/object-detection/alert-on-detections/).
- For full trigger configuration reference, see [Trigger configuration](https://docs.viam.com/reference/triggers/).