netdata/netdata

collectors-snmp-profiles

Author or review Netdata SNMP polling profiles, ddsnmp parsing, topology/licensing/BGP rows and profile-format documentation.

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/netdata/netdata --skill collectors-snmp-profiles

Before you start

  • Installation does not include a model subscription, API allowance or permission to access your files.
  • Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

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.

Affected behaviorRead/check
Acquired OIDs, index extraction or a device deviationRequired Checks, Device-Scoped MIB Deviations and Index Rules below; src/go/plugin/go.d/collector/snmp/profile-format.md#field-accessibility
Profile syntax, inheritance or parser behaviorCanonical Profile Syntax, full profile-format owner and parser/consumer tests
Topology, licensing or BGP rowsTheir Required Checks and Audit Recipe items; follow the typed producer/consumer paths
Emitted topology payloadtopology-authoring; this skill still covers affected profile acquisition
Received trap profiles or trap logscollectors-snmp-trap-profiles or query-snmp-traps

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.

  1. If a not-accessible object appears in the table INDEX, derive it from the row OID index using index or index_transform.
  2. 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.
  1. Put SNMP topology rows under top-level topology: with a required closed

kind. Do not mark topology rows by naming metrics _topology_*.

  1. Do not use chart/export-only value fields on topology row anchor symbols:

chart_meta, metric_type, mapping, transform, scale_factor, or format.

  1. 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.

  1. Put SNMP licensing rows under top-level licensing:. Do not model licensing

telemetry as underscore-prefixed hidden metrics or _license_* tag protocols.

  1. 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.

  1. 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.

  1. 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.

  1. 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.

  1. 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.

  1. 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.

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:

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

IP-MIB ipNetToPhysicalTable address:

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

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

IP-MIB ipAddressTable IPv4 address:

yaml
table:
  OID: 1.3.6.1.2.1.4.34.1.3.1.4
  name: ipAddressTableIPv4
symbols:
  - OID: 1.3.6.1.2.1.4.34.1.3
    name: ip_if_index
metric_tags:
  - tag: topo_ip_addr
    symbol:
      name: ipAddressAddr
    index_transform:
      - start: 2

The table root anchors on readable ipAddressIfIndex and appends index prefix 1.4 for IPv4 type and its required four-octet length. The address is the not-accessible ipAddressAddr index component; start: 2 skips address type and length. The open-ended slice is intentional: a fixed end would hide malformed trailing components instead of letting the strict consumer reject the row. Keep the transformed components raw and require the topology consumer to decode exactly four decimal octets in 0..255; structural walk scope alone does not validate the remaining instance suffix. A malformed descendant can activate dependency walks, but it MUST NOT emit topology.

LLDP-MIB local management address:

yaml
- 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:

bash
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:

bash
rg -n 'name:[[:space:]]*(dot1qTpFdbAddress|ipAddressAddr|ipNetToPhysicalIfIndex|ipNetToPhysicalNetAddressType|ipNetToPhysicalNetAddress|lldpLocManAddrSubtype|lldpLocManAddr|lldpRemManAddrSubtype|lldpRemManAddr)\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 without a symbol.OID, or when it satisfies every device-scoped MIB-deviation requirement above.

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

Select the suites for the affected behavior and its consumers. Existing relevant results count as review evidence; run local checks when needed to verify a claim, without treating review as a request to change profiles. From src/go:

bash
# Profile schema, parsing and validation
go test ./plugin/go.d/collector/snmp/ddsnmp/ddprofiledefinition
# Acquisition, index decoding and typed row delivery
go test ./plugin/go.d/collector/snmp/ddsnmp/ddsnmpcollector
# Topology consumption of profile observations
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.

from this repository

More skills

All skills
netdata
Community

collectors-authoring

Author, modify, or review Netdata collectors across Go, IBM, C, Rust and external plugins. Start here for collector lifecycle, metric identity, missing data, cost, cardinality, SNMP/Prometheus profiles, statsd, logs, topology, flow/OTEL ingestion and Functions. Routes to domain and framework guidance. Operator queries use the query skills.

1h installs
2
GitHub stars
81.3K
Updated
Nov 4
netdata
Community

collectors-go-design

Design or review go.d collector and discoverer contracts, including capability scope, options, metric meaning and identity, vnodes, Functions, ownership, remote writes and durable state. Also author or review DynCfg configschema.json forms. Contract-preserving fixes and migrations use framework guidance; integration prose uses the metadata skill.

1h installs
2
GitHub stars
81.3K
Updated
Nov 4
netdata
Community

collectors-go-framework-v2

Implement, migrate or review Go go.d framework V2 collectors, CollectorV2 lifecycle, metrix metric stores, charts.yaml authoring (defaults, families, ordering, statesets, labels), charttpl/chartengine, Functions and host scopes/vnodes. Use affected contracts and source owners; collector product/config design uses collectors-go-design.

1h installs
2
GitHub stars
81.3K
Updated
Nov 4
netdata
Community

collectors-metadata-yaml

Write, review, or explain collector metadata.yaml content and integration-page wording across collector families, including ibm.d docgen sources. Use for field meaning, readability, defaults, discovery, permissions, costs, metrics, setup, and alerts. Generator mechanics belong to integrations-lifecycle; DynCfg form wording belongs to collectors-go-design/config-schema.md.

1h installs
2
GitHub stars
81.3K
Updated
Nov 4