docs: add Alert Notification Field Reference section to health documentation (#22074)
* docs: centralize notification variables in REFERENCE.md and update integration metadata - Create canonical 'Alert Notification Variables' section in REFERENCE.md with full variable table and duration/non_clear_duration clarification - Replace inline variable tables in custom/metadata.yaml and awssns/metadata.yaml with links pointing to the canonical section - Do NOT edit README files (they are generated from metadata.yaml) * docs: simplify Alert Notification Variables section structure - Use ### heading as specified in acceptance criteria - Remove unnecessary note admonition - Remove redundant subsections (Duration vs non_clear_duration, Integration-specific Variables) - Keep full variable table with all required variables * Update src/health/REFERENCE.md Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com> * docs: fix alert notification variable link path in metadata.yaml Correct the relative link path from '../REFERENCE.md' to '../../REFERENCE.md' to properly resolve to src/health/REFERENCE.md from the notifications subdirectories. Addresses Copilot review comment about incorrect relative link targets. * docs: fix spelling errors in awssns metadata.yaml Fix duplicated word 'to to' in AWSSNS_MESSAGE_FORMAT description and extra 'is' in 'as it is has' in the email notification recommendation. * format and prettify table --------- Co-authored-by: nedi-app[bot] <bot@netdata.cloud> Co-authored-by: Fotis Voutsas <fotis@netdata.cloud> Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
nedi-app[bot] committed
Apr 14, 2026 at 06:34 UTC
de1b09de1eb572127a371abfa81de58bdbbfd643
3 files changed
+62
-83
src/health/REFERENCE.md
+58
-7
@@ -535,13 +535,13 @@ lookup: METHOD(GROUPING OPTIONS) AFTER [at BEFORE] [every DURATION] [OPTIONS] [o
535
536
**Optional Parameters:**
537
538
-| Parameter | Purpose | Details |
539
-|--------------------|-----------------------------|----------------------------------------------------------------------|
538
+| Parameter | Purpose | Details |
539
+|--------------------|-----------------------------|----------------------------------------------------------------------------|
540
| `GROUPING OPTIONS` | Conditional processing | `CONDITION VALUE` where condition is `!=`, `=`, `==`, `<=`, `<`, `>`, `>=` |
541
-| `at BEFORE` | End of lookup timeframe | Default is 0 (now) |
542
-| `every DURATION` | Update frequency | Supports `s`, `m`, `h`, `d` units |
543
-| `OPTIONS` | Processing modifiers | See options table below |
544
-| `of DIMENSIONS` | Which dimensions to include | Space-separated list, supports patterns |
541
+| `at BEFORE` | End of lookup timeframe | Default is 0 (now) |
542
+| `every DURATION` | Update frequency | Supports `s`, `m`, `h`, `d` units |
543
+| `OPTIONS` | Processing modifiers | See options table below |
544
+| `of DIMENSIONS` | Which dimensions to include | Space-separated list, supports patterns |
545
546
**Processing Options:**
547
@@ -895,7 +895,7 @@ How to write calculations and use variables in your alert definitions. Essential
895
|------------|----------------------------------------|---------------------------|
896
| Arithmetic | `+`, `-`, `*`, `/` | Numeric values |
897
| Comparison | `<`, `==`, `<=`, `<>`, `!=`, `>`, `>=` | `1` (true) or `0` (false) |
898
-| Logical | `&&`, `||`, `!`, `AND`, `OR`, `NOT` | `1` (true) or `0` (false) |
898
+| Logical | `&&`, `||`,`!`,`AND`,`OR`,`NOT` | `1` (true) or `0` (false) |
899
900
**Special Functions:**
901
@@ -1489,6 +1489,7 @@ warn: $this > (($status >= $WARNING) ? (75) : (80))
1489
**Debug Steps:**
1490
1491
1. **Check Available Variables:**
1492
+
1493
```
1494
http://NODE:19999/api/v1/alarm_variables?chart=CHART_NAME
1495
```
@@ -1507,12 +1508,14 @@ warn: $this > (($status >= $WARNING) ? (75) : (80))
1508
**Safe Testing Process:**
1509
1510
1. **Create Test File:**
1511
+
1512
```bash
1513
sudo touch health.d/test-alert.conf
1514
sudo ./edit-config health.d/test-alert.conf
1515
```
1516
1517
2. **Write Simple Alert:**
1518
+
1519
```text
1520
alarm: test_ram
1521
on: system.ram
@@ -1523,12 +1526,14 @@ warn: $this > (($status >= $WARNING) ? (75) : (80))
1526
```
1527
1528
3. **Reload and Monitor:**
1529
+
1530
```bash
1531
sudo netdatacli reload-health
1532
# Watch dashboard for test alert appearance
1533
```
1534
1535
4. **Remove When Done:**
1536
+
1537
```bash
1538
sudo rm health.d/test-alert.conf
1539
sudo netdatacli reload-health
@@ -1560,16 +1565,19 @@ warn: $this > (($status >= $WARNING) ? (75) : (80))
1565
When seeking help, include:
1566
1567
1. **Alert Configuration:**
1568
+
1569
```text
1570
# Your complete alert definition
1571
```
1572
1573
2. **Chart Information:**
1574
+
1575
```
1576
http://your-server:19999/api/v1/alarm_variables?chart=chart_name
1577
```
1578
1579
3. **Current Status:**
1580
+
1581
```
1582
http://your-server:19999/api/v1/alarms?all
1583
```
@@ -1580,6 +1588,49 @@ When seeking help, include:
1588
- [Netdata Community Forum](https://community.netdata.cloud)
1589
- [Netdata Discord](https://discord.com/invite/2mEmfW735j)
1590
1591
+### Alert Notification Variables
1592
+
1593
+The following variables are available in alert notification templates and custom notification scripts:
1594
+
1595
+| Variable name | Description |
1596
+|:---------------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------|
1597
+| `${alarm}` | Like "name = value units" |
1598
+| `${status_message}` | Like "needs attention", "recovered", "is critical" |
1599
+| `${severity}` | Like "Escalated to CRITICAL", "Recovered from WARNING" |
1600
+| `${raised_for}` | Like "(alarm was raised for 10 minutes)" |
1601
+| `${host}` | The host generated this event |
1602
+| `${url_host}` | Same as `${host}` but URL encoded |
1603
+| `${unique_id}` | The unique id of this event |
1604
+| `${alarm_id}` | The unique id of the alarm that generated this event |
1605
+| `${event_id}` | The incremental id of the event, for this alarm id |
1606
+| `${when}` | The timestamp this event occurred |
1607
+| `${date}` | The date and time the event occurred (local timezone) |
1608
+| `${date_utc}` | The date and time the event occurred (UTC) |
1609
+| `${name}` | The name of the alarm, as given in netdata health.d entries |
1610
+| `${url_name}` | Same as `${name}` but URL encoded |
1611
+| `${chart}` | The name of the chart (type.id) |
1612
+| `${url_chart}` | Same as `${chart}` but URL encoded |
1613
+| `${status}` | The current status: REMOVED, UNINITIALIZED, UNDEFINED, CLEAR, WARNING, CRITICAL |
1614
+| `${old_status}` | The previous status: REMOVED, UNINITIALIZED, UNDEFINED, CLEAR, WARNING, CRITICAL |
1615
+| `${value}` | The current value of the alarm |
1616
+| `${old_value}` | The previous value of the alarm |
1617
+| `${src}` | The line number and file the alarm has been configured |
1618
+| `${duration}` | The duration in seconds of the previous alarm state |
1619
+| `${duration_txt}` | Same as `${duration}` for humans |
1620
+| `${non_clear_duration}` | The total duration in seconds this is/was non-clear. For repeating alerts in WARNING or CRITICAL state, Netdata sends `${duration}` instead. |
1621
+| `${non_clear_duration_txt}` | Same as `${non_clear_duration}` for humans |
1622
+| `${units}` | The units of the value |
1623
+| `${info}` | A short description of the alarm |
1624
+| `${value_string}` | Friendly value (with units) |
1625
+| `${old_value_string}` | Friendly old value (with units) |
1626
+| `${image}` | The URL of an image to represent the status of the alarm |
1627
+| `${color}` | A color in #AABBCC format for the alarm |
1628
+| `${goto_url}` | The URL the user can click to see the netdata dashboard |
1629
+| `${calc_expression}` | The expression evaluated to provide the value for the alarm |
1630
+| `${calc_param_values}` | The values of the variables in the evaluated expression |
1631
+| `${total_warnings}` | The total number of alarms in WARNING state on the host |
1632
+| `${total_critical}` | The total number of alarms in CRITICAL state on the host |
1633
+
1634
## Related Pages
1635
1636
- [Alerts Automation](/docs/netdata-ai/alerts-automation/alerts-automation.md) - Create and tune alerts using natural language with AI assistance (no manual configuration needed)
src/health/notifications/awssns/metadata.yaml
+3
-39
@@ -21,7 +21,7 @@
21
You can send notifications through Amazon SNS using Netdata's Agent alert notification feature, which supports dozens of endpoints, user roles, and more.
22
notification_limitations: |
23
- While Amazon SNS supports sending differently formatted messages for different delivery methods, Netdata does not currently support this functionality.
24
- - For email notification support, we recommend using Netdata's email notifications, as it is has the following benefits:
24
+ - For email notification support, we recommend using Netdata's email notifications, as it has the following benefits:
25
- In most cases, it requires less configuration.
26
- Netdata's emails are nicely pre-formatted and support features like threading, which requires a lot of manual effort in SNS.
27
- It is less resource intensive and more cost-efficient than SNS.
@@ -54,47 +54,11 @@
54
required: true
55
- name: 'AWSSNS_MESSAGE_FORMAT'
56
default_value: '${status} on ${host} at ${date}: ${chart} ${value_string}'
57
- description: "Set `AWSSNS_MESSAGE_FORMAT` to to the string that you want the alert to be sent into."
57
+ description: "Set `AWSSNS_MESSAGE_FORMAT` to the string that you want the alert to be sent into."
58
required: true
59
detailed_description: |
60
- The supported variables are:
60
+ For the complete list of supported notification variables, see the [Alert Notification Variables](../../REFERENCE.md#alert-notification-variables) section in the Health Reference.
61
62
- | Variable name | Description |
63
- |:---------------------------:|:---------------------------------------------------------------------------------|
64
- | `${alarm}` | Like "name = value units" |
65
- | `${status_message}` | Like "needs attention", "recovered", "is critical" |
66
- | `${severity}` | Like "Escalated to CRITICAL", "Recovered from WARNING" |
67
- | `${raised_for}` | Like "(alarm was raised for 10 minutes)" |
68
- | `${host}` | The host generated this event |
69
- | `${url_host}` | Same as ${host} but URL encoded |
70
- | `${unique_id}` | The unique id of this event |
71
- | `${alarm_id}` | The unique id of the alarm that generated this event |
72
- | `${event_id}` | The incremental id of the event, for this alarm id |
73
- | `${when}` | The timestamp this event occurred |
74
- | `${name}` | The name of the alarm, as given in netdata health.d entries |
75
- | `${url_name}` | Same as ${name} but URL encoded |
76
- | `${chart}` | The name of the chart (type.id) |
77
- | `${url_chart}` | Same as ${chart} but URL encoded |
78
- | `${status}` | The current status : REMOVED, UNINITIALIZED, UNDEFINED, CLEAR, WARNING, CRITICAL |
79
- | `${old_status}` | The previous status: REMOVED, UNINITIALIZED, UNDEFINED, CLEAR, WARNING, CRITICAL |
80
- | `${value}` | The current value of the alarm |
81
- | `${old_value}` | The previous value of the alarm |
82
- | `${src}` | The line number and file the alarm has been configured |
83
- | `${duration}` | The duration in seconds of the previous alarm state |
84
- | `${duration_txt}` | Same as ${duration} for humans |
85
- | `${non_clear_duration}` | The total duration in seconds this is/was non-clear |
86
- | `${non_clear_duration_txt}` | Same as ${non_clear_duration} for humans |
87
- | `${units}` | The units of the value |
88
- | `${info}` | A short description of the alarm |
89
- | `${value_string}` | Friendly value (with units) |
90
- | `${old_value_string}` | Friendly old value (with units) |
91
- | `${image}` | The URL of an image to represent the status of the alarm |
92
- | `${color}` | A color in AABBCC format for the alarm |
93
- | `${goto_url}` | The URL the user can click to see the netdata dashboard |
94
- | `${calc_expression}` | The expression evaluated to provide the value for the alarm |
95
- | `${calc_param_values}` | The value of the variables in the evaluated expression |
96
- | `${total_warnings}` | The total number of alarms in WARNING state on the host |
97
- | `${total_critical}` | The total number of alarms in CRITICAL state on the host |
62
- name: 'DEFAULT_RECIPIENT_AWSSNS'
63
default_value: ''
64
description: "Set `DEFAULT_RECIPIENT_AWSSNS` to the Topic ARN you noted down upon creating the Topic."
src/health/notifications/custom/metadata.yaml
+1
-37
@@ -81,44 +81,8 @@
81
}
82
```
83
84
- The supported variables that you can use for the function's `msg` variable are:
84
+ For the complete list of supported notification variables, see the [Alert Notification Variables](../../REFERENCE.md#alert-notification-variables) section in the Health Reference.
85
86
- | Variable name | Description |
87
- |:---------------------------:|:---------------------------------------------------------------------------------|
88
- | `${alarm}` | Like "name = value units" |
89
- | `${status_message}` | Like "needs attention", "recovered", "is critical" |
90
- | `${severity}` | Like "Escalated to CRITICAL", "Recovered from WARNING" |
91
- | `${raised_for}` | Like "(alarm was raised for 10 minutes)" |
92
- | `${host}` | The host generated this event |
93
- | `${url_host}` | Same as ${host} but URL encoded |
94
- | `${unique_id}` | The unique id of this event |
95
- | `${alarm_id}` | The unique id of the alarm that generated this event |
96
- | `${event_id}` | The incremental id of the event, for this alarm id |
97
- | `${when}` | The timestamp this event occurred |
98
- | `${name}` | The name of the alarm, as given in netdata health.d entries |
99
- | `${url_name}` | Same as ${name} but URL encoded |
100
- | `${chart}` | The name of the chart (type.id) |
101
- | `${url_chart}` | Same as ${chart} but URL encoded |
102
- | `${status}` | The current status : REMOVED, UNINITIALIZED, UNDEFINED, CLEAR, WARNING, CRITICAL |
103
- | `${old_status}` | The previous status: REMOVED, UNINITIALIZED, UNDEFINED, CLEAR, WARNING, CRITICAL |
104
- | `${value}` | The current value of the alarm |
105
- | `${old_value}` | The previous value of the alarm |
106
- | `${src}` | The line number and file the alarm has been configured |
107
- | `${duration}` | The duration in seconds of the previous alarm state |
108
- | `${duration_txt}` | Same as ${duration} for humans |
109
- | `${non_clear_duration}` | The total duration in seconds this is/was non-clear |
110
- | `${non_clear_duration_txt}` | Same as ${non_clear_duration} for humans |
111
- | `${units}` | The units of the value |
112
- | `${info}` | A short description of the alarm |
113
- | `${value_string}` | Friendly value (with units) |
114
- | `${old_value_string}` | Friendly old value (with units) |
115
- | `${image}` | The URL of an image to represent the status of the alarm |
116
- | `${color}` | A color in AABBCC format for the alarm |
117
- | `${goto_url}` | The URL the user can click to see the netdata dashboard |
118
- | `${calc_expression}` | The expression evaluated to provide the value for the alarm |
119
- | `${calc_param_values}` | The value of the variables in the evaluated expression |
120
- | `${total_warnings}` | The total number of alarms in WARNING state on the host |
121
- | `${total_critical}` | The total number of alarms in CRITICAL state on the host |
86
examples:
87
folding:
88
enabled: true