SNMP monitoring integration

New Relic Infrastructure's Simple Network Management Protocol (SNMP) integration collects data from any device or application that reports metrics via SNMP. This document explains how to install and configure the SNMP integration, and describes the types of metrics collected.

This integration is released as Open Source under the MIT license on GitHub. A change log is also available there for the latest updates.

Access to this feature depends on your subscription level. Requires Infrastructure Pro.

Features

The New Relic SNMP on-host integration allows users to monitor any application that exposes metrics with SNMP. The metrics to be collected are defined in YAML files, which can be configured to collect any subset of metrics desired. A sample collection file is included.

Compatibility and requirements

To use the SNMP integration, ensure your system meets these requirements:

Install

On-host integrations do not automatically update. For best results, you should occasionally update the integration and update the Infrastructure agent.

To install the SNMP integration:

  1. Follow the instructions for installing an integration, using the file name nri-snmp.
  2. Via the command line, change directory to the integrations folder:
    cd /etc/newrelic-infra/integrations.d
  3. Create a copy of the sample configuration file by running:
    sudo cp snmp-config.yml.sample snmp-config.yml
  4. Edit the snmp-config.yml configuration file using the configuration settings.
  5. Restart the infrastructure agent.

It is also possible to manually install integrations from a tarball file. For more information, see Install manually from a tarball archive.

Configure

The SNMP integration defines and collects integration data using two types of YAML files; snmp-config.yml configuration file and metrics collection files.

The snmp-config.yml is where the host connection and collection file information is defined. The file accepts the following arguments. For an example configuration, see the host connection file example.

The snmp-config.yml file accepts the following arguments:

  • snmp_host: The host SNMP is running on. Default: localhost. This field is required.
  • snmp_port: The port SNMP is running on. Default: 161. This field is required.
  • v2: Use SNMP version 2 Default: true.
  • v3: Use SNMP version 3. Default: false.
  • community: The SNMP v2 community string. Default: public. This field is applicable only for SNMP v2.
  • username: The security name that identifies an SNMP v3 user. This field is applicable only for SNMP v3.
  • auth_protocol: The authentication protocol. It can be either MD5 or SHA. Default: MD5. This field is applicable only for SNMP v3.
  • auth_passphrase: The password used to generate the key used for authentication. This field is applicable only for SNMP v3.
  • priv_protocol: The encryption protocol. It can be AES or DES. Default: AES. This field is applicable only for SNMP v3.
  • priv_passphrase: The password used to generate the key used to encrypt messages. This field is applicable only for SNMP v3.
  • collection_files: A comma-separated list of full file paths to the metric collection definition files. Default: /etc/newrelic-infra/integrations.d/snmp-metrics.yml.

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

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: An 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, rate, delta, or attribute. If unspecified, the integration attempts to infer the metric type .

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 file configurations:

Example host connection file
integration_name: com.newrelic.snmp

	instances:
	  - name: snmp
	    command: all_data
	    arguments:
	      snmp_host: localhost
	      snmp_port: 161
              v2: true
	      community: public
	      collection_files: "/etc/newrelic-infra/integrations.d/snmp-metrics.yml"
	
Example metrics collection file

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

    

Find and use data

In New Relic Insights, SNMP data is attached to the user defined event type specified in the configuration file.

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:

Search logs for errors

If you are having trouble with the integration, first enable and search the logs for errors.

Metrics limit exceeded

If you suspect there is a domain sending more than 200 metrics, you can check the log file for this message:

"Metric Set x has n metrics, the current limit is 200. This metric set will not be reported."

If you see this error message, lower the number of metrics being sent for the reported metric set.

For more help

Recommendations for learning more: