DOCS-4257: Document log alerting

docs/data-ai/ai/alert.md

@@ -168,16 +168,12 @@ Follow these steps to configure a trigger to alert when `filtered-camera` syncs
 
    1. Click **Add Email**.
 
-      {{<imgproc src="/build/configure/trigger-configured-email.png" resize="x600" style="width: 500px" declaredimensions=true alt="The trigger configured with an example email address." class="shadow imgzoom" >}}
-
    1. Add the email address you wish to be notified whenever this trigger fires.
 
    To add a webhook notification:
 
    1. Click **Add Webhook**.
 
-      {{<imgproc src="/build/configure/trigger-configured.png" resize="x600" style="width: 500px" declaredimensions=true alt="The trigger configured with an example webhook URL." class="shadow imgzoom" >}}
-
    1. Add the URL of your cloud function.
    1. Write your cloud function to process the [webhook data](/data-ai/reference/triggers-configuration/#webhook-attributes).
       Use your cloud function to process data or interact with external APIs, such as Twilio, PagerDuty, or Zapier.

docs/data-ai/data/alert-data.md

@@ -26,8 +26,6 @@ You can configure triggers to fire in the following scenarios:
 1. Go to the **CONFIGURE** tab of your machine.
    Click the **+** (Create) button in the left side menu and select **Trigger**.
 
-   {{<imgproc src="/build/configure/trigger-create.png" resize="x800" declaredimensions=true alt="The Create menu with Trigger at the bottom of the list of options." style="width: 400px" class="shadow imgzoom" >}}
-
 1. Enter a name and click **Create**.
 
 1. In the **Type** dropdown, choose one of the following event types:
@@ -57,7 +55,6 @@ You can configure triggers to fire in the following scenarios:
    To add a webhook:
 
    1. Click **Add Webhook**.
-      {{<imgproc src="/build/configure/trigger-configured.png" resize="x800" style="width: 500px" declaredimensions=true alt="A trigger configured with an example URL." class="shadow imgzoom" >}}
    1. Add the URL of your cloud function.
    1. Configure the time between notifications.
    1. Write your cloud function to process the [webhook](/data-ai/reference/triggers-configuration/#webhook-attributes).
@@ -67,7 +64,6 @@ You can configure triggers to fire in the following scenarios:
    To add an email notification:
 
    1. Click **Add Email**.
-      {{<imgproc src="/build/configure/trigger-configured-email.png" resize="x800" style="width: 500px" declaredimensions=true alt="A trigger configured with an example email." class="shadow imgzoom" >}}
    1. Add the email address where you wish to be notified whenever this trigger fires.
    1. Configure the time between notifications.
 

docs/data-ai/reference/triggers-configuration.md

@@ -14,9 +14,10 @@ Triggers can alert you by email or webhook when any of the following events occu
 - [machine telemetry data syncs from your local device to the Viam cloud](/manage/troubleshoot/alert/)
 - [data syncs from a machine](/data-ai/data/alert-data/)
 - [service detects a specified object or classifies a specified label](/data-ai/ai/alert/)
+- [machine logs contain errors, warnings, or info logs](/manage/troubleshoot/alert/)
 
 This page provides a reference for the Trigger attributes.
-For step-by-step configuration information, see the links above instead.
+For step-by-step configuration information, see the preceding links instead.
 
 ## JSON configuration templates
 
@@ -100,6 +101,30 @@ The following template demonstrates the structure of a JSON configuration for a
 ]
 ```
 
+### Machine logs trigger template
+
+```json {class="line-numbers linkable-line-numbers"}
+"triggers": [
+  {
+    "name": "<trigger name>",
+    "event": {
+      "type": "conditional_logs_ingested",
+      "log_levels": [
+          "error",
+          "warn",
+          "info"
+        ]
+    },
+    "notifications": [
+      {
+        "type": "<webhook|email>",
+        "value": "<webhook URL or email address>"
+      }
+    ]
+  }
+]
+```
+
 ## Trigger attributes
 
 Triggers support the following attributes:
@@ -108,8 +133,8 @@ Triggers support the following attributes:
 | Name | Type | Required? | Description |
 | ---- | ---- | --------- | ----------- |
 | `name` | string | **Required** | The name of the trigger |
-| `event` |  object | **Required** | The trigger event object, which contains the following fields: <ul><li>`type`: The type of the event to trigger on. Options: <ul><li>`part_data_ingested`: fire when data syncs</li> <li>`conditional_data_ingested`: fire when data that meets a certain condition syncs</li> <li>`part_online`: fire when the part is online</li> <li>`part_offline`: fire when the part is offline</li></ul></li><li>`data_types`: Required with `type` `part_data_ingested`. An array of data types that trigger the event. Options: `binary`, `tabular`, `file`, `unspecified`. </li><li> `conditional`: Required when `type` is `conditional_data_ingested`. For more information about this field, see [Conditional attributes](/data-ai/reference/triggers-configuration/#conditional-attributes). </li></ul> |
-| `notifications` |  object | **Required** | The notifications object, which contains the following fields: <ul><li>`type`: The type of the notification. Options: `webhook`, `email`</li><li>`value`: The URL to send the request to or the email address to notify.</li><li>`seconds_between_notifications`: The interval between notifications in seconds.</li></ul> For more information on webhooks, see [Webhook attributes](#webhook-attributes). |
+| `event` |  object | **Required** | The trigger event object, which contains the following fields: <ul><li>`type`: The type of the event to trigger on. Options: <ul><li>`part_data_ingested`: fire when data syncs</li> <li>`conditional_data_ingested`: fire when data that meets a certain condition syncs</li> <li>`part_online`: fire when the part is online</li> <li>`part_offline`: fire when the part is offline</li> <li>`conditional_logs_ingested`: check every hour and fire if logs of the specified log level are present</li></ul></li><li>`data_types`: Required with `type` `part_data_ingested`. An array of data types that trigger the event. Options: `binary`, `tabular`, `file`, `unspecified`. </li><li> `conditional`: Required when `type` is `conditional_data_ingested`. For more information about this field, see [Conditional attributes](/data-ai/reference/triggers-configuration/#conditional-attributes). </li><li> `log_levels`: Required when `type` is `conditional_logs_ingested`. An array of log levels. Options: `error`, `warn`, `info`. </li></ul> |
+| `notifications` |  object | **Required** | The notifications object, which contains the following fields: <ul><li>`type`: The type of the notification. Options: `webhook`, `email`</li><li>`value`: The URL to send the request to or the email address to notify.</li><li>`seconds_between_notifications`: The interval between notifications in seconds. This field is ignored for event type `conditional_logs_ingested` where the interval is always one hour.</li></ul> For more information on webhooks, see [Webhook attributes](#webhook-attributes). |
 | `notes` | string | Optional | Descriptive text to document the purpose, configuration details, or other important information about this trigger. |
 
 ## Conditional attributes
@@ -261,6 +286,9 @@ def trigger():
     data = {}
     if request.data:
         data = request.json
+        # For logs the return type is an array
+        if isinstance(data, list):
+            data = {"logs": data}
     payload = {
         "Org-Id": headers.get('org-id', 'no value'),
         "Organization-Name": headers.get('organization-name', '') or
@@ -281,7 +309,8 @@ def trigger():
         "Data-Type": data.get('data_type', 'no value'),
         "File-Id": data.get('file_id', 'no value'),
         "Trigger-Condition": data.get("trigger_condition", 'no value'),
-        "Data": data.get('data', 'no value')
+        "Data": data.get('data', 'no value'),
+        "Logs": data.get('logs', 'no value')
     }
     print(payload)
 
@@ -307,6 +336,9 @@ def hello_http(request):
     data = {}
     if request.data:
         data = request.json
+        # For logs the return type is an array
+        if isinstance(data, list):
+            data = {"logs": data}
     payload = {
         "Org-Id": headers.get("org-id", "no value"),
         "Organization-Name": headers.get("organization-name", "")
@@ -327,7 +359,8 @@ def hello_http(request):
         "Data-Type": data.get("data_type", "no value"),
         "File-Id": data.get('file_id', "no value"),
         "Trigger-Condition": data.get("trigger_condition", "no value"),
-        "Data": data.get('data', "no value")
+        "Data": data.get('data', 'no value'),
+        "Logs": data.get('logs', 'no value')
     }
     print(payload)
 

docs/manage/troubleshoot/alert.md

@@ -23,10 +23,11 @@ date: "2024-12-07"
 cost: "0"
 ---
 
-You can configure triggers that alert you when machine telemetry data syncs from your local device to the Viam cloud:
+You can configure triggers that alert you when machine telemetry data syncs from your local device to the Viam cloud or based on log messages:
 
 - **Telemetry sync**: Alerts whenever certain telemetry syncs
 - **Conditional telemetry sync**: Alert only when synced telemetry satisfies a condition
+- **Logs**: Alert on error, warning, or info logs appearing on a machine
 
 For example, you can configure a trigger to send you a notification when your machine's CPU usage reaches a certain threshold.
 
@@ -201,8 +202,6 @@ Use **Builder mode** to create a trigger:
 Go to the **CONFIGURE** tab of your machine.
 Click the **+** (Create) button in the left side menu and select **Trigger**.
 
-{{<imgproc src="/build/configure/trigger-create.png" resize="x400" declaredimensions=true alt="The Create menu with Trigger at the bottom of the list of options.">}}
-
 {{< /tablestep >}}
 {{< tablestep >}}
 **Create the trigger**
@@ -245,14 +244,12 @@ To add a notification method, add an entry to the **Webhooks** or **Email** sub-
 To add an email notification:
 
 1.  Click **Add Email**.
-    {{<imgproc src="/build/configure/trigger-configured-email.png" resize="x400" style="width: 500px" declaredimensions=true alt="The trigger configured with an example email." class="shadow" >}}
 1.  Add the email you wish to be notified whenever this trigger is triggered.
 1.  Configure the time between notifications.
 
 To add a webhook notification:
 
 1.  Click **Add Webhook**.
-    {{<imgproc src="/build/configure/trigger-configured.png" resize="x400" style="width: 500px" declaredimensions=true alt="The trigger configured with an example URL." class="shadow" >}}
 1.  Add the URL of your cloud function.
 1.  Configure the time between notifications.
 1.  Write your cloud function to process the [webhook](/data-ai/reference/triggers-configuration/#webhook-attributes).
@@ -338,6 +335,70 @@ In the **Data capture** section of your sensor's configuration, toggle the switc
 
 Click the **Save** button in the top right corner of the page to save your configuration.
 
+## Alert on machine logs
+
+{{< tabs >}}
+{{% tab name="Builder mode" %}}
+
+1. Go to the **CONFIGURE** tab of your machine.
+   Click the **+** (Create) button in the left side menu and select **Trigger**.
+
+1. Name the trigger and click **Create**.
+
+1. Select **Conditional logs ingestion** as the trigger **Type**.
+
+1. Select any number of log levels (**Error**, **Warn**, and **Info**) to alert on.
+
+   **Once per hour**, Viam issues an alert if machine logs are found.
+
+1. To add a notification method, add an entry to the **Webhooks** or **Email** sub-panels:
+
+   To add an email notification:
+
+   1. Click **Add Email**.
+   1. Add the email you wish to be notified whenever this trigger is triggered.
+   1. Configure the time between notifications.
+
+   To add a webhook notification:
+
+   1. Click **Add Webhook**.
+   1. Add the URL of your cloud function.
+   1. Configure the time between notifications.
+   1. Write your cloud function to process the [webhook attributes](/data-ai/reference/triggers-configuration/#webhook-attributes).
+      Use your cloud function to process data or interact with any external API, including Twilio, PagerDuty, or Zapier.
+
+{{% /tab %}}
+{{% tab name="JSON mode" %}}
+
+Use the following template in your `components` JSON to configure the top-level `triggers` field:
+
+```json {class="line-numbers linkable-line-numbers"}
+"triggers": [
+  {
+    "name": "<trigger name>",
+    "event": {
+      "type": "conditional_logs_ingested",
+      "log_levels": [
+          "error",
+          "warn",
+          "info"
+        ]
+    },
+    "notifications": [
+      {
+        "type": "<webhook|email>",
+        "value": "<webhook URL or email address>"
+      }
+    ]
+  }
+]
+```
+
+{{% /tab %}}
+{{< /tabs >}}
+
+For more information about triggers, see [Trigger configuration](/data-ai/reference/triggers-configuration/).
+
 ## Alert on machine status
 
 ### Part is online
@@ -348,8 +409,6 @@ Click the **Save** button in the top right corner of the page to save your confi
 1. Go to the **CONFIGURE** tab of your machine.
    Click the **+** (Create) button in the left side menu and select **Trigger**.
 
-   {{<imgproc src="/build/configure/trigger-create.png" resize="x400" declaredimensions=true alt="The Create menu with Trigger at the bottom of the list of options." class="shadow">}}
-
 2. Name the trigger and click **Create**.
 
 3. Select **Part is online** as the trigger **Type**.
@@ -359,14 +418,12 @@ Click the **Save** button in the top right corner of the page to save your confi
    To add an email notification:
 
    1. Click **Add Email**.
-      {{<imgproc src="/build/configure/trigger-configured-email.png" resize="x400" style="width: 500px" declaredimensions=true alt="The trigger configured with an example email." class="shadow" >}}
    1. Add the email you wish to be notified whenever this trigger is triggered.
    1. Configure the time between notifications.
 
    To add a webhook notification:
 
    1. Click **Add Webhook**.
-      {{<imgproc src="/build/configure/trigger-configured.png" resize="x400" style="width: 500px" declaredimensions=true alt="The trigger configured with an example URL." class="shadow" >}}
    1. Add the URL of your cloud function.
    1. Configure the time between notifications.
    1. Write your cloud function to process the [webhook attributes](/data-ai/reference/triggers-configuration/#webhook-attributes).
@@ -408,8 +465,6 @@ For more information about triggers, see [Trigger configuration](/data-ai/refere
 1. Go to the **CONFIGURE** tab of your machine.
    Click the **+** (Create) button in the left side menu and select **Trigger**.
 
-   {{<imgproc src="/build/configure/trigger-create.png" resize="x400" declaredimensions=true alt="The Create menu with Trigger at the bottom of the list of options." class="shadow">}}
-
 2. Name the trigger and click **Create**.
 
 3. Select **Part is offline** as the trigger **Type**.