Set up alerts

Configure triggers to receive email or webhook 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 typeFires whenUse case
Telemetry syncData syncs from a machine to the cloudKnow when any data arrives
Conditional telemetrySynced data meets a condition you defineCPU above 80%, temperature below freezing, battery under 20%
Machine logsError, warning, or info logs appearCatch errors without watching the LOGS tab
Part onlineA machine part comes onlineKnow when a machine reconnects after maintenance
Part offlineA machine part goes offlineRespond 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 Component or service. 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. See Trigger configuration for webhook payload details.
  5. Click Save.

Add a triggers field to your machine configuration:

"triggers": [
  {
    "name": "trigger-1",
    "event": {
      "type": "part_data_ingested",
      "data_ingested": {
        "data_types": ["binary", "tabular", "file"]
      }
    },
    "notifications": [
      {
        "type": "email",
        "value": "you@example.com",
        "seconds_between_notifications": 300
      }
    ]
  }
]

"triggers": [
  {
    "name": "cpu-alert",
    "event": {
      "type": "conditional_data_ingested",
      "conditional": {
        "data_capture_method": "sensor:cpu-monitor:Readings",
        "conditions": {
          "evals": [
            {
              "operator": "gt",
              "value": {
                "cpu": 50
              }
            }
          ]
        }
      }
    },
    "notifications": [
      {
        "type": "email",
        "value": "you@example.com",
        "seconds_between_notifications": 600
      }
    ]
  }
]

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 or webhook) and set the alert frequency.
  6. Click Save.
"triggers": [
  {
    "name": "error-log-alert",
    "event": {
      "type": "conditional_logs_ingested",
      "log_levels": ["error", "warn"]
    },
    "notifications": [
      {
        "type": "email",
        "value": "you@example.com"
      }
    ]
  }
]

The notification interval for log triggers is always one hour.

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 and set the alert frequency.
  5. Click Save.
"triggers": [
  {
    "name": "machine-online",
    "event": {
      "type": "part_online"
    },
    "notifications": [
      {
        "type": "email",
        "value": "you@example.com",
        "seconds_between_notifications": 600
      }
    ]
  }
]

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 and set the alert frequency.
  5. Click Save.
"triggers": [
  {
    "name": "machine-offline",
    "event": {
      "type": "part_offline"
    },
    "notifications": [
      {
        "type": "email",
        "value": "you@example.com",
        "seconds_between_notifications": 300
      }
    ]
  }
]

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

Manage alert frequency

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

Set this value based on how quickly you need to respond:

  • Critical alerts (machine offline, safety thresholds): 60-300 seconds
  • Operational alerts (elevated CPU, low battery): 300-600 seconds
  • Informational alerts (data sync confirmations): 3600 seconds or more

Starting with a longer interval and shortening it as needed is better than starting short and dealing with notification noise.

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