Query SNMP traps
This skill teaches operators and AI assistants how to query SNMP trap
journal entries written by the snmp_traps go.d collector.
SNMP trap entries are exposed through the snmp:traps Function.
Direct-journal jobs appear as __logs_sources options, normally named
after the trap listener job. OTLP-only jobs (journal.enabled: false)
do not create local journal files, so they do not appear as log
sources. This skill reuses the token-safe wrappers from
query-netdata-agents and the
Log Function request shape from
query-netdata-cloud/query-logs.md.
Guides
Mandatory Requirements
- If you analyze, you author a how-to. When asked a concrete
SNMP trap query question that is not already covered under
how-tos/, author a new how-to and add it to
how-tos/INDEX.md before completing the
task.
- Use token-safe wrappers. Source
docs/netdata-ai/skills/query-netdata-agents/scripts/_lib.sh,
call agents_load_env, then use agents_call_function,
agents_query_cloud, or agents_query_agent. Do not paste raw
Cloud tokens, agent bearers, or token-bearing curl commands.
- Use structured selections first. The embedded Function is
scoped to SNMP trap journal files. Use
selections.__logs_sources
when the query should target one trap listener job, and usually
narrow further with selections.TRAP_REPORT_TYPE=["trap"],
["deduplication_summary"], or ["decode_error"]. Use full-text
query only as a residual search over that narrowed result.
- Treat trap content as sensitive. Do not paste raw trap rows,
SNMP communities, USM secrets, MAC addresses, usernames, public
device IPs, customer hostnames, or full
TRAP_JSON payloads into
durable artifacts. Return summarized fields unless the user
explicitly needs raw output locally.
- Remember the Function is node-scoped. Cloud-proxied
snmp:traps calls target one node. For a room or fleet query,
list nodes first and loop over each node's Function, then aggregate
client-side. Use __logs_sources to narrow to a specific listener
job when needed.
Trap Field Reference
The collector writes structured fields that are useful for queries:
| Field |
Use |
MESSAGE |
Rendered human-readable trap description |
ND_LOG_SOURCE=snmp-trap |
Fast discriminator for trap entries |
TRAP_REPORT_TYPE |
trap, deduplication_summary, or decode_error |
TRAP_JOB |
Trap listener job name |
TRAP_OID |
Numeric trap OID |
TRAP_NAME |
MIB-qualified trap name |
TRAP_PDU_TYPE |
trap (unacknowledged) or inform |
TRAP_VERSION |
SNMP version: v1, v2c, or v3 |
TRAP_CATEGORY |
One of the bounded trap categories |
TRAP_SEVERITY |
One of emerg, alert, crit, err, warning, notice, info, debug |
TRAP_SOURCE_IP |
Identified trap source IP |
TRAP_SOURCE_UDP_PEER |
UDP peer address |
TRAP_SOURCE_UDP_PORT |
UDP peer source port for decode-error rows |
_HOSTNAME |
Source device hostname when resolved by collector identity |
TRAP_REVERSE_DNS |
Optional PTR annotation for the source IP; never authoritative identity |
ND_NIDL_NODE |
Netdata vnode identity when known |
TRAP_DEVICE_VENDOR |
Vendor slug when known |
TRAP_INTERFACE |
Topology interface when enrichment is available |
TRAP_NEIGHBORS |
Topology neighbors when enrichment is available |
TRAP_TAG_* |
Profile/operator labels, selectable but not default facets |
TRAP_VAR_* |
Indexed decoded event varbind fields. Enum-backed varbinds use the enum label, with _RAW carrying the numeric value. Sensitive and redundant protocol-control varbinds are skipped. |
TRAP_ENRICHMENT |
JSON audit trail for source selection and enrichment decisions; search carefully, avoid faceting on it |
TRAP_JSON |
Structured varbind payload and audit copy, including netdata_packet_sequence; prefer TRAP_VAR_* for normal filtering |
TRAP_SUPPRESSED_COUNT |
Dedup summary only |
TRAP_SUPPRESSED_FINGERPRINTS |
Dedup summary only |
TRAP_REPORT_PERIOD_SEC |
Dedup summary only |
TRAP_DECODE_ERROR_KIND |
Decode-error rows only; bounded failure class |
TRAP_DECODE_ERROR |
Decode-error rows only; sanitized decoder error text |
TRAP_PACKET_SIZE |
Decode-error rows only; received datagram size |
TRAP_PACKET_SHA256 |
Decode-error rows only; packet fingerprint without raw bytes |
TRAP_LISTENER |
Decode-error rows only; listener endpoint when known |
TRAP_ENGINE_ID |
Decode-error rows only; SNMPv3 engine ID when safely extractable |
Standard Setup
Use the wrappers from query-netdata-agents:
source "$(git rev-parse --show-toplevel)/docs/netdata-ai/skills/query-netdata-agents/scripts/_lib.sh"
agents_load_env
Cloud-proxied query, preferred by default:
NODE_UUID="YOUR_NODE_UUID"
SNMP_TRAPS_FUNCTION="snmp:traps"
agents_call_function \
--via cloud \
--node "$NODE_UUID" \
--function "$SNMP_TRAPS_FUNCTION" \
--body '{"info":true}'
Direct-agent query, for local or Cloud-unavailable cases:
NODE_UUID="YOUR_NODE_UUID"
AGENT_HOST="agent.example.invalid:19999"
MACHINE_GUID="YOUR_MACHINE_GUID"
SNMP_TRAPS_FUNCTION="snmp:traps"
agents_call_function \
--via agent \
--node "$NODE_UUID" \
--host "$AGENT_HOST" \
--machine-guid "$MACHINE_GUID" \
--function "$SNMP_TRAPS_FUNCTION" \
--body '{"info":true}'
Row Decoding Helper
Log Function responses store rows as arrays. Use columns to map row
positions back to field names:
jq '.columns as $c
| .data[]? as $row
| $c
| to_entries
| sort_by(.value.index)
| map({(.key): $row[.value.index]})
| add' response.json
Source Selection
Start with {"info":true} for snmp:traps and inspect the
__logs_sources required parameter. By default, the SDK selects all
direct-journal sources. To target one listener job, add:
{
"selections": {
"__logs_sources": ["local"]
}
}
If a job is missing from __logs_sources, verify the job exists and
journal.enabled is not false. Until Netdata's Function deletion
protocol lands, a node with no direct-journal trap sources may still
show the Function but return no sources or an unavailable response.
See Also
1---
2name: query-snmp-traps
3description: Query SNMP trap logs through Netdata Cloud or directly from a Netdata Agent. Use when the user asks about SNMP traps, trap journal entries, trap severities, trap categories, trap senders, deduplication summaries, decode errors, TRAP_* fields, TRAP_VAR_* indexed varbind fields, TRAP_JSON varbind audit data, or how to inspect received traps in the Logs UI/API.
4metadata:
5 source: https://skillmd.com/skills/netdata/query-snmp-traps
6---
7
8# Query SNMP traps
9
10This skill teaches operators and AI assistants how to query SNMP trap
11journal entries written by the `snmp_traps` go.d collector.
12
13SNMP trap entries are exposed through the `snmp:traps` Function.
14Direct-journal jobs appear as `__logs_sources` options, normally named
15after the trap listener job. OTLP-only jobs (`journal.enabled: false`)
16do not create local journal files, so they do not appear as log
17sources. This skill reuses the token-safe wrappers from
18[`query-netdata-agents`](../query-netdata-agents/SKILL.md) and the
19Log Function request shape from
20[`query-netdata-cloud/query-logs.md`](../query-netdata-cloud/query-logs.md).
21
22## Guides
23
24| Task | How-to |
25|---|---|
26| Recent security traps from one device | [how-tos/recent-security-traps-from-device.md](./how-tos/recent-security-traps-from-device.md) |
27| Critical and emergency traps across a room | [how-tos/filter-by-severity-across-fleet.md](./how-tos/filter-by-severity-across-fleet.md) |
28| Top trap senders in the last hour | [how-tos/top-trap-senders-last-hour.md](./how-tos/top-trap-senders-last-hour.md) |
29| Dedup summaries during a flap storm | [how-tos/inspect-dedup-summary-entries.md](./how-tos/inspect-dedup-summary-entries.md) |
30| Filter by indexed varbind fields; inspect `TRAP_JSON` when needed | [how-tos/search-varbind-value-in-trap-json.md](./how-tos/search-varbind-value-in-trap-json.md) |
31| Convert custom MIBs into trap profiles | [how-tos/convert-custom-mibs-to-trap-profiles.md](./how-tos/convert-custom-mibs-to-trap-profiles.md) |
32| Operational how-tos catalog | [how-tos/INDEX.md](./how-tos/INDEX.md) |
33
34## Mandatory Requirements
35
361. **If you analyze, you author a how-to.** When asked a concrete
37 SNMP trap query question that is not already covered under
38 [`how-tos/`](./how-tos/), author a new how-to and add it to
39 [`how-tos/INDEX.md`](./how-tos/INDEX.md) before completing the
40 task.
412. **Use token-safe wrappers.** Source
42 `docs/netdata-ai/skills/query-netdata-agents/scripts/_lib.sh`,
43 call `agents_load_env`, then use `agents_call_function`,
44 `agents_query_cloud`, or `agents_query_agent`. Do not paste raw
45 Cloud tokens, agent bearers, or token-bearing curl commands.
463. **Use structured selections first.** The embedded Function is
47 scoped to SNMP trap journal files. Use `selections.__logs_sources`
48 when the query should target one trap listener job, and usually
49 narrow further with `selections.TRAP_REPORT_TYPE=["trap"]`,
50 `["deduplication_summary"]`, or `["decode_error"]`. Use full-text
51 `query` only as a residual search over that narrowed result.
524. **Treat trap content as sensitive.** Do not paste raw trap rows,
53 SNMP communities, USM secrets, MAC addresses, usernames, public
54 device IPs, customer hostnames, or full `TRAP_JSON` payloads into
55 durable artifacts. Return summarized fields unless the user
56 explicitly needs raw output locally.
575. **Remember the Function is node-scoped.** Cloud-proxied
58 `snmp:traps` calls target one node. For a room or fleet query,
59 list nodes first and loop over each node's Function, then aggregate
60 client-side. Use `__logs_sources` to narrow to a specific listener
61 job when needed.
62
63## Trap Field Reference
64
65The collector writes structured fields that are useful for queries:
66
67| Field | Use |
68|---|---|
69| `MESSAGE` | Rendered human-readable trap description |
70| `ND_LOG_SOURCE=snmp-trap` | Fast discriminator for trap entries |
71| `TRAP_REPORT_TYPE` | `trap`, `deduplication_summary`, or `decode_error` |
72| `TRAP_JOB` | Trap listener job name |
73| `TRAP_OID` | Numeric trap OID |
74| `TRAP_NAME` | MIB-qualified trap name |
75| `TRAP_PDU_TYPE` | `trap` (unacknowledged) or `inform` |
76| `TRAP_VERSION` | SNMP version: `v1`, `v2c`, or `v3` |
77| `TRAP_CATEGORY` | One of the bounded trap categories |
78| `TRAP_SEVERITY` | One of `emerg`, `alert`, `crit`, `err`, `warning`, `notice`, `info`, `debug` |
79| `TRAP_SOURCE_IP` | Identified trap source IP |
80| `TRAP_SOURCE_UDP_PEER` | UDP peer address |
81| `TRAP_SOURCE_UDP_PORT` | UDP peer source port for decode-error rows |
82| `_HOSTNAME` | Source device hostname when resolved by collector identity |
83| `TRAP_REVERSE_DNS` | Optional PTR annotation for the source IP; never authoritative identity |
84| `ND_NIDL_NODE` | Netdata vnode identity when known |
85| `TRAP_DEVICE_VENDOR` | Vendor slug when known |
86| `TRAP_INTERFACE` | Topology interface when enrichment is available |
87| `TRAP_NEIGHBORS` | Topology neighbors when enrichment is available |
88| `TRAP_TAG_*` | Profile/operator labels, selectable but not default facets |
89| `TRAP_VAR_*` | Indexed decoded event varbind fields. Enum-backed varbinds use the enum label, with `_RAW` carrying the numeric value. Sensitive and redundant protocol-control varbinds are skipped. |
90| `TRAP_ENRICHMENT` | JSON audit trail for source selection and enrichment decisions; search carefully, avoid faceting on it |
91| `TRAP_JSON` | Structured varbind payload and audit copy, including `netdata_packet_sequence`; prefer `TRAP_VAR_*` for normal filtering |
92| `TRAP_SUPPRESSED_COUNT` | Dedup summary only |
93| `TRAP_SUPPRESSED_FINGERPRINTS` | Dedup summary only |
94| `TRAP_REPORT_PERIOD_SEC` | Dedup summary only |
95| `TRAP_DECODE_ERROR_KIND` | Decode-error rows only; bounded failure class |
96| `TRAP_DECODE_ERROR` | Decode-error rows only; sanitized decoder error text |
97| `TRAP_PACKET_SIZE` | Decode-error rows only; received datagram size |
98| `TRAP_PACKET_SHA256` | Decode-error rows only; packet fingerprint without raw bytes |
99| `TRAP_LISTENER` | Decode-error rows only; listener endpoint when known |
100| `TRAP_ENGINE_ID` | Decode-error rows only; SNMPv3 engine ID when safely extractable |
101
102## Standard Setup
103
104Use the wrappers from `query-netdata-agents`:
105
106```bash
107source "$(git rev-parse --show-toplevel)/docs/netdata-ai/skills/query-netdata-agents/scripts/_lib.sh"
108agents_load_env
109```
110
111Cloud-proxied query, preferred by default:
112
113```bash
114NODE_UUID="YOUR_NODE_UUID"
115SNMP_TRAPS_FUNCTION="snmp:traps"
116
117agents_call_function \
118 --via cloud \
119 --node "$NODE_UUID" \
120 --function "$SNMP_TRAPS_FUNCTION" \
121 --body '{"info":true}'
122```
123
124Direct-agent query, for local or Cloud-unavailable cases:
125
126```bash
127NODE_UUID="YOUR_NODE_UUID"
128AGENT_HOST="agent.example.invalid:19999"
129MACHINE_GUID="YOUR_MACHINE_GUID"
130SNMP_TRAPS_FUNCTION="snmp:traps"
131
132agents_call_function \
133 --via agent \
134 --node "$NODE_UUID" \
135 --host "$AGENT_HOST" \
136 --machine-guid "$MACHINE_GUID" \
137 --function "$SNMP_TRAPS_FUNCTION" \
138 --body '{"info":true}'
139```
140
141## Row Decoding Helper
142
143Log Function responses store rows as arrays. Use `columns` to map row
144positions back to field names:
145
146```bash
147jq '.columns as $c
148 | .data[]? as $row
149 | $c
150 | to_entries
151 | sort_by(.value.index)
152 | map({(.key): $row[.value.index]})
153 | add' response.json
154```
155
156## Source Selection
157
158Start with `{"info":true}` for `snmp:traps` and inspect the
159`__logs_sources` required parameter. By default, the SDK selects all
160direct-journal sources. To target one listener job, add:
161
162```json
163{
164 "selections": {
165 "__logs_sources": ["local"]
166 }
167}
168```
169
170If a job is missing from `__logs_sources`, verify the job exists and
171`journal.enabled` is not `false`. Until Netdata's Function deletion
172protocol lands, a node with no direct-journal trap sources may still
173show the Function but return no sources or an unavailable response.
174
175## See Also
176
177- [Cloud log Function guide](../query-netdata-cloud/query-logs.md)
178- [Direct-agent log Function guide](../query-netdata-agents/query-logs.md)
179- [Generic Function invocation through Cloud](../query-netdata-cloud/query-functions.md)
180- [Generic direct-agent Function invocation](../query-netdata-agents/query-functions.md)
181- [SNMP trap profile format](../../../../src/go/plugin/go.d/config/go.d/snmp.trap-profiles/profile-format.md)