SNMP monitoring integration (legacy)

Important

Have you tried our new Network Performance Monitoring?

Collect both SNMP and Network Flows to answer the question Is it the network? faster.

Our SNMP integration monitors any application that exposes metrics with SNMP.

Read on to install the integration, and to configure a YAML file to start collecting metrics. This doc also contains sample YAML files to help you get started.

Compatibility and requirements

Our integration is compatible with SNMP version 2 or 3.

Before installing the integration, make sure that you meet the following requirements:

SNMP monitoring enabled device or application.
If SNMP is not running on Kubernetes or Amazon ECS, you must install the infrastructure agent on a Linux OS host that's running SNMP. Otherwise:
- If running on Kubernetes, see these requirements.
- If running on ECS, see these requirements.

Install and activate

To install the SNMP integration, follow the instructions for your environment:

Follow the instructions for installing an integration, using the file name nri-snmp.
Change directory to the integrations folder:
```
cd /etc/newrelic-infra/integrations.d
```

Copy the sample configuration and metrics files:

sudo cp snmp-config.yml.sample snmp-config.yml

sudo cp snmp-metrics.yml.sample snmp-metrics.yml

Edit the snmp-config.yml file as described in the configuration settings.
Edit the snmp-metrics.yml file as described in the metric collection files.
Restart the infrastructure agent.

Download the nri-snmp .MSI installer image from: http://download.newrelic.com/infrastructure_agent/windows/integrations/nri-snmp/nri-snmp-amd64.msi

To install from the Windows command prompt, run:

msiexec.exe /qn /i PATH\TO\nri-snmp-amd64.msi

or double-click the file in Explorer.

In the Integrations directory, C:\Program Files\New Relic\newrelic-infra\integrations.d\, create a copy of the sample configuration and metrics files by running:
```
copy snmp-config.yml.sample snmp-config.yml
```
```
copy snmp-metrics.yml.sample snmp-metrics.yml
```
Edit the snmp-config.yml file as described in the configuration settings.
Edit the snmp-metrics.yml file as described in the metric collection files.
Restart the infrastructure agent.

Additional notes:

Advanced: Integrations are also available in tarball format to allow for install outside of a package manager.
On-host integrations do not automatically update. For best results, regularly update the integration package and the infrastructure agent.

Configuration

Configure the integration

There are several ways to configure the integration, depending on how it was installed:

If enabled via Kubernetes: see Monitor services running on Kubernetes.
If enabled via Amazon ECS: see Monitor services running on ECS.
If installed on-host: edit the config in the integration's YAML config file, snmp-config.yml.

An integration's YAML-format configuration is where you can place required login credentials and configure how data is collected. Which options you change depend on your setup and preference.

The configuration file has common settings applicable to all integrations, such as interval, timeout, inventory_source. To read all about these common settings, refer to our Configuration Format document.

Important

If you are still using our legacy configuration/definition files, please refer to this document for help.

Specific settings related to SNMP are defined using the env section of the configuration file. These settings control the connection to your SNMP instance as well as other security settings and features. The list of valid settings is described in the next section of this document.

SNMP Instance Settings

The SNMP integration collects both metrics and inventory information. The type of metrics collected is determined by the information added to the metrics collection file:

Setting	Description	Default
SNMP_HOST	Hostname or IP where SNMP is running.	localhost
SNMP_PORT	Port on which SNMP is listening.	161
TIMEOUT	Request timeout in seconds.	10
RETRIES	Number of retries in case of timeout.	0
EXPONENTIAL_TIMEOUT	Doubles timeout value in each retry attempt.	false
V3	Use SNMP version 3.	false
COMMUNITY	The SNMP community string. Only for SNMP v2.	public
USERNAME	Security identifier for v3 user. Only for SNMP v3.	N/A
SECURITY_LEVEL	Security level. Only for SNMP v3. Valid options are: noAuthnoPriv authNoPriv authPriv	N/A
AUTH_PROTOCOL	Authentication protocol. Only for SNMP v3. Valid options are: MD5 SHA	MD5
AUTH_PASSPHRASE	Password used to generate the key for authentication. Only for SNMP v3.	N/A
PRIV_PROTOCOL	Encryption protocol. Only for SNMP v3. Valid options are: AES DES	AES
PRIV_PASSPHRASE	Password used to generate the key used to encrypt messages. Only for SNMP v3.	N/A
COLLECTION_FILES	Comma-separated list of full file paths to metric collection definition files.	N/A

The values for these settings can be defined in several ways:

Adding the value directly in the config file. This is the most common way.
Replacing the values from environment variables using the {{}} notation. This requires infrastructure agent v1.14.0+. Read more here or see the example below.
Using secrets management. Use this to protect sensitive information, such as passwords that would be exposed in plain text on the configuration file. For more information, see Secrets management.

Metric collection files

The metrics collection definition files are structured YAML files which tell the integration what metrics to collect. For an example configuration, see the metrics collection file example.

Sample metrics collection file: /etc/newrelic-infra/integrations.d/snmp-metrics.yml.sample

Tip

You can write different collection files to ease organization and maintenance. See configuration file below for an example.

Devices

A collection file collects and organizes metrics. Each file contains a single collect: block which contains one or more devices. For each device, the following keys are defined:

device: The name of the SNMP device from which metrics are being collected. This field is required.
metrics_sets: A list of metric sets that organize metrics to collect from this device. See Metric Sets.
inventory: A list of Object Identifiers (OIDs) to collect from this device and report as inventory. See Inventory.

Metric Sets

Metrics Set represents a logical grouping of SNMP Object Identifiers (OIDs) to get from the SNMP device and report to New Relic. For each metric set, the following keys are defined:

name: The metric set name.
event_type: The event type name for a collection from this metric set.
For tips on naming event types, see Naming tips.
type: The metric set type. Use scalar to describe a metric set of SNMP scalar OIDs or table to describe a metric set that corresponds to the metrics from an SNMP table.
root_oid: If type is a table, enter the root OID of the table. The integration performs an SNMP walk from this OID to get the table metrics.
index: If type is a table, enter one or more table column index OIDs that define the table's row uniquely. For each index OID, the following keys are defined:
- oid: The OID name to collect, e.g., .1.3.6.1.4.1.52032.1.2.1.1.1. This field is required.
- name: The name under which the metric will appear in New Relic. If unspecified, it will default to the OID name.
metrics: List of SNMP OIDs to be collected as part of this metric set. Enter a list of scalar OIDs or table column OIDs as appropriate for the type.
- oid: The OID name to collect, e.g., 1.3.6.1.4.1.52032.1.1.2.0. This field is required.
- metric_name: The name under which the metric will appear in New Relic. If unspecified, it will default to the OID name.
- metric_type: The New Relic metric type to collect this attribute as. Options are gauge, delta, pdelta, rate, prate or attribute. If unspecified, the integration attempts to infer the metric type .

Inventory

Inventory is an array of SNMP Object Identifiers (OIDs) to be collected and reported as inventory items. For each OID, the following keys are defined:

oid: The OID name to collect, e.g., 1.3.6.1.4.1.52032.1.1.4.0. This field is required.
category: The category name under which the inventory item will appear in New Relic. This field is required.
name: The name under which the inventory item will appear in New Relic. This field is required.

Example configurations

This is the basic configuration used to collect SNMP v2 metrics and inventory from your localhost:

integrations:
  - name: nri-snmp
    env:
      SNMP_HOST: localhost
      SNMP_PORT: 161
      COMMUNITY: public
      COLLECTION_FILES: "/etc/newrelic-infra/integrations.d/snmp-metrics.yml"
    interval: 30s
    labels:
      targets: routers
    inventory_source: config/snmp

In this configuration we collect SNMP v2 metrics and inventory using a timeout of 5 seconds, 3 retries and exponential timeout.
With this configuration the integration will make 3 requests with the following timeouts:

1st request: 5 seconds
2nd request: 10 seconds

3rd request: 20 seconds

integrations:
  - name: nri-snmp
    env:
      SNMP_HOST: localhost
      SNMP_PORT: 161
      TIMEOUT: 5
      RETRIES: 3
      EXPONENTIAL_TIMEOUT: true
      COMMUNITY: public
      COLLECTION_FILES: "/etc/newrelic-infra/integrations.d/snmp-metrics.yml"
    interval: 30s
    labels:
      targets: routers
    inventory_source: config/snmp

This is the basic configuration used to collect SNMP v3 metrics and inventory from your localhost:

integrations:
  - name: nri-snmp
    env:
      SNMP_HOST: localhost
      SNMP_PORT: 161
      V3: true
      USERNAME: snmp_user
      SECURITY_LEVEL: authNoPriv
      AUTH_PROTOCOL: SHA
      AUTH_PASSPHRASE: my_auth_password
      PRIV_PROTOCOL: AES
      PRIV_PASSPHRASE: my_priv_password
      COLLECTION_FILES: "/etc/newrelic-infra/integrations.d/snmp-metrics.yml"
    interval: 30s
    labels:
      targets: routers
    inventory_source: config/snmp

collect:
  # Sample dataset for New Relic SNMP test application
- device: NR-SNMP-MIB
  metric_sets:
  - name: ScalarSet
    type: scalar
    event_type: SNMPSample
    metrics:
    - metric_name: counterSample
      oid: .1.3.6.1.4.1.52032.1.1.1
      metric_type: auto
    - metric_name: rateSample
      oid: .1.3.6.1.4.1.52032.1.1.2
      metric_type: auto
    - metric_name: displayStringSample
      oid: .1.3.6.1.4.1.52032.1.1.3
      metric_type: auto
  - name: CityWeatherTable
    type: table
    event_type: SNMPSample
    root_oid: .1.3.6.1.4.1.52032.1.2.1
    index:
    - metric_name: cityName
      oid: .1.3.6.1.4.1.52032.1.2.1.1.1
      metric_type: auto
    metrics:
    - metric_name: temperature
      oid: .1.3.6.1.4.1.52032.1.2.1.1.2
      metric_type: gauge
    - metric_name: humidity
      oid: .1.3.6.1.4.1.52032.1.2.1.1.3
      metric_type: gauge
    - metric_name: wind
      oid: .1.3.6.1.4.1.52032.1.2.1.1.4
      metric_type: gauge
    - metric_name: windDirection
      oid: .1.3.6.1.4.1.52032.1.2.1.1.5
      metric_type: gauge
  inventory:
    - oid: .1.3.6.1.4.1.52032.1.1.4.0
      category: version
      name: buildNumber

For more about the general structure of on-host integration configuration, see Configuration.

Tips for naming your data

Metrics are sent and stored in the form of samples. This is a list of key-value pairs that include metric data and metadata. Each sample is stored as an event in New Relic’s event database.

You are responsible for creating and naming the SNMP data reported to New Relic. For this reason, New Relic strongly recommends following these conventions when naming your event types. To ensure you have a consistent naming scheme:

Use camel case.
Use a name that clearly identifies what data it contains.

Example: MyorgApplicationSample

Recommendation: Use the same naming scheme for similar metrics across different applications.

Find and use data

Data from this service is not reported to an integration dashboard because the samples gathered are generally unique to the device being monitored. You will need to build your own dashboard.

SNMP metrics are attached to the user defined event type specified in the configuration file. You can query this data for troubleshooting purposes or to create custom charts and dashboards.

For more on how to find and use your data, see Understand integration data.

Metric data

The metrics generated by the integration include metadata associated with the collection they are collecting from. This metadata should be used in NRQL queries to filter and facet the data so that the query returns only the data for the desired metric set.

Each event contains the following metadata:

Name	Description
`device`	The device name for these metrics.
`host`	The SNMP host the metrics are being collected from.
`port`	The SNMP port the metrics are being collected from.
`displayName`	The metric set name for these metrics.

Inventory data

The SNMP integration captures the configuration parameters of the SNMP integration. The data is available on the Infrastructure Inventory page, under the config/snmp source. For more about inventory data, see Understand integration data.

Troubleshooting

Troubleshooting tips:

Check the source code

This integration is open source software. That means you can browse its source code and send improvements, or create your own fork and build it.

For more help

If you need more help, check out these support and learning resources:

Browse the Explorers Hub to get help from the community and join in discussions.
Find answers on our sites and learn how to use our support portal.
Run New Relic Diagnostics, our troubleshooting tool for Linux, Windows, and macOS.
Review New Relic's data security and licenses documentation.

Important

Compatibility and requirements

Install and activate

ECS

Kubernetes

Linux

Windows

Configuration

Configure the integration

Important

SNMP Instance Settings

Metric collection files

Tip

Devices

Metric Sets

Inventory

Example configurations

SNMP v2 configuration example

SNMP v2 configuration with retries example

SNMP v3 configuration example

Example metrics collection file

Tips for naming your data

Find and use data

Metric data

Inventory data

Troubleshooting

Search logs for errors

Metrics limit exceeded

Important

Check the source code

For more help

SNMP monitoring integration (legacy)

Important

Compatibility and requirements

Install and activate

Kubernetes

Linux

Windows

Configuration

Configure the integration

Important

SNMP Instance Settings

Metric collection files

Tip

Devices

Metric Sets

Inventory

Example configurations

SNMP v2 configuration example

SNMP v2 configuration with retries example

SNMP v3 configuration example

Example metrics collection file

Tips for naming your data

Find and use data

Metric data

Inventory data

Troubleshooting

Search logs for errors

Metrics limit exceeded

Check the source code

.css-3u3y73{fill:none;stroke:currentColor;stroke-width:2;stroke-linecap:round;stroke-linejoin:round;}.css-1bvd50p{width:1rem;height:1rem;fill:none;stroke:currentColor;stroke-width:2;stroke-linecap:round;stroke-linejoin:round;}For more help

For more help