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.
Access to this feature depends on your subscription level. Requires Infrastructure Pro.
This on-host integration has been contributed to the New Relic GitHub under an MIT license.
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:
- New Relic Infrastructure installed on host.
- Linux distribution compatible with New Relic Infrastructure.
- SNMP monitoring enabled device or application.
- SNMP version 2 or 3.
To install the SNMP integration:
- Follow the instructions for installing an integration, using the file name
- Via the command line, change directory to the integrations folder:
- Create a copy of the sample configuration file by running:
sudo cp snmp-config.yml.sample snmp-config.yml
- Edit the
snmp-config.ymlconfiguration file using the configuration settings.
- Restart the infrastructure agent.
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.
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:
v3: Use SNMP version 3. Default:
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. 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. 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:
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:
You can write different collection files to ease organization and maintenance. See configuration file below for an example.
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.
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
scalarto describe a metric set of SNMP scalar OIDs or
tableto describe a metric set that corresponds to the metrics from an SNMP table.
table, enter the root OID of the table. The integration performs an SNMP walk from this OID to get the table metrics.
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.,
.126.96.36.199.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
table column OIDsas appropriate for the
oid: The OID name to collect, e.g.,
188.8.131.52.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
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.,
184.108.40.206.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: .220.127.116.11.4.1.52032.1.1.1 metric_type: auto - metric_name: rateSample oid: .18.104.22.168.4.1.52032.1.1.2 metric_type: auto - metric_name: displayStringSample oid: .22.214.171.124.4.1.52032.1.1.3 metric_type: auto - name: CityWeatherTable type: table event_type: SNMPSample root_oid: .126.96.36.199.4.1.52032.1.2.1 index: - metric_name: cityName oid: .188.8.131.52.4.1.52032.1.2.1.1.1 metric_type: auto metrics: - metric_name: temperature oid: .184.108.40.206.4.1.52032.1.2.1.1.2 metric_type: gauge - metric_name: humidity oid: .220.127.116.11.4.1.52032.1.2.1.1.3 metric_type: gauge - metric_name: wind oid: .18.104.22.168.4.1.52032.1.2.1.1.4 metric_type: gauge - metric_name: windDirection oid: .22.214.171.124.4.1.52032.1.2.1.1.5 metric_type: gauge inventory: - oid: .126.96.36.199.4.1.52032.1.1.4.0 category: version name: buildNumber
Find and use data
To find your integration data in Infrastructure, go to infrastructure.newrelic.com > Integrations > On-host integrations and select one of the SNMP integration links.
For more on how to find and use your data, see Understand integration 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:
The device name for these metrics.
The SNMP host the metrics are being collected from.
The SNMP port the metrics are being collected from.
The metric set name for these metrics.
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.
- 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.