Collectors Snmp Profiles

SNMP Profile Authoring

Use this skill when authoring or reviewing the profile contracts in:

• src/go/plugin/go.d/config/go.d/snmp.profiles/
• src/go/plugin/go.d/collector/snmp/ddsnmp/
• src/go/plugin/go.d/collector/snmp/profile-format.md
• src/go/plugin/go.d/collector/snmp_topology/

Boundary: this skill owns the profile topology: rows, which OIDs feed the SNMP topology producer and how they are extracted. What the producer emits from those observations (actors, links, evidence, modals) is the payload contract in src/plugins.d/FUNCTION_TOPOLOGY_DEVELOPER_GUIDE.md; the developer workflow for changing it is .agents/skills/topology-authoring/SKILL.md.

Select The Affected Contract

Apply AGENTS.md#skill-selection. Review uses the checks below and existing source/validation evidence; it does not create an implementation SOW or require a live device capture. Live access remains within the task's authorization. Verify every added or changed acquisition symbol against its source MIB. A prose-only change does not require a new MIB audit of untouched symbols; parser changes still need the relevant input and consumer contracts.

Required Checks

1. Identify the source MIB object for every profile field being added or changed.
2. Check the object's MAX-ACCESS (SMIv2) or ACCESS (SMIv1).
3. If the object is not-accessible, do not configure it as a readable symbol.OID unless it satisfies every device-scoped MIB-deviation requirement below.
4. If a not-accessible object appears in the table INDEX, derive it from the row OID index using index or index_transform.
5. Keep index extraction and value formatting separate:
   • use index for one index component;
   • use index_transform for multiple components;
   • use symbol.format only for final formatting such as ip_address, mac_address, or hex.
6. Put SNMP topology rows under top-level topology: with a required closed kind. Do not mark topology rows by naming metrics _topology_*.
7. Do not use chart/export-only value fields on topology row anchor symbols: chart_meta, metric_type, mapping, transform, scale_factor, or format.
8. Keep regular systemUptime rows under metrics:. Do not model uptime as a topology row kind; topology-specific uptime acquisition belongs in collector code, not profile topology schema.
9. Put SNMP licensing rows under top-level licensing:. Do not model licensing telemetry as underscore-prefixed hidden metrics or _license_* tag protocols.
10. Licensing row value symbols may use format and exact mapping, but must not use chart/export fields, transforms, scale factors, or underscore-prefixed generated names.
11. For scalar licensing rows that combine multiple scalar signal OIDs into one license row, declare an explicit stable id:. For table licensing rows, keep every effective OID source (symbol.OID, from, or legacy OID) inside the same table OID and derive not-accessible INDEX values from the row index.
12. Put SNMP BGP rows under top-level bgp:. Do not model BGP telemetry as vendor-specific raw metrics, virtual_metrics, or underscore-prefixed tag protocols when adding or migrating BGP coverage.
13. BGP peer-state mappings must use the six RFC 4271 canonical states (idle, connect, active, opensent, openconfirm, established). Use partial: true plus partial_states only when the source MIB is intentionally partial.
14. For BGP table rows, derive not-accessible INDEX objects with exactly one row-index selector: index, index_from_end, or index_transform. Use index_from_end for trailing AFI/SAFI-like components after variable-length indexes such as InetAddress.
15. To constrain a topology table to a fixed structural index prefix, use one readable anchor symbol and set table.OID to <anchor-column>.<prefix>. A simple same-index cross-table dependency inherits that prefix and is anchor-gated only when its target table has no symbol-bearing producer. A target route with a real symbol owner remains eager. Do not rely on propagation for ordinary metrics, multiple anchors, lookup_symbol, index_transform, or conflicting dependency scopes.

Device-Scoped MIB Deviations

A vendor profile MAY poll an object that the source MIB marks not-accessible only when all of these requirements hold:

• Scope: The polling row is declared in a selector-matched device or topology-role profile. A generic standards profile MUST NOT carry the deviation.
• Proof: A checked repository fixture or repeatable live capture proves that the matched device returns the object as a readable column and omits the standards-readable anchor needed to obtain the row otherwise.
• Isolation: The device row overrides the generic row identity instead of adding a second generic fallback or a second topology kind.
• Documentation: A short profile comment explains the vendor deviation and why index-only decoding cannot be used.
• Regression: Tests pin both the selector-scoped override and real fixture collection through the profile parser and consumer path.

Do not generalize a device deviation to related models or vendors without equivalent evidence.

Canonical Profile Syntax

Stock profiles MUST use symbol objects for OID/name pairs, including metric tags and typed licensing/BGP values. Put metric type overrides on each affected symbol or symbols entry instead of the deprecated row-level metric_type. Legacy custom profile aliases remain supported; typed OID precedence is symbol.OID, then from, then legacy OID. Collection, boundary validation and inheritance identity use that same source. Prefer one OID source form per value. Metric and topology column rows require table.OID; table.name is optional for those rows. The retired constant_value_one key is ignored. Ordinary metric symbols still require OIDs; do not use the key to generate or suppress metrics.