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

1. 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.
2. 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.
3. 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.
4. 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.
5. 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:

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

• Cloud log Function guide
• Direct-agent log Function guide
• Generic Function invocation through Cloud
• Generic direct-agent Function invocation
• SNMP trap profile format