Collectors Snmp Trap Profiles

SNMP Trap Profile Authoring

Use this skill for authoring or reviewing the affected contracts under:

• src/go/plugin/go.d/config/go.d/snmp.trap-profiles/ (stock pack default/, catalogue.json, profile-format.md)
• src/go/cmd/snmptrapprofilegen/ (the generator; installed as snmp-trap-profile-gen)
• src/go/plugin/go.d/collector/snmp_traps/internal/catalog/ when the change is about what a profile may contain

Select The Task

Apply AGENTS.md#skill-selection. Review checks affected rules against source and existing validation evidence; implementation procedures below do not require a reviewer to create artifacts, regenerate the pack, call a classifier or install profiles. Select additional sections when the changed behavior reaches them.

Authoritative sources

This skill holds only what the documents below lack. Point at them; do not restate them here.

• src/go/plugin/go.d/config/go.d/snmp.trap-profiles/profile-format.md: the profile format (file layout, the varbinds table, trap entries, .0. tolerance, description templates, metrics:/charts: rules and their validation list, categories, severities, cardinality, operator overrides, generated stock profiles). It ships with the pack under usr/lib/netdata/conf.d/go.d/snmp.trap-profiles/, so it is operator-facing and must stay true to the loader.
• src/go/plugin/go.d/collector/snmp_traps/ARCHITECTURE.md: how the collector works (life of a trap, journal field contract, package map, "Where To Change Things", and the validation commands; the sections a rule below relies on are cited as src/go/plugin/go.d/collector/snmp_traps/ARCHITECTURE.md#where-to-change-things and src/go/plugin/go.d/collector/snmp_traps/ARCHITECTURE.md#validation). Collector code changes start there, not here.
• docs/npm/snmp-traps/ (published operator docs): trap-profiles.md (override versus new profile), configuration.md (every job option), field-reference.md (every TRAP_* field), metrics.md (built-in charts and dimensions).
• Sibling skills: collectors-snmp-profiles for polling profiles; query-snmp-traps for reading trap logs.
• Design history (rejected alternatives, the comparison with other trap systems, the phase plans) is not maintained in the tree; the pre-implementation design records that used to live in this directory are in git history.

Required checks before changing a profile

1. Trap name: is MIB-qualified <MIB-MODULE>::<symbol> (IF-MIB::linkDown). Bare symbols are reused across vendor MIB modules and are not unique; the qualified form is what snmptranslate produces and what lands in TRAP_NAME. If the OID changes, the name changes. Different OIDs must have different names (profile-format.md, "Trap entries").

2. Check MAX-ACCESS of the source MIB object for every varbind. A not-accessible index object still belongs in the varbinds table, so that the rare device that does include it gets it named in TRAP_JSON and, when non-sensitive and non-redundant, as an indexed TRAP_VAR_* field. Never use it as a description: template variable on its own: an SNMP entity normally does not send it in the trap PDU, so the placeholder renders empty. No in-tree artifact can check this; it needs the MIB.

3. Every varbind reference resolves. A name in a trap's varbinds: list must exist in the file-scoped varbinds: table or be an inline {name, oid, type} dict on that trap. A dangling name renders empty in the description and produces a misleading journal message. Table entries need both oid and type; an empty {} entry fails profile load. The generator drops extractor records with an empty name, OID, or type from the table and from every trap's reference list (buildProfile, pinned by TestBuildProfileDropsUnresolvedVarbinds); do the same by hand.

4. Keep the metadata the loader validates. Trap status: takes only current, deprecated, mandatory, obsolete, optional (validTrapStatuses in the generator, validStatuses in internal/catalog/profile.go). Varbind enum: is what renders {{value}} symbolically and what equals/in predicates match; constraints: documents the range. File-scope vendor:, mib_count:, trap_count: are emitted on every stock file. Do not strip any of them when editing.

5. Categories: closed set of 8. state_change, config_change, security, auth, license, mobility, diagnostic, unknown. Cross-cutting concerns (compliance scope, tenant, datacenter, change window) go in labels:, not new slugs. Every profile entry declares category and severity (the loader rejects a missing or unknown value); only a trap with no profile match is logged with unknown/notice at runtime, and operators reclassify it through the job's overrides:. There is no "custom" category. Changing the set is taxonomy work.

6. Severities: closed set of 8 full syslog names mapped to PRIORITY=0..7: emerg, alert, crit, err, warning, notice, info, debug (never warn). emerg is for true vendor catastrophe; routine events are warning/notice/info; debug only when the MIB itself marks the notification debug-level.

7. Label cardinality. Label templates reference bounded varbinds only. Reject labels built from MAC addresses, source IPs, usernames, packet contents, RAID slot IDs, or any per-event identifier; the loader rejects unbounded label templates at profile load. High-cardinality content belongs in description: (rendered into MESSAGE), the indexed TRAP_VAR_* fields, and TRAP_JSON, none of which propagate to metrics.

8. Label keys match [a-z][a-z0-9_]* and emit as TRAP_TAG_<KEY_UPPERCASE>, whether they come from a profile's labels: or from a listener job's per-OID overrides[].labels (there is no job-wide labels: option). The dedicated prefix makes collision with the plugin-owned TRAP_* fields impossible, so the key syntax is the only check. See docs/npm/snmp-traps/field-reference.md for the shipped TRAP_* set (it is not closed at the profile level; new fields arrive with collector releases).

9. Trap OID form and .0. tolerance. Use the OID form the source MIB tooling produces. Lookup is exact-match first, then retries the alternate spelling with one .0. segment added or removed before the final arc (model.AlternateTrapOID, called from Epoch.lookupLoaded). A catalogue that defines both spellings of one trap fails to load ("alternate form already defined"). The tolerance is trap-OID only: never normalize or alternate-match varbind OIDs.

10. Stock versus operator. Files under default/ are generated and overwritten on regeneration (their header comment says so); never hand-edit them for site concerns. Operator profiles live in the user config directory go.d/snmp.trap-profiles/ (catalog_paths.go) in one of three forms: a complete same-identity replacement of a stock file, an independent different-identity addition, or a metric-only profile whose rules reference stock traps. Partial inheritance does not exist; an extends: key is rejected as unknown at profile load. Per-OID category, severity, and label overrides belong in the listener job's overrides: (docs/npm/snmp-traps/trap-profiles.md has the decision table).

11. No hand-authored journal fields. There is no journal_fields: key: TRAP_VAR_* fields are derived from the received non-sensitive, non-redundant varbinds and TRAP_JSON keeps the audit copy. display_hint is documented as a future varbind field but is not part of the loaded schema: varbinds: entries accept unknown keys (profileYAMLSpec in internal/catalog/load.go), so a hand-added display_hint is silently ignored and then overwritten on regeneration. When the renderer starts consuming DISPLAY-HINT metadata, the extractor, profile-format.md, and model.TrapEntry change in the same cycle.

12. Profile metrics only through the validated schema. profile-format.md, "Optional metrics: rules and charts:", owns the syntax, defaults, numeric source types, and the load-time rejection list; a listener job enables rules explicitly with profile_metrics.include (rule names, never trap names or filenames). Checks the loader enforces (internal/catalog/metric_validate.go) that authors most often get wrong:

    • Chart IDs and contexts must not reuse the six built-in charts events, severity, errors, dedup_suppressed, pipeline, profile_metric_diagnostics or their snmp.trap.* contexts; a chart context defaults to snmp.trap.<chart id> and must start with snmp.trap.; metric names must not start with a reserved prefix (builtInProfileMetricChartIDs, reservedProfileMetricPrefixes).
    • Every where: predicate selects exactly one string-valued source: varbind, or field from the closed set category, severity, trap_name, trap_oid; predicates AND; use absent, not not plus exists.
    • identity.resource.key_from_varbind must be an integer-like bounded varbind (INTEGER, Integer32, Unsigned32, Gauge32); Counter32, Counter64, TimeTicks are sample values, not identity keys.
    • missing: is one of drop, error, zero, unknown_dimension (zero is invalid for counter and state; unknown_dimension needs resource identity). Authoring rules the loader does NOT check, so review them by hand:
    • Every rule sharing a chart has the same label shape: do not mix resource and non-resource rules, or several resource classes, in one chart.
    • Declare lifecycle explicitly on every chart that creates per-source or per-resource instances instead of relying on the loader's defaults; expired instances are removed and a returning identity starts a fresh series.
    • On a chart that carries a state rule, lifecycle.expire_after_cycles must outlast state.ttl: the TTL publishes the clear value once and only then expires the series, so a chart that expires first leaves the problem state as the last value. The loader validates the two fields independently and never compares them. A rule's where: is evaluated before its state.set_when/clear_when predicates.
    • Never use the community varbind or another sensitive varbind (model.IsSensitiveVarbind) as a predicate or sample source; redaction happens downstream, not in rule validation.
    • Profile rules describe vendor or site semantics, never receiver health. Profile metrics update only after the trap is committed to the configured backend; dedup-suppressed and write-failed traps do not count.
    • No stock profile ships metrics: today (0 of 803). Stock rules would be a curation layer that the generator must preserve through a tested read-modify-write path from a reviewable, committed source recording rule name, trap, varbinds, type, chart, and cardinality evidence, and must validate against the varbinds: and traps: it just emitted before writing the file. That path does not exist; build it before adding stock rules, and check pack size and lazy-load memory when you do.