Set up alerts | Viam Documentation

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. 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.

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 module.

You can add additional sensors for memory, temperature, and other metrics. See the sbc-hwmonitor module page for the full list.

First install telegraf:

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.

You can add additional sensors for other metrics. See the viam-telegraf-sensor module page 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.

Use the CLI

You can also manage triggers from the command line:

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

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

Other alert types