@cryptotaxi247 / netdata
Code Commits Issues Pulls Sessions CI/CD
master
master
md 152 lines 6.09 KB
Rendered Raw
1 <!--startmeta
2 custom_edit_url: "https://github.com/netdata/netdata/edit/master/src/health/notifications/awssns/README.md"
3 meta_yaml: "https://github.com/netdata/netdata/edit/master/src/health/notifications/awssns/metadata.yaml"
4 sidebar_label: "AWS SNS"
5 learn_status: "Published"
6 learn_rel_path: "Alerts & Notifications/Notifications/Agent Dispatched Notifications"
7 keywords: ['AWS SNS']
8 message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE NOTIFICATION'S metadata.yaml FILE"
9 endmeta-->
10
11 # AWS SNS
12
13
14 <img src="https://netdata.cloud/img/aws.svg" width="150"/>
15
16
17 As part of its AWS suite, Amazon provides a notification broker service called 'Simple Notification Service' (SNS). Amazon SNS works similarly to Netdata's own notification system, allowing to dispatch a single notification to multiple subscribers of different types. Among other things, SNS supports sending notifications to:
18 - Email addresses
19 - Mobile Phones via SMS
20 - HTTP or HTTPS web hooks
21 - AWS Lambda functions
22 - AWS SQS queues
23 - Mobile applications via push notifications
24 You can send notifications through Amazon SNS using Netdata's Agent alert notification feature, which supports dozens of endpoints, user roles, and more.
25
26
27 <img src="https://img.shields.io/badge/maintained%20by-Netdata-%2300ab44" />
28
29 ## Limitations
30
31 - While Amazon SNS supports sending differently formatted messages for different delivery methods, Netdata does not currently support this functionality.
32 - For email notification support, we recommend using Netdata's email notifications, as it has the following benefits:
33 - In most cases, it requires less configuration.
34 - Netdata's emails are nicely pre-formatted and support features like threading, which requires a lot of manual effort in SNS.
35 - It is less resource intensive and more cost-efficient than SNS.
36
37
38 ## Setup
39
40
41 ### Prerequisites
42
43 ####
44
45 - The [Amazon Web Services CLI tools](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) (awscli).
46 - An actual home directory for the user you run Netdata as, instead of just using `/` as a home directory. The setup depends on the distribution, but `/var/lib/netdata` is the recommended directory. If you are using Netdata as a dedicated user, the permissions will already be correct.
47 - An Amazon SNS topic to send notifications to with one or more subscribers. The Getting Started section of the Amazon SNS documentation covers the basics of how to set this up. Make note of the Topic ARN when you create the topic.
48 - While not mandatory, it is highly recommended to create a dedicated IAM user on your account for Netdata to send notifications. This user needs to have programmatic access, and should only allow access to SNS. For an additional layer of security, you can create one for each system or group of systems.
49 - Terminal access to the Agent you wish to configure.
50
51
52
53 ### Configuration
54
55 #### Options
56
57 The following options can be defined for this notification
58
59 <details open><summary>Config Options</summary>
60
61
62
63 | Option | Description | Default | Required |
64 |:-----|:------------|:--------|:---------:|
65 | aws path | The full path of the aws command. If empty, the system `$PATH` will be searched for it. If not found, Amazon SNS notifications will be silently disabled. | | yes |
66 | SEND_AWSNS | Set `SEND_AWSNS` to YES | YES | yes |
67 | [AWSSNS_MESSAGE_FORMAT](#option-awssns-message-format) | Set `AWSSNS_MESSAGE_FORMAT` to the string that you want the alert to be sent into. | ${status} on ${host} at ${date}: ${chart} ${value_string} | yes |
68 | [DEFAULT_RECIPIENT_AWSSNS](#option-default-recipient-awssns) | Set `DEFAULT_RECIPIENT_AWSSNS` to the Topic ARN you noted down upon creating the Topic. | | yes |
69
70 <a id="option-awssns-message-format"></a>
71 ##### AWSSNS_MESSAGE_FORMAT
72
73 For the complete list of supported notification variables, see the [Alert Notification Variables](../../REFERENCE.md#alert-notification-variables) section in the Health Reference.
74
75
76 <a id="option-default-recipient-awssns"></a>
77 ##### DEFAULT_RECIPIENT_AWSSNS
78
79 All roles will default to this variable if left unconfigured.
80
81 You can have different recipient Topics per **role**, by editing `DEFAULT_RECIPIENT_AWSSNS` with the Topic ARN you want, in the following entries at the bottom of the same file:
82
83 ```text
84 role_recipients_awssns[sysadmin]="arn:aws:sns:us-east-2:123456789012:Systems"
85 role_recipients_awssns[domainadmin]="arn:aws:sns:us-east-2:123456789012:Domains"
86 role_recipients_awssns[dba]="arn:aws:sns:us-east-2:123456789012:Databases"
87 role_recipients_awssns[webmaster]="arn:aws:sns:us-east-2:123456789012:Development"
88 role_recipients_awssns[proxyadmin]="arn:aws:sns:us-east-2:123456789012:Proxy"
89 role_recipients_awssns[sitemgr]="arn:aws:sns:us-east-2:123456789012:Sites"
90 ```
91
92
93
94 </details>
95
96
97
98 #### via File
99
100 The configuration file name for this integration is `health_alarm_notify.conf`.
101
102
103 You can edit the configuration file using the [`edit-config`](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/README.md#edit-configuration-files) script from the
104 Netdata [config directory](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/README.md#locate-your-config-directory).
105
106 ```bash
107 cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
108 sudo ./edit-config health_alarm_notify.conf
109 ```
110
111 ##### Examples
112
113 ###### Basic Configuration
114
115 An example working configuration would be:
116
117 ```yaml
118 ```text
119 #------------------------------------------------------------------------------
120 # Amazon SNS notifications
121
122 SEND_AWSSNS="YES"
123 AWSSNS_MESSAGE_FORMAT="${status} on ${host} at ${date}: ${chart} ${value_string}"
124 DEFAULT_RECIPIENT_AWSSNS="arn:aws:sns:us-east-2:123456789012:MyTopic"
125 ```
126
127 ```
128
129
130 ## Troubleshooting
131
132 ### Test Notification
133
134 You can run the following command by hand, to test alerts configuration:
135
136 ```bash
137 # become user netdata
138 sudo su -s /bin/bash netdata
139
140 # enable debugging info on the console
141 export NETDATA_ALARM_NOTIFY_DEBUG=1
142
143 # send test alarms to sysadmin
144 /usr/libexec/netdata/plugins.d/alarm-notify.sh test
145
146 # send test alarms to any role
147 /usr/libexec/netdata/plugins.d/alarm-notify.sh test "ROLE"
148 ```
149
150 Note that this will test _all_ alert mechanisms for the selected role.
151
152