docs: note that health foreach works only with template (#15478)
* docs: note that health foreach works only with template
Ilya Mashchenko committed
Jul 21, 2023 at 12:56 UTC
11464f4636e916413e0102300cbed2cd17f627bf
1 file changed
+33
-31
health/REFERENCE.md
+33
-31
@@ -485,7 +485,7 @@ The full [database query API](https://github.com/netdata/netdata/blob/master/web
485
`,` or `|` instead of spaces)_ and the `match-ids` and `match-names` options affect the searches
486
for dimensions.
487
488
-- `foreach DIMENSIONS` is optional, will always be the last parameter, and uses the same `,`/`|`
488
+- `foreach DIMENSIONS` is optional and works only with [templates](#alarm-line-alarm-or-template), will always be the last parameter, and uses the same `,`/`|`
489
rules as the `of` parameter. Each dimension you specify in `foreach` will use the same rule
490
to trigger an alarm. If you set both `of` and `foreach`, Netdata will ignore the `of` parameter
491
and replace it with one of the dimensions you gave to `foreach`. This option allows you to
@@ -1068,18 +1068,18 @@ alarm to it.
1068
Check if user or system dimension is using more than 50% of cpu:
1069
1070
```yaml
1071
- alarm: dim_template
1072
- on: system.cpu
1073
- os: linux
1074
-lookup: average -3s percentage foreach system,user
1075
- units: %
1076
- every: 10s
1077
- warn: $this > 50
1078
- crit: $this > 80
1071
+template: cpu_template
1072
+ on: system.cpu
1073
+ os: linux
1074
+ lookup: average -1m foreach system,user
1075
+ units: %
1076
+ every: 10s
1077
+ warn: $this > 50
1078
+ crit: $this > 80
1079
```
1080
1081
-The `lookup` line will calculate the average CPU usage from system and user in the last 3 seconds. Because we have
1082
-the foreach in the `lookup` line, Netdata will create two independent alarms called `dim_template_system`
1081
+The `lookup` line will calculate the average CPU usage from system and user over the last minute. Because we have
1082
+the foreach in the `lookup` line, Netdata will create two independent alarms called `cpu_template_system`
1083
and `dim_template_user` that will have all the other parameters shared among them.
1084
1085
### Example 6 - CPU usage
@@ -1087,17 +1087,17 @@ and `dim_template_user` that will have all the other parameters shared among the
1087
Check if all dimensions are using more than 50% of cpu:
1088
1089
```yaml
1090
- alarm: dim_template
1091
- on: system.cpu
1092
- os: linux
1093
-lookup: average -3s percentage foreach *
1094
- units: %
1095
- every: 10s
1096
- warn: $this > 50
1097
- crit: $this > 80
1090
+template: cpu_template
1091
+ on: system.cpu
1092
+ os: linux
1093
+ lookup: average -1m foreach *
1094
+ units: %
1095
+ every: 10s
1096
+ warn: $this > 50
1097
+ crit: $this > 80
1098
```
1099
1100
-The `lookup` line will calculate the average of CPU usage from system and user in the last 3 seconds. In this case
1100
+The `lookup` line will calculate the average of CPU usage from system and user over the last minute. In this case
1101
Netdata will create alarms for all dimensions of the chart.
1102
1103
### Example 7 - Z-Score based alarm
@@ -1199,6 +1199,8 @@ Dimension templates can condense many individual entities into one—no more cop
1199
1200
### The fundamentals of `foreach`
1201
1202
+> **Note**: works only with [templates](#alarm-line-alarm-or-template).
1203
+
1204
Our dimension templates update creates a new `foreach` parameter to the
1205
existing [`lookup` line](#alarm-line-lookup). This
1206
is where the magic happens.
@@ -1224,38 +1226,38 @@ Before dimension templates, you would need the following three entities:
1226
```yaml
1227
alarm: cpu_system
1228
on: system.cpu
1227
-lookup: average -10m percentage of system
1229
+lookup: average -10m of system
1230
every: 1m
1231
warn: $this > 50
1232
crit: $this > 80
1233
1234
alarm: cpu_user
1235
on: system.cpu
1234
-lookup: average -10m percentage of user
1236
+lookup: average -10m of user
1237
every: 1m
1238
warn: $this > 50
1239
crit: $this > 80
1240
1241
alarm: cpu_nice
1242
on: system.cpu
1241
-lookup: average -10m percentage of nice
1243
+lookup: average -10m of nice
1244
every: 1m
1245
warn: $this > 50
1246
crit: $this > 80
1247
```
1248
1247
-With dimension templates, you can condense these into a single alarm. Take note of the `alarm` and `lookup` lines.
1249
+With dimension templates, you can condense these into a single template. Take note of the `alarm` and `lookup` lines.
1250
1251
```yaml
1250
- alarm: cpu_template
1251
- on: system.cpu
1252
-lookup: average -10m percentage foreach system,user,nice
1253
- every: 1m
1254
- warn: $this > 50
1255
- crit: $this > 80
1252
+template: cpu_template
1253
+ on: system.cpu
1254
+ lookup: average -10m foreach system,user,nice
1255
+ every: 1m
1256
+ warn: $this > 50
1257
+ crit: $this > 80
1258
```
1259
1258
-The `alarm` line specifies the naming scheme Netdata will use. You can use whatever naming scheme you'd like, with `.`
1260
+The `template` line specifies the naming scheme Netdata will use. You can use whatever naming scheme you'd like, with `.`
1261
and `_` being the only allowed symbols.
1262
1263
The `lookup` line has changed from `of` to `foreach`, and we're now passing three dimensions.