docs: improve config options table with grouped section headers (#20980)
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Ilya Mashchenko committed
Sep 15, 2025 at 07:24 UTC
c3d46103e5754da71ac2fe155e00892df9a350e9
3 files changed
+118
-68
integrations/schemas/shared.json
+5
-1
@@ -158,13 +158,17 @@
158
"type": "string",
159
"description": "Option name."
160
},
161
+ "group": {
162
+ "type": "string",
163
+ "description": "Optional group name. Used to organize related options together in documentation tables."
164
+ },
165
"description": {
166
"type": "string",
167
"description": "Option description. Must be short. Use 'detailed_description' for a long description."
168
},
169
"detailed_description": {
170
"type": "string",
167
- "description": "Option detailed description. Use it to describe in details complex options."
171
+ "description": "Option detailed description. Use it to describe complex options in detail."
172
},
173
"default_value": {
174
"type": [
integrations/templates/setup.md
+17
-3
@@ -21,7 +21,7 @@ You can configure the **[[ entry.meta.module_name ]]** collector in two ways:
21
22
:::important
23
24
-UI configuration requires paid Netdata Cloud plan. File-based configuration uses the same options and is useful if you prefer configuring via file or need to automate deployments.
24
+UI configuration requires paid Netdata Cloud plan.
25
26
:::
27
@@ -55,11 +55,24 @@ No action required.
55
[% if entry.setup.configuration.options.folding.enabled and not clean %]
56
{% details open=true summary="[[ entry.setup.configuration.options.folding.title ]]" %}
57
[% endif %]
58
-| Name | Description | Default | Required |
59
-|:----|:-----------|:-------|:--------:|
58
+
59
+[% set has_groups = entry.setup.configuration.options.list | selectattr("group","defined") | list | length > 0 %]
60
+
61
+[% if has_groups %]
62
+| Group | Option | Description | Default | Required |
63
+|:------|:-----|:------------|:--------|:---------:|
64
+[% set ns = namespace(last_group=None) %]
65
+[% for item in entry.setup.configuration.options.list %]
66
+| [[ ("**" ~ item.group ~ "**") if (item.group is defined and item.group != ns.last_group) else "" ]] | [[ strfy(item.name) ]] | [[ strfy(item.description) ]] | [[ strfy(item.default_value) ]] | [[ strfy(item.required) ]] |
67
+[% set ns.last_group = item.group if item.group is defined else ns.last_group %]
68
+[% endfor %]
69
+[% else %]
70
+| Option | Description | Default | Required |
71
+|:-----|:------------|:--------|:---------:|
72
[% for item in entry.setup.configuration.options.list %]
73
| [[ strfy(item.name) ]] | [[ strfy(item.description) ]] | [[ strfy(item.default_value) ]] | [[ strfy(item.required) ]] |
74
[% endfor %]
75
+[% endif %]
76
77
[% for item in entry.setup.configuration.options.list %]
78
[% if 'detailed_description' in item %]
@@ -69,6 +82,7 @@ No action required.
82
83
[% endif %]
84
[% endfor %]
85
+
86
[% if entry.setup.configuration.options.folding.enabled and not clean %]
87
{% /details %}
88
[% endif %]
src/go/plugin/go.d/collector/snmp/metadata.yaml
+96
-64
@@ -83,90 +83,34 @@ modules:
83
enabled: true
84
list:
85
- name: update_every
86
+ group: Base
87
description: Data collection frequency.
88
default_value: 10
89
required: false
90
- name: autodetection_retry
91
+ group: Base
92
description: Recheck interval in seconds. Zero means no recheck will be scheduled.
93
default_value: 0
94
required: false
95
- name: hostname
96
+ group: Base
97
description: Target host (IP or DNS name, IPv4/IPv6).
98
default_value: ""
99
required: true
97
- - name: enable_profiles
98
- description: Enable collection of metrics using SNMP profiles.
99
- default_value: "true"
100
- required: false
101
- - name: enable_profiles_table_metrics
102
- description: Enable collection of SNMP table metrics from profiles. Enabling this may **increase collection time and memory usage** for devices with many network interfaces.
103
- default_value: "true"
104
- required: false
105
- - name: disable_legacy_collection
106
- description: Disable the legacy SNMP collection method, forcing the collector to use only SNMP profiles (YAML-based configuration). When enabled, the collector will ignore any non-profile based collection logic.
107
- default_value: "false"
108
- required: false
109
- - name: create_vnode
110
- description: If set, the collector will create a Netdata Virtual Node for this SNMP device, which will appear as a separate Node in Netdata.
111
- default_value: "true"
112
- required: false
113
- - name: vnode_device_down_threshold
114
- description: Number of consecutive failed data collections before marking the device as down.
115
- default_value: 3
116
- required: false
117
- - name: vnode.guid
118
- description: A unique identifier for the Virtual Node. If not set, a GUID will be automatically generated from the device's IP address.
119
- default_value: ""
120
- required: false
121
- - name: vnode.hostname
122
- description: The hostname that will be used for the Virtual Node. If not set, the device's hostname will be used.
123
- default_value: ""
124
- required: false
125
- - name: vnode.labels
126
- description: Additional key-value pairs to associate with the Virtual Node.
127
- default_value: ""
128
- required: false
100
+
101
- name: community
102
+ group: SNMPv1/2
103
description: SNMPv1/2 community string.
104
default_value: public
105
required: false
133
- - name: options.version
134
- description: "SNMP version. Available versions: 1, 2, 3."
135
- default_value: 2
136
- required: false
137
- - name: options.port
138
- description: Target port.
139
- default_value: 161
140
- required: false
141
- - name: options.retries
142
- description: Retries to attempt.
143
- default_value: 1
144
- required: false
145
- - name: options.timeout
146
- description: SNMP request/response timeout.
147
- default_value: 5
148
- required: false
149
- - name: options.max_repetitions
150
- description: Controls how many SNMP variables to retrieve in a single GETBULK request.
151
- default_value: 25
152
- required: false
153
- - name: options.max_request_size
154
- description: Maximum number of OIDs allowed in a single GET request.
155
- default_value: 60
156
- required: false
157
- - name: network_interface_filter.by_name
158
- description: "Filter interfaces by their names using [simple patterns](/src/libnetdata/simple_pattern/README.md#simple-patterns)."
159
- default_value: ""
160
- required: false
161
- - name: network_interface_filter.by_type
162
- description: "Filter interfaces by their types using [simple patterns](/src/libnetdata/simple_pattern/README.md#simple-patterns)."
163
- default_value: ""
164
- required: false
106
+
107
- name: user.name
108
+ group: SNMPv3
109
description: SNMPv3 user name.
110
default_value: ""
111
required: false
112
- name: user.level
113
+ group: SNMPv3
114
description: Security level of SNMPv3 messages.
115
default_value: ""
116
required: false
@@ -179,6 +123,7 @@ modules:
123
| authNoPriv | 2 | message authentication and no encryption |
124
| authPriv | 3 | message authentication and encryption |
125
- name: user.auth_proto
126
+ group: SNMPv3
127
description: Authentication protocol for SNMPv3 messages.
128
default_value: ""
129
required: false
@@ -195,10 +140,12 @@ modules:
140
| sha384 | 6 | SHA message authentication (HMAC-SHA-384) |
141
| sha512 | 7 | SHA message authentication (HMAC-SHA-512) |
142
- name: user.auth_key
143
+ group: SNMPv3
144
description: Authentication protocol pass phrase for SNMPv3 messages.
145
default_value: ""
146
required: false
147
- name: user.priv_proto
148
+ group: SNMPv3
149
description: Privacy protocol for SNMPv3 messages.
150
default_value: ""
151
required: false
@@ -215,9 +162,94 @@ modules:
162
| aes192c | 6 | 192-bit AES encryption (CFB-AES-192) with "Reeder" key localization |
163
| aes256c | 7 | 256-bit AES encryption (CFB-AES-256) with "Reeder" key localization |
164
- name: user.priv_key
165
+ group: SNMPv3
166
description: Privacy protocol pass phrase for SNMPv3 messages.
167
default_value: ""
168
required: false
169
+
170
+ - name: options.version
171
+ group: SNMP transport
172
+ description: "SNMP version. Available versions: 1, 2, 3."
173
+ default_value: 2
174
+ required: false
175
+ - name: options.port
176
+ group: SNMP transport
177
+ description: Target port.
178
+ default_value: 161
179
+ required: false
180
+ - name: options.retries
181
+ group: SNMP transport
182
+ description: Retries to attempt.
183
+ default_value: 1
184
+ required: false
185
+ - name: options.timeout
186
+ group: SNMP transport
187
+ description: SNMP request/response timeout.
188
+ default_value: 5
189
+ required: false
190
+ - name: options.max_repetitions
191
+ group: SNMP transport
192
+ description: Controls how many SNMP variables to retrieve in a single GETBULK request.
193
+ default_value: 25
194
+ required: false
195
+ - name: options.max_request_size
196
+ group: SNMP transport
197
+ description: Maximum number of OIDs allowed in a single GET request.
198
+ default_value: 60
199
+ required: false
200
+
201
+ - name: enable_profiles
202
+ group: Profiles
203
+ description: Enable collection of metrics using SNMP profiles.
204
+ default_value: "true"
205
+ required: false
206
+ - name: enable_profiles_table_metrics
207
+ group: Profiles
208
+ description: Enable collection of SNMP table metrics from profiles. Enabling this may **increase collection time and memory usage** for devices with many network interfaces.
209
+ default_value: "true"
210
+ required: false
211
+ - name: disable_legacy_collection
212
+ group: Profiles
213
+ description: Disable the legacy SNMP collection method, forcing the collector to use only SNMP profiles (YAML-based configuration). When enabled, the collector will ignore any non-profile based collection logic.
214
+ default_value: "false"
215
+ required: false
216
+
217
+ - name: create_vnode
218
+ group: Virtual node
219
+ description: If set, the collector will create a Netdata Virtual Node for this SNMP device, which will appear as a separate Node in Netdata.
220
+ default_value: "true"
221
+ required: false
222
+ - name: vnode_device_down_threshold
223
+ group: Virtual node
224
+ description: Number of consecutive failed data collections before marking the device as down.
225
+ default_value: 3
226
+ required: false
227
+ - name: vnode.guid
228
+ group: Virtual node
229
+ description: A unique identifier for the Virtual Node. If not set, a GUID will be automatically generated from the device's IP address.
230
+ default_value: ""
231
+ required: false
232
+ - name: vnode.hostname
233
+ group: Virtual node
234
+ description: The hostname that will be used for the Virtual Node. If not set, the device's hostname will be used.
235
+ default_value: ""
236
+ required: false
237
+ - name: vnode.labels
238
+ group: Virtual node
239
+ description: Additional key-value pairs to associate with the Virtual Node.
240
+ default_value: ""
241
+ required: false
242
+
243
+ - name: network_interface_filter.by_name
244
+ group: Filters
245
+ description: "Filter interfaces by their names using [simple patterns](/src/libnetdata/simple_pattern/README.md#simple-patterns)."
246
+ default_value: ""
247
+ required: false
248
+ - name: network_interface_filter.by_type
249
+ group: Filters
250
+ description: "Filter interfaces by their types using [simple patterns](/src/libnetdata/simple_pattern/README.md#simple-patterns)."
251
+ default_value: ""
252
+ required: false
253
examples:
254
folding:
255
title: Config