diff options
Diffstat (limited to 'web/api/health/README.md')
| -rw-r--r-- | web/api/health/README.md | 50 |
1 files changed, 28 insertions, 22 deletions
diff --git a/web/api/health/README.md b/web/api/health/README.md index a86dbfdd8..b6e8b5c23 100644 --- a/web/api/health/README.md +++ b/web/api/health/README.md @@ -1,20 +1,26 @@ +<!-- +title: "Health API Calls" +date: 2020-04-27 +custom_edit_url: https://github.com/netdata/netdata/edit/master/web/api/health/README.md +--> + # Health API Calls ## Health Read API ### Enabled Alarms -NetData enables alarms on demand, i.e. when the chart they should be linked to starts collecting data. So, although many more alarms are configured, only the useful ones are enabled. - -To get the list of all enabled alarms: +Netdata enables alarms on demand, i.e. when the chart they should be linked to starts collecting data. So, although many +more alarms are configured, only the useful ones are enabled. -`http://your.netdata.ip:19999/api/v1/alarms?all` +To get the list of all enabled alarms, open your browser and navigate to `http://NODE:19999/api/v1/alarms?all`, +replacing `NODE` with the IP address or hostname for your Agent dashboard. ### Raised Alarms This API call will return the alarms currently in WARNING or CRITICAL state. -`http://your.netdata.ip:19999/api/v1/alarms` +`http://NODE:19999/api/v1/alarms` ### Event Log @@ -28,11 +34,11 @@ The size of the alarm log is configured in `netdata.conf`. There are 2 settings: The API call retrieves all entries of the alarm log: -`http://your.netdata.ip:19999/api/v1/alarm_log` +`http://NODE:19999/api/v1/alarm_log` ### Alarm Log Incremental Updates -`http://your.netdata.ip:19999/api/v1/alarm_log?after=UNIQUEID` +`http://NODE:19999/api/v1/alarm_log?after=UNIQUEID` The above returns all the events in the alarm log that occurred after UNIQUEID (you poll it once without `after=`, remember the last UNIQUEID of the returned set, which you give back to get incrementally the next events). @@ -40,7 +46,7 @@ The above returns all the events in the alarm log that occurred after UNIQUEID ( The following will return an SVG badge of the alarm named `NAME`, attached to the chart named `CHART`. -`http://your.netdata.ip:19999/api/v1/badge.svg?alarm=NAME&chart=CHART` +`http://NODE:19999/api/v1/badge.svg?alarm=NAME&chart=CHART` ## Health Management API @@ -53,7 +59,7 @@ Specifically, the API allows you to: - Silence alarm notifications. Alarm conditions will be evaluated, the alarms will appear in the log and the Netdata UI will show the alarms as active, but no notifications will be sent. - Disable or Silence specific alarms that match selectors on alarm/template name, chart, context, host and family. -The API is available by default, but it is protected by an `api authorization token` that is stored in the file you will see in the following entry of `http://localhost:19999/netdata.conf`: +The API is available by default, but it is protected by an `api authorization token` that is stored in the file you will see in the following entry of `http://NODE:19999/netdata.conf`: ``` [registry] @@ -63,27 +69,27 @@ The API is available by default, but it is protected by an `api authorization to You can access the API via GET requests, by adding the bearer token to an `Authorization` http header, like this: ``` -curl "http://myserver/api/v1/manage/health?cmd=RESET" -H "X-Auth-Token: Mytoken" +curl "http://NODE:19999/api/v1/manage/health?cmd=RESET" -H "X-Auth-Token: Mytoken" ``` -By default access to the health management API is only allowed from `localhost`. Accessing the API from anything else will return a 403 error with the message `You are not allowed to access this resource.`. You can change permissions by editing the `allow management from` variable in `netdata.conf` within the [web] section. See [web server access lists](../../server/#access-lists) for more information. +By default access to the health management API is only allowed from `localhost`. Accessing the API from anything else will return a 403 error with the message `You are not allowed to access this resource.`. You can change permissions by editing the `allow management from` variable in `netdata.conf` within the [web] section. See [web server access lists](/web/server/README.md#access-lists) for more information. The command `RESET` just returns Netdata to the default operation, with all health checks and notifications enabled. -If you've configured and entered your token correclty, you should see the plain text response `All health checks and notifications are enabled`. +If you've configured and entered your token correctly, you should see the plain text response `All health checks and notifications are enabled`. ### Disable or silence all alarms If all you need is temporarily disable all health checks, then you issue the following before your maintenance period starts: ```sh -curl "http://myserver/api/v1/manage/health?cmd=DISABLE ALL" -H "X-Auth-Token: Mytoken" +curl "http://NODE:19999/api/v1/manage/health?cmd=DISABLE ALL" -H "X-Auth-Token: Mytoken" ``` The effect of disabling health checks is that the alarm criteria are not evaluated at all and nothing is written in the alarm log. If you want the health checks to be running but to not receive any notifications during your maintenance period, you can instead use this: ```sh -curl "http://myserver/api/v1/manage/health?cmd=SILENCE ALL" -H "X-Auth-Token: Mytoken" +curl "http://NODE:19999/api/v1/manage/health?cmd=SILENCE ALL" -H "X-Auth-Token: Mytoken" ``` Alarms may then still be raised and logged in Netdata, so you'll be able to see them via the UI. @@ -91,7 +97,7 @@ Alarms may then still be raised and logged in Netdata, so you'll be able to see Regardless of the option you choose, at the end of your maintenance period you revert to the normal state via the RESET command. ```sh - curl "http://myserver/api/v1/manage/health?cmd=RESET" -H "X-Auth-Token: Mytoken" + curl "http://NODE:19999/api/v1/manage/health?cmd=RESET" -H "X-Auth-Token: Mytoken" ``` ### Disable or silence specific alarms @@ -115,12 +121,12 @@ To clear all selectors and reset the mode to default, use the `RESET` command. The following example silences notifications for all the alarms with context=load: ``` -curl "http://myserver/api/v1/manage/health?cmd=SILENCE&context=load" -H "X-Auth-Token: Mytoken" +curl "http://NODE:19999/api/v1/manage/health?cmd=SILENCE&context=load" -H "X-Auth-Token: Mytoken" ``` #### Selection criteria -The `selection criteria` are key/value pairs, in the format `key : value`, where value is a Netdata [simple pattern](../../../libnetdata/simple_pattern/). This means that you can create very powerful selectors (you will rarely need more than one or two). +The `selection criteria` are key/value pairs, in the format `key : value`, where value is a Netdata [simple pattern](/libnetdata/simple_pattern/README.md). This means that you can create very powerful selectors (you will rarely need more than one or two). The accepted keys for the `selection criteria` are the following: @@ -135,19 +141,19 @@ You can add any of the selection criteria you need on the request, to ensure tha Example 1: Disable all health checks for context = `random` ``` -http://localhost/api/v1/manage/health?cmd=DISABLE&context=random +http://NODE:19999/api/v1/manage/health?cmd=DISABLE&context=random ``` Example 2: Silence all alarms and templates with name starting with `out_of` on host `myhost` ``` -http://localhost/api/v1/manage/health?cmd=SILENCE&alarm=out_of*&hosts=myhost +http://NODE:19999/api/v1/manage/health?cmd=SILENCE&alarm=out_of*&hosts=myhost ``` Example 2.2: Add one more selector, to also silence alarms for cpu1 and cpu2 ``` -http://localhost/api/v1/manage/health?families=cpu1 cpu2 +http://NODE:19999/api/v1/manage/health?families=cpu1 cpu2 ``` ### List silencers @@ -155,7 +161,7 @@ http://localhost/api/v1/manage/health?families=cpu1 cpu2 The command `LIST` was added in Netdata v1.16.0 and returns a JSON with the current status of the silencers. ``` - curl "http://myserver/api/v1/manage/health?cmd=LIST" -H "X-Auth-Token: Mytoken" + curl "http://NODE:19999/api/v1/manage/health?cmd=LIST" -H "X-Auth-Token: Mytoken" ``` As an example, the following response shows that we have two silencers configured, one for an alarm called `samplealarm` and one for alarms with context `random` on host `myhost` @@ -214,6 +220,6 @@ The file's location is configurable in `netdata.conf`. The default is shown belo ### Further reading -The test script under [tests/health_mgmtapi](../../../tests/health_mgmtapi) contains a series of tests that you can either run or read through to understand the various calls and responses better. +The test script under [tests/health_mgmtapi](/tests/health_mgmtapi/README.md) contains a series of tests that you can either run or read through to understand the various calls and responses better. [](<>) |