docs(go.d/snmp): add Debugging Gaps on Charts (#21452)
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Ilya Mashchenko committed
Dec 11, 2025 at 22:13 UTC
156a1de791f92160f9355f2d4da49dc0c456b946
2 files changed
+52
-4
integrations/templates/troubleshooting.md
+1
-1
@@ -128,6 +128,6 @@ Note that this will test _all_ alert mechanisms for the selected role.
128
[% for item in entry.troubleshooting.problems.list %]
129
### [[ item.name ]]
130
131
-[[ description ]]
131
+[[ item.description ]]
132
133
[% endfor %]
src/go/plugin/go.d/collector/snmp/metadata.yaml
+51
-3
@@ -482,9 +482,6 @@ modules:
482
auth_key: auth_protocol_passphrase
483
priv_proto: aes256
484
priv_key: priv_protocol_passphrase
485
- troubleshooting:
486
- problems:
487
- list: []
485
alerts: []
486
metrics:
487
folding:
@@ -502,3 +499,54 @@ modules:
499
If `ping.enabled` is true, ICMP latency/packet-loss charts are also provided (or exclusively, when `ping_only: true`).
500
availability: []
501
scopes: []
502
+ troubleshooting:
503
+ problems:
504
+ list:
505
+ - name: Debugging Gaps on Charts
506
+ description: |
507
+ If your SNMP charts show gaps, it means the collector could not finish metric collection before the next scheduled run. This usually happens when SNMP tables take longer to collect than your configured `update_every`.
508
+
509
+ These gaps do *not* mean the device stopped exporting SNMP metrics — only that the collector had to skip cycles.
510
+
511
+ **Step 1: Check the Logs**
512
+
513
+ [Look for messages](#getting-logs) like:
514
+
515
+ ```text
516
+ level=warn msg="skipping data collection: previous run is still in progress for 4s (skipped 4 times in a row, interval 1s)" collector=snmp job=your_device
517
+ level=info msg="data collection resumed after 4.36s (skipped 4 times)" collector=snmp job=your_device
518
+ ```
519
+
520
+ The “resumed after” message shows how long the previous collection actually took.
521
+ For example, if a run needs ~4.4 seconds and `update_every` is 1 second, 4 cycles will be skipped.
522
+
523
+
524
+ **Step 2: Check Collection Timings**
525
+
526
+ Open **SNMP → Internal → Stats** in the dashboard.
527
+ The **SNMP profile collection timings** chart shows how long each part of the SNMP polling takes.
528
+ Table metrics are usually the slowest and often determine the total collection time.
529
+
530
+ **Step 3: Increase the data collection interval**
531
+
532
+ [Set `update_every`](#setup) to a value **higher than your slowest collection time**, with some extra buffer for network variability.
533
+
534
+ | Typical Collection Time | Recommended `update_every` |
535
+ |-------------------------|-----------------------------|
536
+ | < 2 seconds | 2 seconds |
537
+ | 2–5 seconds | 5 seconds |
538
+ | 5–10 seconds | 10 seconds |
539
+ | > 10 seconds | collection_time × 2 |
540
+
541
+ :::info
542
+
543
+ - **Rule of thumb:** `update_every` should be at least 2× your slowest table collection time.
544
+ - The default `update_every: 10` works well in most environments.
545
+ - Only reduce it if your device consistently responds fast enough.
546
+
547
+ :::
548
+
549
+ **Quick Checklist**
550
+ 1. Do logs show “skipping data collection”?
551
+ 2. Does *Internal → Stats* show collection time > `update_every`?
552
+ 3. Increase `update_every` until skips disappear.