SNMP Trap Metrics

Use this page to read the SNMP trap receiver metrics: whether the receiver is healthy, whether traps are flowing, and what the receiver is dropping or suppressing. For the default health alerts that ship for these metrics, see Alerts.

SNMP trap metrics describe the receiver and the traps that reached it. They do not prove the complete state of a device. Absence of traps is not proof of absence of events, because a device may be quiet, misconfigured, blocked by the network, or sending to another destination.

For setup and related operator workflows, see:

• Configuration
• Usage and Output
• Alerts
• Validation and Data Quality
• Troubleshooting

Receiver pipeline

The SNMP trap receiver pipeline chart shows per-job event rates for the receiver path. Use it first when deciding whether the listener is receiving packets and whether accepted traps are reaching the configured output backend.

Every packet walks the same funnel; the branches are where traps are lost or held:

Dimension	What it means	Operator use
received	A UDP packet entered the trap handler.	Confirms traffic reached the listener process. This counts after the kernel UDP buffer, so datagrams the kernel drops are invisible here — watch ipv4.udperrors (RcvbufErrors) for kernel drops and see Sizing and Capacity for buffer tuning.
decoded	The packet parsed as an SNMP trap or INFORM PDU.	Compare with received to find packets rejected before or during decode, such as source allowlist drops, unsupported sniffed versions, authentication failures, or malformed packets.
accepted	The trap became a normal trap entry after source checks, profile lookup, template rendering, and source attribution.	Compare with decoded to find post-decode policy or source-identity checks that stopped a decoded trap before acceptance.
committed	The trap was accepted by the configured output (journal or OTLP).	This is the strongest receiver-side signal that the receiver accepted the trap for local storage or export. Backend failures are exposed by write and export error metrics.
dedup_suppressed	A repeated trap matched deduplication and was counted in a periodic summary instead of stored as its own row.	Expected during repeated events when deduplication is enabled.
dropped	A packet entered the handler but did not become a committed trap, a dedup summary, or a write failure. Decode-error rows can also increment it alongside their error dimension.	Compare with the processing-error dimensions and decode-error rows to separate decode failures, policy drops, and rate limits.
write_failed	The authoritative output (journal, or OTLP when journal is disabled) could not keep the trap.	Which counters rise depends on the backend mode — see the table below.

Which counters rise on a backend failure

Job backend mode	On a journal write failure	On an OTLP export failure
Journal only	write_failed + journal_write_failed	— (no OTLP)
Journal + OTLP	write_failed + journal_write_failed	otlp_export_failed only — the journal copy is unaffected, so write_failed does not rise
OTLP only	— (no journal)	write_failed + otlp_export_failed — terminal; the trap is lost

Interpret gaps in order:

• received rising while decoded is flat usually points to source allowlist, unsupported sniffed version, authentication, or malformed packet problems before a parsed trap exists.
• decoded rising while accepted is flat usually points to post-decode policy checks: version or community allowlist drops, engine ID checks, or rate limits. Profile lookup problems and template issues are data-quality signals on traps that can still become accepted entries. Dedup suppression does not keep accepted flat; it is tracked separately.
• received rising while committed is flat means traps are reaching the receiver but are not being accepted by the configured output writer. Check dropped, dedup_suppressed, write_failed, and the error dimensions.
• write_failed rising means the authoritative backend could not keep traps. See Which counters rise on a backend failure for which counter maps to which backend mode.
• dedup_suppressed rising means repeated rows were intentionally collapsed. Confirm the deduplication policy before treating this as loss.

Categories and severities

Category and severity charts count traps after receiver commit. They classify trap rows accepted by the configured writer; they are not polling metrics and do not prove current device state.

The SNMP trap events chart uses this fixed category set:

Category	Typical meaning
state_change	A device, interface, service, sensor, peer, or component changed state.
config_change	Configuration changed on the sender.
security	Security-related event.
auth	Authentication or authorization event.
license	License state or entitlement event.
mobility	Wireless or roaming event.
diagnostic	Diagnostic, test, or health-reporting event.
unknown	Netdata could not classify the trap with a loaded profile or override.

The SNMP trap events by severity chart uses this fixed severity set:

Severity	Operator meaning
emerg	System unusable. Treat as immediate device-side emergency.
alert	Immediate action required.
crit	Critical condition.
err	Error condition.
warning	Warning condition.
notice	Normal but significant condition.
info	Informational event.
debug	Debug-level event.

Severity and category come from trap profiles or local overrides. If unknown grows, check profile coverage and any custom profile load errors.

Processing errors

The SNMP trap processing errors chart shows per-job error rates. Some errors can still produce a decode_error row if the receiver can write one; other drops happen before a row exists and are visible only as metrics.

Dimension	What to check
unknown_oid	The trap was decoded, but no loaded profile matched its trap OID. Add or fix profile coverage if the trap should be classified.
decode_failed	The packet could not be decoded and did not match a more specific decode error class. Check sender version and packet validity.
template_unresolved	A profile template referenced a missing varbind or field. Check custom profile templates and the trap payload.
malformed_pdu	The PDU was structurally invalid, too large, missing required trap fields, or otherwise malformed. Check sender firmware and packet capture.
dropped_allowlist	The sender, SNMP version, or community was outside the allowed configuration. Check allowlist.source_cidrs, versions, and communities.
rate_limited	A sender exceeded the configured per-source rate limit. Check rate_limit settings and sender storm behavior.
auth_failures	Authentication or decryption failed. Check SNMP community or SNMPv3 auth/privacy settings.
usm_failures	SNMPv3 USM processing failed. Check users, protocols, keys, and sender engine state.
unknown_engine_id	SNMPv3 engine ID was not accepted or could not be resolved according to the job configuration. When dynamic_engine_id_discovery is enabled, first-time accepted (engineID, username) registrations also increment this counter once per job lifetime as a visibility signal. Check engine ID whitelist, dynamic discovery settings, cap exhaustion, invalid sender state, or unauthorized senders.
inform_response_failed	The receiver failed to send an INFORM acknowledgement. This is non-blocking: the trap can still continue through the receiver. Check the local socket and network path back to the sender.
binary_encoded	Structured fields were written with binary journal encoding for CWE-117 log-injection protection. Applies to the direct-journal path; OTLP-only jobs keep this counter at zero. A low background rate can be normal with known binary varbinds, but the default snmp_trap_binary_encoded_fields alert warns on any sustained non-zero rate over 10 minutes. Tune or silence that alert for known steady-state binary sources; investigate new or rising rates by checking profile labels, rendered varbind values with control characters, invalid UTF-8, or binary payload values.
profile_load_failed	Trap profile loading or lookup failed. Check custom profile YAML and profile directories.
journal_write_failed	Direct journal write failed. Check disk space, permissions, and the per-job journal directory.
otlp_export_failed	OTLP export failed. Check endpoint, credentials, TLS, queue pressure, and network path.
listener_read_failed	The listener failed to read from a bound UDP socket. Check operating-system socket errors and listener lifecycle logs.

For configuration details, see the rate limiting, deduplication, and output backend sections.

Deduplication suppression

The SNMP trap dedup suppressed events chart appears when deduplication is enabled. Its dimension is suppressed, and it counts repeated matching traps that were intentionally suppressed during the deduplication window. The receiver pipeline chart tracks the same suppressed traps as dedup_suppressed, so both dimensions rise and fall together.

Deduplication protects storage and downstream systems from repeated identical rows. A suppressed trap is not committed as a normal trap row and does not update profile-defined metrics. It is represented by deduplication metrics and summary rows instead, so the suppression remains auditable.

Use this chart with the pipeline:

• dedup_suppressed rising with stable committed means repeated events are being collapsed as configured.
• dedup_suppressed rising at very high rate can indicate a device-side trap storm.
• If distinct resources are being collapsed together, review dedup.key_varbinds in Configuration.

Source-level investigation

Built-in receiver metrics are job-scoped. To identify active or affected senders, filter and group trap rows by TRAP_SOURCE_IP or TRAP_SOURCE_UDP_PEER, then inspect TRAP_ENRICHMENT when the selected source differs from the UDP peer or attribution is unclear. See Journal and Querying for source filters and Field Reference for the source and enrichment contracts.

Use profile-defined metrics when a vendor or site semantic needs a bounded device-level time series. They are opt-in and have separate source, resource, and instance limits.

Profile-defined metrics

Profile-defined metrics convert selected committed traps into time-series. They are disabled by default and must be enabled with profile_metrics in Configuration.

Important behavior:

• Only committed traps update profile metrics. A later journal or OTLP failure does not roll back a metric that was already updated, so a metric and its downstream export can briefly diverge.
• Dedup-suppressed traps do not update profile metrics.
• Traps that fail their authoritative output commit do not update profile metrics. When journal and OTLP are both enabled, journal is authoritative, so a later OTLP export failure does not roll back the metric update.
• Fixed cardinality limits protect the node by bounding enabled rules, sources, resources per source, and total metric instances per job.
• Over-cap profile metric instances are skipped and counted by diagnostics; the accepted trap can still be committed.

profile_metrics.include explicitly lists every loaded rule that runs. At least one rule is required when profile metrics are enabled.

When at least one profile metric rule is selected, Netdata also emits the dynamic SNMP trap profile metric diagnostics chart, context snmp.trap.profile_metric_diagnostics, for the listener job.

Dimension	What it means	Operator use
rule_missed	A selected rule did not match the trap, or a missing value used missing: drop.	Expected when a rule applies only to some traps. Sudden changes can mean the trap payload or profile predicates changed.
extraction_failed	A selected rule matched but could not extract a required runtime value.	Check the profile rule, varbind type, and trap payload.
attribution_failed	Netdata could not derive a source identity for the metric instance.	Check source attribution and enrichment evidence.
overflow_dropped	A new metric instance exceeded source, resource, chart, or job cardinality caps.	Tighten rule identity or reduce selected rules.
source_transitions	The same source route changed between fallback and vnode or device attribution.	Check enrichment, vnode matching, relays, and whether sender identity is stable.

Enable only rules with bounded identity and labels. For trap row fields and deduplication summary rows, see Usage and Output. For validation workflow and data-quality checks, see Validation and Data Quality and Troubleshooting.