[opensourcedex]

snmp_exporter is a free, open source monitoring & observability project written in Go and released under Apache-2.0. It has 2,193 GitHub stars, 749 forks and 103 open issues, and was last pushed 4 days ago. On this registry it ranks #166 of 270 tracked projects in Monitoring & Observability, with 5 head-to-head comparisons available. It gained 14 stars over the last 30 tracked days.

What is snmp_exporter?

SNMP Exporter is the Prometheus project's recommended way to expose SNMP data from network devices in a format Prometheus can ingest, aimed at operators who monitor switches, access points, and routers alongside the rest of their infrastructure.

What it is

SNMP Exporter is a Go program, licensed under Apache-2.0, that bridges two data models: the hierarchical OID trees that SNMP devices expose and the n-dimensional label matrix that Prometheus stores. It lives in the Prometheus exporter ecosystem and replaces the manual work of walking SNMP trees by hand and translating the results into metrics a time-series database can hold.

The concrete problem it solves is index mapping. In SNMP, a value such as ifHCOutOctets is addressed by an OID whose trailing numbers are indices; the same indices appear in parallel subtrees such as ifIndex, ifDescr, ifName, and ifAlias. The exporter reads those subtrees, joins them on the shared index, and emits a single sample such as ifHCOutOctets{ifAlias="",ifDescr="eth0",ifIndex="2",ifName="eth0"} 1000. Multiple index values on one entry become separate Prometheus labels, so ifEntry's ifIndex INDEX becomes the ifIndex label automatically.

Key capabilities

  • Maps SNMP OID trees to Prometheus labels without hand-walking: ifIndex becomes the ifIndex label.
  • Ships a default scrape path using the if_mib module and public_v2 auth, with default transport udp and default port 161.
  • Supports custom transports and ports through the [transport://]host[:port] target syntax, for example tcp on port 1161.
  • Configures auth and modules in an snmp.yml file, with named entries such as public_v2 and my_secure_v3.
  • Accepts optional snmp_context and, for SNMPv3, snmp_engineid URL parameters, where snmp_context overrides context_name in snmp.yml.
  • Handles multi-module requests so a single scrape can cover more than one module definition.
  • Exposes the exporter's own operational metrics on its own endpoint.

Who uses it and how

  • Network and infrastructure teams monitoring switches, access points, and routers with the if_mib module and a read-only community string.
  • Sites with strict security requirements that run SNMPv3 auth modules instead of community strings, since SNMP v1 and v2c send community strings unencrypted.
  • Large fleets: a single instance of the exporter can serve thousands of devices.
  • Operators who need device-specific module and auth pairs, for example walking a ddwrt device through a my_secure_v3 auth entry.
  • Prometheus users who scrape device targets through Prometheus query parameters, which are URL-encoded automatically in the Prometheus configuration file.

Getting started

Binaries are downloadable from the GitHub releases page and need no special installation, after which the exporter runs as a daemon or from the CLI with ./snmp_exporter. A sample systemd unit file is provided at examples/systemd/snmp_exporter.service, and official container images are published as quay.io/prometheus/snmp-exporter and prom/snmp-exporter on Docker Hub.

How it compares

No paid products that this project replaces are listed among the provided facts, and no comparable exporters are named either. On the evidence available, it stands alone in this registry as the Prometheus-ecosystem SNMP exporter.

When to use it — and when not to

A self-hoster must operate the exporter process and maintain the snmp.yml file that defines every auth and module a target relies on, which is real configuration work rather than a turnkey appliance. Teams without Prometheus, or those wanting a managed SNMP polling service with a support contract, should look elsewhere, and anyone forced to keep SNMP v1 or v2c must accept that community strings travel unencrypted and are not treated as secrets. The project shows a healthy footprint at 2,171 stars, 747 forks, and 103 open issues, but the published README is uneven in places, so expect to lean on the sample configs under examples/sample-configs rather than the prose.

project readme (upstream, from github) — read inline

Prometheus SNMP Exporter

Build Status [Docker Repository on Quay][quay] [Docker Pulls][hub]

This exporter is the recommended way to expose SNMP data in a format which Prometheus can ingest.

To simply get started, it's recommended to use the if_mib module with switches, access points, or routers using the public_v2 auth module, which should be a read-only access community on the target device.

Note, community strings in SNMP are not considered secrets, as they are sent unencrypted in SNMP v1 and v2c. For secure access, SNMP v3 is required.

Concepts

While SNMP uses a hierarchical data structure and Prometheus uses an n-dimensional matrix, the two systems map perfectly, and without the need to walk through data by hand. snmp_exporter maps the data for you.

Prometheus

Prometheus is able to map SNMP index instances to labels. For example, the ifEntry specifies an INDEX of ifIndex. This becomes the ifIndex label in Prometheus.

If an SNMP entry has multiple index values, each value is mapped to a separate Prometheus label.

SNMP

SNMP is structured in OID trees, described by MIBs. OID subtrees have the same order across different locations in the tree. The order under 1.3.6.1.2.1.2.2.1.1 (ifIndex) is the same as in 1.3.6.1.2.1.2.2.1.2 (ifDescr), 1.3.6.1.2.1.31.1.1.1.10 (ifHCOutOctets), etc. The numbers are OIDs, the names in parentheses are the names from a MIB, in this case IF-MIB.

Mapping

Given a device with an interface at number 2, a partial snmpwalk return looks like:

1.3.6.1.2.1.2.2.1.1.2 = INTEGER: 2         # ifIndex for '2' is literally just '2'
1.3.6.1.2.1.2.2.1.2.2 = STRING: "eth0"     # ifDescr
1.3.6.1.2.1.31.1.1.1.1.2 = STRING: "eth0"  # IfName
1.3.6.1.2.1.31.1.1.1.10.2 = INTEGER: 1000  # ifHCOutOctets, 1000 bytes
1.3.6.1.2.1.31.1.1.1.18.2 = STRING: ""     # ifAlias

snmp_exporter combines all of this data into:

ifHCOutOctets{ifAlias="",ifDescr="eth0",ifIndex="2",ifName="eth0"} 1000

Scaling

A single instance of snmp_exporter can be run for thousands of devices.

Usage

Installation

Binaries can be downloaded from the Github releases page and need no special installation.

We also provide a sample systemd unit file.

Practical SNMP setup samples (local workstation, network devices, SNMPv2c/v3 auth, and notes on HTTP proxies such as Zscaler) are under examples/sample-configs.

Running

Start snmp_exporter as a daemon or from CLI:

./snmp_exporter

Visit where 192.0.0.8 is the IP or FQDN of the SNMP device to get metrics from. Note that this will use the default transport (udp), default port (161), default auth (public_v2) and default module (if_mib). The auth and module must be defined in the snmp.yml file.

For example, if you have an auth named my_secure_v3 for walking ddwrt, the URL would look like .

To configure a different transport and/or port, use the syntax [transport://]host[:port].

For example, to scrape a device using tcp on port 1161, the URL would look like .

Note that URL encoding should be used for target due to the : and / characters. Prometheus encodes query parameters automatically and manual encoding is not necessary within the Prometheus configuration file.

Metrics concerning the operation of the exporter itself are available at the endpoint .

It is possible to supply an optional snmp_context parameter in the URL, like this:

The snmp_context parameter in the URL would override the context_name parameter in the snmp.yml file.

It is also possible when using SNMPv3 to supply an optional snmp_engineid parameter in the URL, like this:

Multi-Module Handling

The multi-module functionality allows you to specify multiple modules, enabling the retrieval of information from several modules in a single scrape. The concurrency can be specified using the snmp-exporter option --snmp.module-concurrency (the default is 1).

Note: This implementation does not perform any de-duplication of walks between different modules.

There are two ways to specify multiple modules. You can either separate them with a comma or define multiple params_module. The URLs would look like this:

For comma separation:

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

For multiple params_module:

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

Prometheus Example:


  - job_name: 'my'
    params:
      module: 
        - if_mib
        - synology
        - ucd_la_table

Configuration

The default configuration file name is snmp.yml and should not be edited by hand. If you need to change it, see Generating configuration.

The default snmp.yml file covers a variety of common hardware walking them using SNMP v2 GETBULK.

The --config.file parameter can be used multiple times to load more than one file. It also supports glob filename matching, e.g. snmp*.yml.

The --config.expand-environment-variables parameter allows passing environment variables into some fields of the configuration file. The username, password & priv_password fields in the auths section are supported. Defaults to disabled.

Duplicate module or auth entries are treated as invalid and can not be loaded.

Prometheus Configuration

The URL params target, auth, and module can be controlled through relabelling.

Example config:

scrape_configs:
  - job_name: 'snmp'
    static_configs:
      - targets:
        - 192.168.1.2  # SNMP device.
        - switch.local # SNMP device.
        - tcp://192.168.1.3:1161  # SNMP device using TCP transport and custom port.
    metrics_path: /snmp
    params:
      auth: [public_v2]
      module: [if_mib]
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: 127.0.0.1:9116  # The SNMP exporter's real hostname:port.

  # Global exporter-level metrics
  - job_name: 'snmp_exporter'
    static_configs:
      - targets: ['localhost:9116']

You could pass username, password & priv_password via environment variables of your choice in below format. If the variables exist in the environment, they are resolved on the fly, otherwise snmp_exporter will error while loading the config.

This requires the --config.expand-environment-variables flag be set.

auths:
  example_with_envs:
    community: mysecret
    security_level: SomethingReadOnly
    username: ${ARISTA_USERNAME}
    password: ${ARISTA_PASSWORD}
    auth_protocol: SHA256
    priv_protocol: AES
    priv_password: ${ARISTA_PRIV_PASSWORD}

Similarly to blackbox_exporter, snmp_exporter is meant to run on a few central machines and can be thought of like a "Prometheus proxy".

TLS and basic authentication

The SNMP Exporter supports TLS and basic authentication. This enables better control of the various HTTP endpoints.

To use TLS and/or basic authentication, you need to pass a configuration file using the --web.config.file parameter. The format of the file is described in the exporter-toolkit repository.

Note that the TLS and basic authentication settings affect all HTTP endpoints: /metrics for scraping, /snmp for scraping SNMP devices, and the web UI.

Generating configuration

Most use cases should be covered by our default configuration. If you need to generate your own configuration from MIBs, you can use the generator.

Use the generator if you need to customize which objects are walked or use non-public MIBs.

Getting more MIBs

The generator ships with a curated set of open MIBs. For vendor MIBs not included here, the prometheus-community/snmp repository maintains a growing collection of MIBs and ready-to-use generator configs contributed by the community. Clone or download MIBs from that repository and place them in the generator's mibs/ directory, then regenerate snmp.yml with make generate.

If you have vendor MIBs or generator configs for devices not yet represented there, consider contributing them upstream to grow the shared library.

Large counter value handling

In order to provide accurate counters for large Counter64 values, the exporter will automatically wrap the value every 2^53 to avoid 64-bit float rounding. Prometheus handles this gracefully for you and you will not notice any negative effects.

If you need to disable this feature for non-Prometheus systems, use the command line flag --no-snmp.wrap-large-counters.

Once you have it running

It can be opaque to get started with all this, but in our own experience, snmp_exporter is honestly the best way to interact with SNMP. To make it easier for others, please consider contributing back your configurations to us. snmp.yml config should be accompanied by generator config. For your dashboard, alerts, and recording rules, please consider contributing them to .

Frequently asked questions

Is snmp_exporter free to use?

snmp_exporter is open source under the Apache-2.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does snmp_exporter do?

SNMP Exporter for Prometheus

What is snmp_exporter written in?

snmp_exporter is primarily written in Go. Its source is publicly available at https://github.com/prometheus/snmp_exporter, and it has 2,193 GitHub stars.