Make the document more generic (#14932)
Chris Akritidis committed
Apr 19, 2023 at 07:54 UTC
46928d371a290dbed4b1a1848ced4082660b2ce7
1 file changed
+97
-29
docs/guides/using-host-labels.md
+97
-29
@@ -1,20 +1,81 @@
1
-# Using host labels to organize your metrics
1
+# Organize systems, metrics, and alerts
2
3
When you use Netdata to monitor and troubleshoot an entire infrastructure, you need sophisticated ways of keeping everything organized.
4
+Netdata allows to organize your observability infrastructure with spaces, war rooms, virtual nodes, host labels, and metric labels.
5
5
-Some of the scenarios that host labels can be extremely useful are:
6
+## Spaces and war rooms
7
+
8
+[Spaces](https://github.com/netdata/netdata/blob/master/docs/cloud/spaces.md) are used for organization-level or infrastructure-level
9
+grouping of nodes and people. A node can only appear in a single space, while people can have access to multiple spaces.
10
+
11
+The [war rooms](https://github.com/netdata/netdata/edit/master/docs/cloud/war-rooms.md) in a space bring together nodes and people in
12
+collaboration areas. War rooms can also be used for fine-tuned
13
+[role based access control](https://github.com/netdata/netdata/blob/master/docs/cloud/manage/role-based-access.md).
14
+
15
+## Virtual nodes
16
+
17
+Netdata’s virtual nodes functionality allows you to define nodes in configuration files and have them be treated as regular nodes
18
+in all of the UI, dashboards, tabs, filters etc. For example, you can create a virtual node each for all your Windows machines
19
+and monitor them as discrete entities. Virtual nodes can help you simplify your infrastructure monitoring and focus on the
20
+individual node that matters.
21
+
22
+To define your windows server as a virtual node you need to:
23
+
24
+ * Define virtual nodes in `/etc/netdata/vnodes/vnodes.conf`
25
+
26
+ ```yaml
27
+ - hostname: win_server1
28
+ guid: <value>
29
+ ```
30
+ Just remember to use a valid guid (On Linux you can use `uuidgen` command to generate one, on Windows just use the `[guid]::NewGuid()` command in PowerShell)
31
+
32
+ * Add the vnode config to the windows monitoring job we created earlier, see higlighted line below:
33
+ ```yaml
34
+ jobs:
35
+ - name: win_server1
36
+ vnode: win_server1
37
+ url: http://203.0.113.10:9182/metrics
38
+ ```
39
+
40
+## Host labels
41
+
42
+Host labels can be extremely useful when:
43
44
- You need alarms that adapt to the system's purpose
45
- You need properly-labeled metrics archiving so you can sort, correlate, and mash-up your data to your heart's content.
46
- You need to keep tabs on ephemeral Docker containers in a Kubernetes cluster.
47
11
-You need **host labels**: a powerful new way of organizing your Netdata-monitored systems. We introduced host labels in
12
-[v1.20 of Netdata](https://blog.netdata.cloud/posts/release-1.20/), and they come pre-configured out of the box.
13
-
48
Let's take a peek into how to create host labels and apply them across a few of Netdata's features to give you more
49
organization power over your infrastructure.
50
17
-## Create unique host labels
51
+### Default labels
52
+
53
+When Netdata starts, it captures relevant information about the system and converts them into automatically generated
54
+host labels. You can use these to logically organize your systems via health entities, exporting metrics,
55
+parent-child status, and more.
56
+
57
+They capture the following:
58
+
59
+- Kernel version
60
+- Operating system name and version
61
+- CPU architecture, system cores, CPU frequency, RAM, and disk space
62
+- Whether Netdata is running inside of a container, and if so, the OS and hardware details about the container's host
63
+- Whether Netdata is running inside K8s node
64
+- What virtualization layer the system runs on top of, if any
65
+- Whether the system is a streaming parent or child
66
+
67
+If you want to organize your systems without manually creating host labels, try the automatic labels in some of the
68
+features below. You can see them under `http://HOST-IP:19999/api/v1/info`, beginning with an underscore `_`.
69
+```json
70
+{
71
+ ...
72
+ "host_labels": {
73
+ "_is_k8s_node": "false",
74
+ "_is_parent": "false",
75
+ ...
76
+```
77
+
78
+### Custom labels
79
80
Host labels are defined in `netdata.conf`. To create host labels, open that file using `edit-config`.
81
@@ -65,28 +126,8 @@ read the status of your agent. For example, from a VPS system running Debian 10:
126
}
127
```
128
68
-You may have noticed a handful of labels that begin with an underscore (`_`). These are automatic labels.
69
-
70
-### Automatic labels
71
-
72
-When Netdata starts, it captures relevant information about the system and converts them into automatically-generated
73
-host labels. You can use these to logically organize your systems via health entities, exporting metrics,
74
-parent-child status, and more.
129
76
-They capture the following:
77
-
78
-- Kernel version
79
-- Operating system name and version
80
-- CPU architecture, system cores, CPU frequency, RAM, and disk space
81
-- Whether Netdata is running inside of a container, and if so, the OS and hardware details about the container's host
82
-- Whether Netdata is running inside K8s node
83
-- What virtualization layer the system runs on top of, if any
84
-- Whether the system is a streaming parent or child
85
-
86
-If you want to organize your systems without manually creating host labels, try the automatic labels in some of the
87
-features below.
88
-
89
-## Host labels in streaming
130
+### Host labels in streaming
131
132
You may have noticed the `_is_parent` and `_is_child` automatic labels from above. Host labels are also now
133
streamed from a child to its parent node, which concentrates an entire infrastructure's OS, hardware, container,
@@ -105,7 +146,7 @@ child system. It's a vastly simplified way of accessing critical information abo
146
You can also use `_is_parent`, `_is_child`, and any other host labels in both health entities and metrics
147
exporting. Speaking of which...
148
108
-## Host labels in health entities
149
+### Host labels in alerts
150
151
You can use host labels to logically organize your systems by their type, purpose, or location, and then apply specific
152
alarms to them.
@@ -153,7 +194,7 @@ Or when ephemeral Docker nodes are involved:
194
Of course, there are many more possibilities for intuitively organizing your systems with host labels. See the [health
195
documentation](https://github.com/netdata/netdata/blob/master/health/REFERENCE.md#alarm-line-host-labels) for more details, and then get creative!
196
156
-## Host labels in metrics exporting
197
+### Host labels in metrics exporting
198
199
If you have enabled any metrics exporting via our experimental [exporters](https://github.com/netdata/netdata/blob/master/exporting/README.md), any new host
200
labels you created manually are sent to the destination database alongside metrics. You can change this behavior by
@@ -182,4 +223,31 @@ send automatic labels = yes
223
By applying labels to exported metrics, you can more easily parse historical metrics with the labels applied. To learn
224
more about exporting, read the [documentation](https://github.com/netdata/netdata/blob/master/exporting/README.md).
225
226
+## Metric labels
227
+
228
+The Netdata aggregate charts allow you to filter and group metrics based on label name-value pairs.
229
+
230
+All go.d plugin collectors support the specification of labels at the "collection job" level. Some collectors come with out of the box
231
+labels (e.g. generic Prometheus collector, Kubernetes, Docker and more). But you can also add your own custom labels, by configuring
232
+the data collection jobs.
233
+
234
+For example, suppose we have a single Netdata agent, collecting data from two remote Apache web servers, located in different data centers.
235
+The web servers are load balanced and provide access to the service "Payments".
236
+
237
+You can define the following in `go.d.conf`, to be able to group the web requests by service or location:
238
+
239
+```
240
+jobs:
241
+ - name: mywebserver1
242
+ url: http://host1/server-status?auto
243
+ labels:
244
+ service: "Payments"
245
+ location: "Atlanta"
246
+ - name: mywebserver2
247
+ url: http://host2/server-status?auto
248
+ labels:
249
+ service: "Payments"
250
+ location: "New York"
251
+```
252
253
+Of course you may define as many custom label/value pairs as you like, in as many data collection jobs you need.