Clarify editing health config files in health quickstart (#7883)
* Add fixes to health quickstart * Add notice about EDITOR and fix link
Joel Hans committed
Jan 30, 2020 at 05:46 UTC
3ddadb97035161f37efc59372306cb46de3c0c3c
2 files changed
+37
-30
health/QUICKSTART.md
+35
-28
@@ -8,18 +8,43 @@ To learn about more advanced health configurations, visit the [health reference
8
9
## What's in this getting started guide
10
11
-- [Locate health configuration files](#locate-health-configuration-files)
12
-- [Edit existing health configuration files](#edit-existing-health-configuration-files)
11
+- [Edit health configuration files](#edit-health-configuration-files)
12
+- [Reference Netdata's stock health configuration files](#reference-netdatas-stock-health-configuration-files)
13
- [Write a new health entity](#write-a-new-health-entity)
14
- [Reload health configuration](#reload-health-configuration)
15
16
-## Locate health configuration files
16
+## Edit health configuration files
17
18
-By default, Netdata will put health configuration files in `/usr/lib/netdata/conf.d/health.d`.
18
+You should use `edit-config` to edit Netdata's health configuration files. `edit-config` will open your system's default
19
+terminal editor for you to make your changes. Once you've saved and closed the editor, `edit-config` will copy your
20
+edited file into `/etc/netdata/health.d/`, which will override the stock file in `/usr/lib/netdata/conf.d/health.d/` and
21
+ensure your customizations are persistent between updates.
22
20
-However, you can double-check the location of these files by navigating to `http://HOST:19999/netdata.conf` in your
21
-browser and looking for the `stock health configuration directory` option. The value here will show the correct path for
22
-your installation.
23
+For example, to edit the `cpu.conf` health configuration file, you would run:
24
+
25
+```bash
26
+cd /etc/netdata/ # Replace with your Netdata configuration directory, if not /etc/netdata/
27
+./edit-config health.d/cpu.conf
28
+```
29
+
30
+> You may need to use `sudo` or another method of elevating your privileges: `sudo ./edit-config health.d/cpu.conf`.
31
+>
32
+> You can also use the `$EDITOR` environment variable to use your preferred terminal editor with `edit-config`. See
33
+> [this page](../docs/step-by-step/step-04.md#use-edit-config-to-open-netdataconf) for details.
34
+
35
+Each health configuration file contains one or more health entities, which always begin with an `alarm:` or `template:`
36
+line. You can edit these entities based on your needs. To make any changes live, be sure to [reload your health
37
+configuration](#reload-health-configuration).
38
+
39
+## Reference Netdata's stock health configuration files
40
+
41
+While you should always [use `edit-config`](#edit-health-configuration-files), you might also want to view the stock
42
+health configuration files Netdata ships with. Stock files can be useful as reference material, or to determine which
43
+file you should edit with `edit-config`.
44
+
45
+By default, Netdata will put health configuration files in `/usr/lib/netdata/conf.d/health.d`. However, you can
46
+double-check the location of these files by navigating to `http://HOST:19999/netdata.conf` in your browser and looking
47
+for the `stock health configuration directory` option. The value here will show the correct path for your installation.
48
49
```conf
50
[health]
@@ -27,7 +52,7 @@ your installation.
52
# stock health configuration directory = /usr/lib/netdata/conf.d/health.d
53
```
54
30
-Navigate to the health configuration directory to see all the available files.
55
+Navigate to the health configuration directory to see all the available files and open them for reading.
56
57
```bash
58
cd /usr/lib/netdata/conf.d/health.d/
@@ -38,26 +63,8 @@ apache.conf fronius.conf mysql.conf swap.conf
63
...
64
```
65
41
-## Edit existing health configuration files
42
-
43
-You should use `edit-config` to edit Netdata's health configuration files.
44
-
45
-For example, to edit the `cpu.conf` health configuration file, you would run:
46
-
47
-```bash
48
-cd /etc/netdata/ # Replace with your Netdata configuration directory, if not /etc/netdata/
49
-./edit-config health.d/cpu.conf
50
-```
51
-
52
-> You may need to use `sudo` or another method of elevating your privileges.
53
-
54
-`edit-config` will open a text editor for you to make your changes. Once you've saved and closed the editor,
55
-`edit-config` will copy your edited file into `/etc/netdata/health.d/`, and it will now override the default in
56
-`/usr/lib/netdata/conf.d/health.d/`.
57
-
58
-Each health configuration file contains one or more health entities, which always begin with an `alarm:` or `template:`
59
-line. You can edit these entities based on your needs. To make any changes live, be sure to [reload your health
60
-configuration](#reload-health-configuration).
66
+> ⚠️ If you edit configuration files in your stock health configuration directory, Netdata will overwrite them during
67
+> any updates. Please use `edit-config` as described in the [section above](#edit-health-configuration-files).
68
69
## Write a new health entity
70
health/tutorials/stop-notifications-alarms.md
+2
-2
@@ -28,8 +28,8 @@ In the `source` row, you see that this chart is getting its configuration from
28
`4@/usr/lib/netdata/conf.d/health.d/cpu.conf`. The relevant part of begins at `health.d`: `health.d/cpu.conf`. That's
29
the file you need to edit if you want to silence this alarm.
30
31
-For more information about locating health configuration files on your system, see the [health
32
-quickstart](../QUICKSTART.md#locate-health-configuration-files).
31
+For more information about editing or referencing health configuration files on your system, see the [health
32
+quickstart](../QUICKSTART.md#edit-health-configuration-files).
33
34
## Edit the file to enable silencing
35