1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
|
# Custom Agent alert notifications
Netdata Agent's alert notification feature allows you to send custom notifications to any endpoint you choose.
> ### Note
>
> This file assumes you have read the [Introduction to Agent alert notifications](https://github.com/netdata/netdata/blob/master/health/notifications/README.md), detailing how the Netdata Agent's alert notification method works.
## Prerequisites
You need to have terminal access to the Agent you wish to configure.
## Configure Netdata to send alert notifications to a custom endpoint
> ### Info
>
> This file mentions editing configuration files.
>
> - To edit configuration files in a safe way, we provide the [`edit config` script](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md#use-edit-config-to-edit-configuration-files) located in your [Netdata config directory](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md#the-netdata-config-directory) (typically is `/etc/netdata`) that creates the proper file and opens it in an editor automatically.
> Note that to run the script you need to be inside your Netdata config directory.
>
> It is recommended to use this way for configuring Netdata.
Edit `health_alarm_notify.conf`, changes to this file do not require restarting Netdata:
1. Set `SEND_CUSTOM` to `YES`.
2. The `DEFAULT_RECIPIENT_CUSTOM`'s value is dependent on how you handle the `${to}` variable inside the `custom_sender()` function.
All roles will default to this variable if left unconfigured.
3. Edit the `custom_sender()` function.
You can look at the other senders in `/usr/libexec/netdata/plugins.d/alarm-notify.sh` for examples of how to modify the function in this configuration file.
The following is a sample `custom_sender()` function in `health_alarm_notify.conf`, to send an SMS via an imaginary HTTPS endpoint to the SMS gateway:
```sh
custom_sender() {
# example human readable SMS
local msg="${host} ${status_message}: ${alarm} ${raised_for}"
# limit it to 160 characters and encode it for use in a URL
urlencode "${msg:0:160}" >/dev/null; msg="${REPLY}"
# a space separated list of the recipients to send alarms to
to="${1}"
for phone in ${to}; do
httpcode=$(docurl -X POST \
--data-urlencode "From=XXX" \
--data-urlencode "To=${phone}" \
--data-urlencode "Body=${msg}" \
-u "${accountsid}:${accounttoken}" \
https://domain.website.com/)
if [ "${httpcode}" = "200" ]; then
info "sent custom notification ${msg} to ${phone}"
sent=$((sent + 1))
else
error "failed to send custom notification ${msg} to ${phone} with HTTP error code ${httpcode}."
fi
done
}
```
The supported variables that you can use for the function's `msg` variable are:
| Variable name | Description |
|:---------------------------:|:---------------------------------------------------------------------------------|
| `${alarm}` | Like "name = value units" |
| `${status_message}` | Like "needs attention", "recovered", "is critical" |
| `${severity}` | Like "Escalated to CRITICAL", "Recovered from WARNING" |
| `${raised_for}` | Like "(alarm was raised for 10 minutes)" |
| `${host}` | The host generated this event |
| `${url_host}` | Same as ${host} but URL encoded |
| `${unique_id}` | The unique id of this event |
| `${alarm_id}` | The unique id of the alarm that generated this event |
| `${event_id}` | The incremental id of the event, for this alarm id |
| `${when}` | The timestamp this event occurred |
| `${name}` | The name of the alarm, as given in netdata health.d entries |
| `${url_name}` | Same as ${name} but URL encoded |
| `${chart}` | The name of the chart (type.id) |
| `${url_chart}` | Same as ${chart} but URL encoded |
| `${family}` | The family of the chart |
| `${url_family}` | Same as ${family} but URL encoded |
| `${status}` | The current status : REMOVED, UNINITIALIZED, UNDEFINED, CLEAR, WARNING, CRITICAL |
| `${old_status}` | The previous status: REMOVED, UNINITIALIZED, UNDEFINED, CLEAR, WARNING, CRITICAL |
| `${value}` | The current value of the alarm |
| `${old_value}` | The previous value of the alarm |
| `${src}` | The line number and file the alarm has been configured |
| `${duration}` | The duration in seconds of the previous alarm state |
| `${duration_txt}` | Same as ${duration} for humans |
| `${non_clear_duration}` | The total duration in seconds this is/was non-clear |
| `${non_clear_duration_txt}` | Same as ${non_clear_duration} for humans |
| `${units}` | The units of the value |
| `${info}` | A short description of the alarm |
| `${value_string}` | Friendly value (with units) |
| `${old_value_string}` | Friendly old value (with units) |
| `${image}` | The URL of an image to represent the status of the alarm |
| `${color}` | A color in AABBCC format for the alarm |
| `${goto_url}` | The URL the user can click to see the netdata dashboard |
| `${calc_expression}` | The expression evaluated to provide the value for the alarm |
| `${calc_param_values}` | The value of the variables in the evaluated expression |
| `${total_warnings}` | The total number of alarms in WARNING state on the host |
| `${total_critical}` | The total number of alarms in CRITICAL state on the host |
You can then have different `${to}` variables per **role**, by editing `DEFAULT_RECIPIENT_CUSTOM` with the variable you want, in the following entries at the bottom of the same file:
```conf
role_recipients_custom[sysadmin]="systems"
role_recipients_custom[domainadmin]="domains"
role_recipients_custom[dba]="databases systems"
role_recipients_custom[webmaster]="marketing development"
role_recipients_custom[proxyadmin]="proxy-admin"
role_recipients_custom[sitemgr]="sites"
```
An example working configuration would be:
```conf
#------------------------------------------------------------------------------
# custom notifications
SEND_CUSTOM="YES"
DEFAULT_RECIPIENT_CUSTOM=""
# The custom_sender() is a custom function to do whatever you need to do
custom_sender() {
# example human readable SMS
local msg="${host} ${status_message}: ${alarm} ${raised_for}"
# limit it to 160 characters and encode it for use in a URL
urlencode "${msg:0:160}" >/dev/null; msg="${REPLY}"
# a space separated list of the recipients to send alarms to
to="${1}"
for phone in ${to}; do
httpcode=$(docurl -X POST \
--data-urlencode "From=XXX" \
--data-urlencode "To=${phone}" \
--data-urlencode "Body=${msg}" \
-u "${accountsid}:${accounttoken}" \
https://domain.website.com/)
if [ "${httpcode}" = "200" ]; then
info "sent custom notification ${msg} to ${phone}"
sent=$((sent + 1))
else
error "failed to send custom notification ${msg} to ${phone} with HTTP error code ${httpcode}."
fi
done
}
```
## Test the notification method
To test this alert notification method refer to the ["Testing Alert Notifications"](https://github.com/netdata/netdata/blob/master/health/notifications/README.md#testing-alert-notifications) section of the Agent alert notifications page.
|
