Prometheus SNMP Exporter

SNMP integer enumerations can be represented in Prometheus in two ways via overrides:

• EnumAsInfo: Best for inventory-like, constant data (e.g., device type). The exporter emits human-readable strings in labels instead of numeric values.
• EnumAsStateSet: Best for stateful data you want to alert on (e.g., link status). This generates one time series per possible state value. Use with caution for high-cardinality values.

To keep numeric label values for an enum column, override its type to gauge instead.

modules:
  cisco_device:
    overrides:
      cempMemPoolType:
        type: gauge

The snmp_exporter bridges the gap between SNMP's hierarchical OID tree structure and Prometheus's n-dimensional matrix. It automatically maps SNMP index instances to Prometheus labels.

For example, if an SNMP entry like ifEntry uses ifIndex as an index, the exporter converts this into an ifIndex label in Prometheus. If an entry has multiple index values, each is mapped to a separate label. This allows the exporter to combine disparate OID values into a single Prometheus metric line with multiple descriptive labels.

# Example SNMP walk return:
1.3.6.1.2.1.2.2.1.1.2 = INTEGER: 2         # ifIndex
1.3.6.1.2.1.2.2.1.2.2 = STRING: "eth0"     # ifDescr
1.3.6.1.2.1.31.1.1.1.10.2 = INTEGER: 1000  # ifHCOutOctets

# Resulting Prometheus metric:
ifHCOutOctets{ifAlias="",ifDescr="eth0",ifIndex="2",ifName="eth0"} 1000

The SNMP Exporter configuration file is a YAML file generated by the generator tool. It defines authentication methods (auths) and specific SNMP modules (modules) that dictate how the exporter interacts with SNMP devices.

Key components include:

• auths: Defines SNMP versions and credentials (e.g., community strings for SNMPv2).
• modules: Contains the logic for a specific device or service, including which OID subtrees to walk, which specific OIDs to get, and how to map those values into Prometheus metrics.
• metrics: Defines the mapping of SNMP OIDs to Prometheus metric names, types, and labels.

auths:
  public_v2:
    version: 2
    community: public
modules:
  module_name:
    walk:
      - "IF-MIB::interfaces"
    get:
      - 1.3.6.1.2.1.1.3
    metrics:
      - name: sysUpTime
        oid: 1.3.6.1.2.1.1.3
        type: gauge

The multi-module functionality allows you to retrieve information from several modules in a single scrape request. You can specify multiple modules by either separating them with a comma in the module parameter or by defining the module parameter multiple times.

Note: This implementation does not perform de-duplication of walks between different modules. You can control the concurrency of these walks using the --snmp.module-concurrency flag (default is 1).

### Comma separation
http://localhost:9116/snmp?module=if_mib,arista_sw&target=192.0.0.8

### Multiple params_module
http://localhost:9116/snmp?module=if_mib&module=arista_sw&target=192.0.0.8

### Prometheus Configuration Example
```yaml
  - job_name: 'my'
    params:
      module:
        - if_mib
        - synology
        - ucd_la_table

To avoid namespace collisions in MIB definitions, it is recommended to use a directory-per-device-family structure.

Each device family directory should contain:

1. A mibs directory containing only the MIBs required for that specific family.
2. A logical link to the generator executable.
3. The generator.yml configuration file.

After generating individual snmp.yml files for each family, merge them into a single main snmp.yml file to be used by the snmp_exporter collector.

To generate configurations, the generator requires MIB files. You can obtain them through several methods:

1. Automatic Download: Use the pre-maintained MIBs from the prometheus-community/snmp repository by running make mibs in the generator directory.
2. Vendor Portals: Download MIBs directly from the hardware vendor's support or developer portal.
3. LibreNMS: The librenms/librenms MIB collection is a recommended alternative source.
4. OID Browsing: Use http://oidref.com to browse and identify specific MIBs.

Note: Using MIBs from the prometheus-community/snmp repository is preferred because they are centrally maintained and versioned.

To use the SNMP Mixin, you must install mixtool and jsonnetfmt. If you have a Go development environment configured, you can install them using the following commands:

$ go install github.com/monitoring-mixins/mixtool/cmd/mixtool@latest
$ go install github.com/google/go-jsonnet/cmd/jsonnetfmt@latest

Starting from snmp_exporter v0.23.0, the configuration format has changed. The configuration is no longer a flat list of modules; instead, it is split into separate metric walking/mapping modules and authentication configurations (auths).

To upgrade, you must migrate both your generator configuration and your generated snmp_exporter configuration to this new format. Configuration files for v0.22.0 and earlier are incompatible with v0.23.0 and later.

You can start the exporter as a daemon or directly from the CLI by running the binary:

./snmp_exporter

By default, the exporter listens on port 9116.