project-snmp-profiles-authoring

name: project-snmp-profiles-authoring description: Use when editing Netdata SNMP profile YAMLs, topology SNMP profiles, ddsnmp profile parsing, or profile-format documentation. Requires checking source MIB field accessibility, especially MAX-ACCESS not-accessible INDEX objects, before adding or changing profile symbols.

SNMP Profile Authoring

Use this skill before editing files under:

• 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/

Required Checks

1. Identify the source MIB object for every profile field being added or changed.
2. Check the object's MAX-ACCESS.
3. If the object is not-accessible, do not configure it as a readable symbol.OID.
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, format, or constant_value_one.
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, constant values, 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 from: references 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.

Index Rules

• index is 1-based.
• index_transform.start and index_transform.end are 0-based and inclusive.
• index_transform: [{start: N}] keeps index component N through the last component when N > 0.
• index_transform: [{start: 0, end: 0}] keeps only the first index component.
• drop_right can be used when the right side has fixed trailing components.

Common Patterns

Q-BRIDGE learned FDB MAC:

- tag: dot1q_fdb_mac
  symbol:
    format: mac_address
  index_transform:
    - start: 1

IP-MIB ipNetToPhysicalTable address:

- tag: arp_ip
  symbol:
    format: ip_address
  index_transform:
    - start: 3

The start: 3 skips ifIndex, address type, and the InetAddress length byte.

LLDP-MIB local management address:

- tag: lldp_loc_mgmt_addr
  symbol:
    name: lldpLocManAddr
    format: hex
  index_transform:
    - start: 2

The start: 2 skips management-address subtype and length. Use hex, not ip_address, because LLDP management addresses can carry non-IP subtypes; the topology runtime normalizes IP-compatible bytes later.

Audit Recipe

When a profile reads a table column, verify that the MIB object is readable:

rg -n -C 4 'OBJECT-TYPE|MAX-ACCESS[[:space:]]+not-accessible|ACCESS[[:space:]]+not-accessible' path/to/MIB

For known topology-sensitive symbols, scan profile YAMLs before committing:

rg -n 'name:[[:space:]]*(dot1qTpFdbAddress|ipNetToPhysicalIfIndex|ipNetToPhysicalNetAddressType|ipNetToPhysicalNetAddress|lldpLocManAddrSubtype|lldpLocManAddr)\b' src/go/plugin/go.d/config/go.d/snmp.profiles

Any hit must be reviewed. It is valid only when the tag is index-derived and does not declare symbol.OID for a not-accessible object.

When adding a new topology kind, update all three parts together:

• profile YAML using topology: - kind: <kind>;
• the Go TopologyKind enum and validation;
• the topology cache handler registry and tests.

Verify that topology rows are delivered through ProfileMetrics.TopologyMetrics, not through underscore-prefixed HiddenMetrics.

When adding or migrating licensing profile coverage, update all related parts together:

• profile YAML using licensing:;
• the closed licensing signal/state/sentinel enums and validation when adding new policy names;
• typed ProfileMetrics.LicenseRows producer/consumer tests;
• MIB evidence for every OID and every not-accessible index-derived field.

Verify that licensing rows are delivered through ProfileMetrics.LicenseRows, not through underscore-prefixed HiddenMetrics.

When adding or migrating BGP profile coverage, update all related parts together:

• profile YAML using bgp:;
• closed BGP row kind, peer-state, AFI/SAFI, and typed field validation when adding new policy names or value domains;
• typed ProfileMetrics.BGPRows producer/consumer tests;
• MIB evidence for every OID and every not-accessible index-derived field;
• SNMP integration metadata and generated docs when public BGP capability claims change.

Verify that BGP rows are delivered through ProfileMetrics.BGPRows, not through metrics:, virtual_metrics:, or underscore-prefixed hidden metrics.

When adding or refactoring SNMP profile, parser, or topology tests, prefer table-driven cases using map[string]struct{} keyed by test-case name when the cases share setup and assertion shape. Use separate test functions only for materially different setup or assertions.

Validation

Run the narrow suites for the changed area:

cd src/go
go test ./plugin/go.d/collector/snmp/ddsnmp/ddprofiledefinition
go test ./plugin/go.d/collector/snmp/ddsnmp/ddsnmpcollector
go test ./plugin/go.d/collector/snmp_topology

See src/go/plugin/go.d/collector/snmp/profile-format.md for the full profile syntax and the "Field accessibility" section.