ansible-inventories/arocom#2969 Documentation for netdata enhancements

docs/ansible/roles/netdata/index.md

@@ -8,3 +8,147 @@ tags:
 # Ansible Role NetData
 
 Needs to be done still.
+
+## Configuration options in inventory
+
+### Alarm channel configuration
+
+A number of variables is available for your inventory to configure alarm
+channels:
+
+```yaml
+netdata_email_enabled: 'YES'
+
+netdata_alerta_enabled: 'YES'
+netdata_alerta_webhook: 'https://alerta.lakedrops.com/api'
+netdata_alerta_apikey: <API KEY>
+netdata_alerta_environment: <ENVIRONMENT>
+
+netdata_slack_enabled: 'YES'
+netdata_slack_webhook: 'https://hooks.slack.com/services/<TOKEN1>/<TOKEN2>/<TOKEN3>'
+netdata_slack_channel: incident
+
+netdata_pushover_enabled: 'YES'
+netdata_pushover_app_token: <APP TOKEN>
+netdata_pushover_user_token: <USER TOKEN>
+
+netdata_pushbullet_enabled: 'YES'
+netdata_pushbullet_token: <TOKEN>
+netdata_pushbullet_recipient: <RECIPIENT>
+
+netdata_twilio_enabled: 'YES'
+netdata_twilio_sid: <SID>
+netdata_twilio_token: <TOKEN>
+netdata_twilio_number: <NUMBER>
+netdata_twilio_recipient: <RECIPIENT>
+
+netdata_messagebird_enabled: 'YES'
+netdata_messagebird_key: <KEY>
+netdata_messagebird_number: <NUMBER>
+netdata_messagebird_recipient: <RECIPIENT>
+
+netdata_telegram_enabled: 'YES'
+netdata_telegram_recipient: <RECIPIENT>
+
+netdata_discord_enabled: 'YES'
+netdata_discord_webhook: <WEBHOOK>
+netdata_discord_recipient: <RECIPIENT>
+
+netdata_hipchat_enabled: 'YES'
+netdata_hipchat_token: <TOKEN>
+netdata_hipchat_recipient: <RECIPIENT>
+
+netdata_kafka_enabled: 'YES'
+netdata_kafka_url: <URL>
+netdata_kafka_sender: <SENDER>
+
+netdata_pagerduty_enabled: 'YES'
+netdata_pagerduty_recipient: <RECIPIENT>
+
+netdata_matrix_enabled: 'YES'
+netdata_matrix_url: <URL>
+netdata_matrix_token: <TOKEN>
+netdata_matrix_room: <ROOM>
+```
+
+### HTTP Checks
+
+Most web services, that get rolled out by Ansible will be added to HTTP checks
+automatically, e.g. Drupal or Nextcloud sites.
+
+You can define additional HTTP checks by defining a dictionary called
+`netdata_httpcheck` on one or more hosts in your inventory.
+
+```yaml
+netdata_httpcheck:
+  - name: Example 1
+    url: 'http://www.example.com'
+    method: GET
+    regex: "<title>Example</title>"
+  - name: Example 2
+    url: 'https://kibana.example.com/api/status'
+    check_response:
+      json:
+        - condition:
+            equals:
+              status.overall.state: green
+  - name: Example 3
+    url: 'https://alerta.example.com/api/environments'
+    header:
+      Authorization: Key <SOME KEY DATA>
+```
+
+There are a lot more configuration options for each HTTP check. Please refer
+to the [Netdata documentation](https://learn.netdata.cloud/docs/agent/collectors/python.d.plugin/httpcheck) for further details.
+
+### Custom alarms
+
+Netdata comes with hundreds of pre-configured alarms and templates. In addition
+to that you can define your own by defining a dictionary called
+`netdata_custom_notifications` on one or more hosts in your inventory.
+
+```yaml
+  - alarm: my_web_service_unreachable
+    'on': httpcheck_Example_1.status
+    calc: '($no_web_service_connections >= $web_service_timeouts) ? ($no_web_service_connections) : ($web_service_timeouts)'
+    units: '%'
+    every: 10s
+    warn: ($no_web_service_connections >= 10 OR $web_service_timeouts >= 10) AND ($no_web_service_connections < 40 OR $web_service_timeouts < 40)
+    crit: $no_web_service_connections >= 40 OR $web_service_timeouts >= 40
+    delay: down 5m multiplier 1.5 max 1h
+    info: average of failed requests either due to timeouts or no connection during the last 5 minutes
+    to: customer
+```
+
+This example is a copy of the stock alarm `web_service_unreachable` which only
+works on the HTTP check `Example 1` and send the alerts to the role
+`customer`.
+
+More details can be found in the [Netdata documentation](https://learn.netdata.cloud/docs/agent/health/reference).
+
+### Custom role recipients
+
+Netdata comes with a number of predefined roles that can receive alarm
+notifications relevant to them:
+
+- sysadmin
+- domainadmin
+- dba
+- webmaster
+- proxyadmin
+- sitemgr
+
+When defining custom alarms you can use different strings which implicitly
+defines new roles. To define individual role recipients, define the dictionary
+`netdata_role_recipients`:
+
+```yaml
+netdata_role_recipients:
+  customer:
+    slack: incidents
+    email: team@example.com redteam@example.com|critical
+```
+
+In this example, alarms for the role `customer` will be sent to Slack into the
+`#incident` channel and by email to the 2 given email addresses, where the
+second one only receives critical alarms.