Trap Profiles

Trap profiles are the meaning layer for SNMP traps. They tell Netdata how to turn a raw trap OID into useful log fields, tags, messages, and optional metrics.

Use this page when you need to understand why a trap has a specific name, category, severity, message, tag, or profile-derived chart when profile metrics are enabled. For listener setup and hardening, see Configuration.

What profiles do

An SNMP trap packet carries a numeric trap OID and a set of varbinds. A trap profile maps that data to operator-friendly output:

• TRAP_OID: the numeric trap OID used to match the loaded profile entry.
• TRAP_NAME: the MIB-qualified trap name, such as SNMPv2-MIB::coldStart.
• TRAP_CATEGORY: one of Netdata's trap categories, such as state_change, config_change, security, or unknown.
• TRAP_SEVERITY: one of the syslog severity slugs, such as warning, notice, or crit.
• MESSAGE: the human-readable trap message rendered from the profile description.
• TRAP_TAG_*: profile-defined or override-defined labels that are safe to index and filter.
• TRAP_VAR_* and TRAP_JSON: decoded varbind fields and the structured varbind payload.
• Profile-defined metrics and charts, when loaded profiles define metric rules and the listener job enables selected rules.

There is no separate TRAP_MESSAGE journal field. The profile-rendered message is written to the standard journal MESSAGE field.

Profiles also define varbind metadata, including symbolic names, OIDs, types, and enum labels. For enum-backed varbinds, TRAP_VAR_* shows the readable enum label in Logs and a sibling TRAP_VAR_*_RAW field keeps the original numeric value.

What ships

Netdata ships with a stock trap profile pack covering 800+ vendors, 6,000+ MIBs, and 150,000+ trap definitions. These profiles cover many common network devices without manual MIB work.

Stock profiles provide:

• Numeric trap OID to TRAP_NAME mapping.
• Closed-set TRAP_CATEGORY and TRAP_SEVERITY values.
• Human-readable MESSAGE templates.
• Varbind names, types, and enum labels.

The current stock pack provides trap decoding coverage. It does not ship profile metric rules or chart definitions, so profile-derived charts require operator profile files that define metrics: and charts: rules.

The category set is fixed: state_change, config_change, security, auth, license, mobility, diagnostic, and unknown.

The severity set is fixed: emerg, alert, crit, err, warning, notice, info, and debug. Netdata maps these to the journal PRIORITY field.

Unknown OIDs

An unknown OID is not the same as broken ingestion.

When Netdata receives and accepts a trap whose OID is not in the loaded profile set:

• the trap is still stored or exported if the configured output backend succeeds;
• TRAP_OID keeps the numeric trap OID;
• TRAP_CATEGORY is unknown;
• TRAP_SEVERITY is notice;
• MESSAGE uses a plain fallback form that includes the OID and source;
• profile-derived names, labels, descriptions, and metrics are not added.

Use unknown OIDs as a coverage signal. If the device is sending a valid trap that your operators need to recognize, add an operator profile file or convert the vendor MIBs into a profile.

Profile lookup tries the exact trap OID first, then tries a single .0. insertion or removal around the last arc to handle SMIv1 and SMIv2 trap OID form differences. For example, 1.3.6.1.4.1.14179.2.6.3.24 and 1.3.6.1.4.1.14179.2.6.3.0.24 resolve to the same profile entry. TRAP_OID still shows the OID sent by the device.

Profile locations

Depending on installation type, paths may be prefixed with /opt/netdata.

Operator profiles should normally stay as editable .yaml or .yml files. Stock profiles are reference-only; they are not the place for site-specific edits, and package updates can replace them.

For the profile YAML schema, see SNMP Trap Profile Format.

Custom MIB conversion

Netdata does not compile ASN.1 MIB files while traps arrive. Runtime trap decoding uses loaded YAML profiles.

If you have vendor MIBs that are not covered by the stock pack, convert them offline with the installed helper:

/usr/libexec/netdata/plugins.d/snmp-trap-profile-gen generate \
  --source-dir ./mibs \
  --all \
  --out-dir ./snmp-trap-profile-gen-output

The helper writes generated profile YAML files under:

./snmp-trap-profile-gen-output/profiles/

Copy the needed YAML files into:

/etc/netdata/go.d/snmp.trap-profiles/

Then confirm the next matching trap resolves to the expected TRAP_NAME, TRAP_CATEGORY, TRAP_SEVERITY, MESSAGE, and TRAP_VAR_* fields in Logs. Generated profiles should be reviewed before use; add or adjust metrics: and charts: sections only when you intentionally want profile-derived metrics.

Per-OID overrides vs profile files

Use the smallest control that matches the job.

Partial profile inheritance is not supported, and the extends: key is rejected. Use listener-job overrides for category, severity, or label policy changes; use a complete same-name operator profile when decode definitions must change.

For simple policy overrides, configure the listener job:

overrides:
  - oid: 1.3.6.1.4.1.9.9.43.2.0.1
    category: config_change
    severity: notice
    labels:
      change_window: business_hours

Label keys become TRAP_TAG_<KEY_UPPERCASE> fields. For example, change_window becomes TRAP_TAG_CHANGE_WINDOW. Label keys must start with a lowercase letter and then use only lowercase letters, digits, and underscores.

Job overrides use static label values. Profile-file labels can also use templates, but templated label values must come from bounded sources such as enum-backed varbinds, booleans, small numeric ranges, {{trap_name}}, or {{vendor}}; unbounded values such as source IPs, hostnames, interface descriptions, MAC addresses, usernames, packet contents, and free-form descriptions are rejected at profile load time.

Profile loading behavior

• Profiles are immutable while any listener job holds a lease on the shared catalog epoch.
• After changing operator or stock profiles, restart the Agent or recreate all listener jobs. The final lease release unloads the epoch, and the next job creation loads operator profiles and the stock manifest.
• Operator profiles, exactly one stock manifest (catalogue.json or catalogue.json.zst), and its profile inventory are validated during collector initialization. Collector.Check() performs no additional validation. Gzip manifests and raw-plus-Zstandard duplicates are rejected; there is no parse-all fallback.
• Every stock manifest entry includes a SHA-256 of the exact decompressed YAML bytes. Lazy hydration verifies and parses those same bytes, so a running catalog epoch rejects a profile body changed underneath its manifest. The digest binds one installed generation together; it is not a package-authenticity signature.
• Stock vendor YAML is loaded and validated only when selected by an exact trap OID, an enabled metric rule, or the candidate-file set for a MIB-qualified trap name. Name resolution hydrates the MIB candidates and then requires one exact trap-name match; it does not load the complete stock pack.
• Invalid eager profiles fail listener job creation. An invalid lazily loaded stock profile increments profile-load-failure metrics when a matching trap first needs that file.

Profile validation failures are visible as collector errors and profile-load-failure metrics. After editing profiles, check Logs and receiver metrics before assuming a change is active; see Metrics for the receiver diagnostics.

Verify profile changes

After adding or changing an operator profile:

• Restart the Agent or recreate all listener jobs, then check the Netdata Agent logs for profile validation errors.
• Check the profile_load_failed, unknown_oid, and template_unresolved dimensions in the SNMP trap processing errors chart.
• Send or wait for a matching trap, then confirm the expected TRAP_NAME, TRAP_CATEGORY, TRAP_SEVERITY, MESSAGE, TRAP_VAR_*, and TRAP_TAG_* fields in Logs.
• If profile_metrics.include names a missing rule, the listener job fails validation with profile_metrics.include rule "<name>" not found. If the rule exists but is disabled in the profile, validation fails with profile_metrics.include rule "<name>" is disabled by profile. Fix the rule name, select another rule, or enable the intended rule in the loaded operator profile.

For field-level query details, see Usage and Output and Field Reference.

Profile-defined metrics and cardinality

Profiles can define optional trap-to-metric rules and chart definitions. Listener jobs decide whether to evaluate those rules with profile_metrics.

Profile metrics are disabled by default, and the current stock pack does not ship metric rules. To create profile-derived charts today:

1. Add metrics: and charts: rules to an operator profile file under /etc/netdata/go.d/snmp.trap-profiles/.
2. Restart the Agent or recreate all listener jobs so the catalog epoch is rebuilt.
3. Enable profile_metrics in the listener job and select the loaded rule names.

Rule names in include come from metric rule name fields in profile YAML files. The stock manifest routes selected names to their owning files; unrelated stock files remain unloaded. If no operator or stock profile defines a selected rule, listener job creation fails validation.

The listener-side profile_metrics settings are documented in Configuration. Rule and chart syntax live in SNMP Trap Profile Format.

Use profile metrics for bounded, operator-useful trap signals, such as:

• counting committed configuration change traps;
• tracking trap-derived state where the profile defines a clear problem and clear condition;
• sampling numeric varbind values from traps when the varbind type is supported.

Do not use high-cardinality values as metric labels or resource identities. Avoid MAC addresses, source IPs, usernames, interface descriptions, packet contents, event IDs, and other per-event values as labels. Put those values in MESSAGE, TRAP_VAR_*, and TRAP_JSON instead.

Only committed traps update profile metrics. For the exact update rule (dedup-suppressed and failed-write traps do not update metrics, and an OTLP export failure does not roll back an already-updated metric), see Metrics.

If metric rules exceed source, resource, chart, or job limits, Netdata skips the over-cap metric instance, keeps accepting traps, and increments profile metric diagnostics.

For full metric rule syntax, validation rules, and examples, see SNMP Trap Profile Format.

Next steps

• To configure listener jobs, overrides, outputs, and profile_metrics, see Configuration.
• To query received traps and read profile-enriched output, see Usage and Output.
• To understand source identity, relay handling, and device context, see Enrichment.
• To understand every emitted trap field, see Field Reference.