Skip to main content
The SNMP integration requires CXDOT Collector 1.6.0 or greater. Simple Network Management Protocol (SNMP) is a protocol for monitoring network devices. Use the SNMP integration with the CXDOT Collector to collect availability and performance metrics from SNMP devices. The SNMP integration supports SNMP v1, v2c, and v3. The integration polls individual devices. A device profile selects the metrics to collect from each device: the default generic-device profile works with any SNMP device, and vendor profiles collect hardware metrics from specific devices. The devices[].profile setting in Configuration reference lists every built-in profile. For a device that the built-in profiles don’t cover, write a custom device profile. The integration doesn’t scan network address ranges, receive traps, build network topology or device inventories, collect network flow records, or run ping checks.

Supported telemetry types

The SNMP integration supports these telemetry types:

Prerequisites

The SNMP integration has the following prerequisites:
  • Enable SNMP v1, v2c, or v3 on each device.
  • Obtain a community string for SNMP v1 or v2c. For SNMP v3, obtain a user name and the authentication and privacy credentials required by the selected security level.
  • Allow the Collector to reach each device over User Datagram Protocol (UDP) on its SNMP port, which is 161 by default.

Configure

The SNMP integration is enabled by default. You can configure targets either by listing static devices in your Helm values or by annotating SNMP agent pods in your Kubernetes cluster. To configure the SNMP integration, follow these steps:
  1. To poll specific network devices, configure static targets by adding a device list to the values.yaml file for your CXDOT Collector Helm chart. Include the port in every endpoint, such as router.example.com:161 for the standard SNMP port. The cluster-tier Collector polls static devices, so set SNMP_COMMUNITY in its environment through clusterCollector.extraEnv. For example:
    The "${env:SNMP_COMMUNITY}" value reads the community string from the SNMP_COMMUNITY environment variable in the Collector environment, so the string doesn’t appear in values.yaml. In this example, clusterCollector.extraEnv sets that variable from the community key of a Kubernetes Secret named snmp-credentials. Create that Secret in the CXDOT Collector namespace before you apply values.yaml, or use your deployment’s secret management to set SNMP_COMMUNITY and IDRAC_SNMP_COMMUNITY in the cluster-tier Collector environment. For SNMP v3, provide auth_password and privacy_password the same way. Set profile for each device that needs a vendor profile. The integration polls exactly the devices in this list and doesn’t process annotations for this integration instance.
  2. Optional: To poll SNMP agents that run in pods, such as containerized network functions, add a CXDOT integration annotation to the pod template. The annotation key must end with the container name, and its value can reference the community string in a Kubernetes Secret in the same namespace. For example, add the following annotation to your workload:
    The Collector replaces ${target.host} with the pod IP address and ${k8s_secret:snmp-credentials/community} with the community key of the snmp-credentials Secret. Because port references resolve only to TCP ports, specify the UDP port (161) directly in endpoint. A device without profile uses the generic-device profile. To allow the Collector to read the Secret, add the pod’s namespace to apiServer.metadataServer.secretAllowlist in the Helm values for your CXDOT Collector.
  3. Optional: Poll a device with a custom device profile. Write the profile as Custom device profiles describes, then store it in a ConfigMap in the namespace where your CXDOT Collector runs. For example, create a ConfigMap from a profile file named hpe-ilo.yaml:
    Replace NAMESPACE with the namespace of your CXDOT Collector.
  4. Optional: Mount the custom device profiles and select them. The cluster-tier Collector polls static devices, so mount the ConfigMap into it with the chart’s clusterCollector.extraVolumes and clusterCollector.extraVolumeMounts values. Set profile_paths to the mount path, and set each device’s profile to the name of its custom profile. For example, add the following to the values.yaml file for your CXDOT Collector Helm chart:
    The CXDOT Collector reads a custom profile when it starts polling a device. After you change a profile, restart the cluster-tier Collector pods.
  5. Optional: Configure a second integration instance to poll static targets and annotated targets together. For example, add the following to the values.yaml file for your CXDOT Collector Helm chart, and set SNMP_COMMUNITY in the cluster-tier Collector environment as shown in the first step:
    The bare snmp key defines the static target instance. The snmp/discovered key defines a named instance that polls annotated targets.
The CXDOT Collector polls only the devices that you list or annotate. It doesn’t scan address ranges or discover other network devices. For more information, see autodiscovery.

Validate

To validate the SNMP integration, follow these steps:
  1. In the Live Telemetry Analyzer, add the following filters:
    • __name__=cxdot.integration.target.health
    • cxdot.integration.name=snmp
    Confirm that one time series appears for each device, identified by the server.address and server.port labels. A device that returns SNMP values reports 1, and any other device reports 0.
  2. In Metrics Explorer, run the following query:
    Confirm that the query reports the interface count of each device that reports 1 in the previous step and uses the generic-device profile. For a device with another profile, query one of that profile’s metrics instead.

Troubleshooting

  • A device with a custom device profile reports cxdot.integration.target.health as 1 but no other metrics: The CXDOT Collector couldn’t load the profile, and its log has a failed to start receiver error that names the profile file and the problem. Fix the profile, then restart the cluster-tier Collector pods.

Custom device profiles

A custom device profile is a YAML file that defines the metrics to collect from a device, and the SNMP Object Identifier (OID) to read each value from. Name the file after the profile it defines, such as hpe-ilo.yaml for a profile named hpe-ilo. For a static device, a custom profile with the same name as a built-in profile replaces the built-in profile. The CXDOT Collector rejects a profile that contains a field it doesn’t recognize. The following profile collects the thermal condition of a Hewlett Packard Enterprise ProLiant server, and the power output and maximum power output of each of its power supplies:
Name metrics and attributes after OpenTelemetry semantic conventions where they apply, such as hw.power_supply.usage and hw.id, and otherwise under a vendor namespace, such as snmp.hpe.. For a metric that OpenTelemetry defines, also use the type and unit it defines. If you’re moving from another SNMP agent, you can keep the names that agent used so that existing dashboards and alerts keep working. A profile contains these fields:
  • name: Required. The name of the profile, which matches the filename without its .yaml extension. A name contains lowercase letters and digits, separated by single hyphens or underscores.
  • resource_attributes: Attributes that every metric from the device carries, keyed by attribute name. Each attribute sets a fixed value, or reads a scalar_oid and sets missing_value for a device that doesn’t report the OID. The empty value keeps the attribute with an empty value, omit leaves the attribute out, and error drops the device’s data points. The CXDOT Collector adds snmp.profile.name, set to the profile name, so a profile can’t set it.
  • metrics: Every metric the profile collects, keyed by metric name. Each metric has a description, a unit in Unified Code for Units of Measure (UCUM) notation, such as By or W, and one of gauge or sum. A gauge reports each value as the device reports it. A sum reports a total. It sets monotonic: true for a running total that never decreases, such as an SNMP counter, and leaves monotonic unset for a total that can decrease, such as the power output that hw.power_supply.usage reports. Both set value_type to int or double.
  • scalars: Values that a device reports once, rather than once per table row. Each scalar reads its oid into its metric.
  • tables: Columns of an SNMP table, which report one value per table row. Each table has a name, the columns to read, and the attributes that identify each row. Each column reads its oid into its metric, and the metric’s data point for each row carries every attribute of the table. Instead of oid, a column can set constant_value and presence_oids, which lists other columns by their OID. The column then reports constant_value for every row that any of those columns reports, such as 1 for each power supply that a table lists.
A table attribute reads one of the following values for each row:
  • oid: The row’s value in another column, from this table or from another table with the same index.
  • index_component: One dot-separated component of the row index, counting from 1. For a table indexed by chassis and bay, row 0.3 has component 1 equal to 0 and component 2 equal to 3.
  • indexed_value_prefix: The row index, appended to the prefix this field sets.
An attribute can also set value_map to translate each value it reads, such as {"1": up, "2": down}, and must then set unknown_value to keep, omit, or error for a value the map doesn’t list. The error value drops the row’s data point. An attribute that reads an oid can also set format to report an address that a column stores as an OCTET STRING, such as a column of type MacAddress or PhysAddress, or an InetAddress column whose rows are IPv4 or IPv6 addresses. The mac_address format reports a colon-separated Media Access Control (MAC) address, such as d0:94:66:a1:b2:c3, and ip_address reports an IPv4 or IPv6 address, such as 10.0.0.1. A value_map matches the formatted value. A row that reports any other type has no value for the attribute. A column of type IpAddress already reports an address, so leave format off its attribute. When a row has no value for an attribute, the CXDOT Collector drops the row’s data point, unless the attribute sets optional: true, which leaves out only the attribute. Every table needs at least one attribute that isn’t optional, and together the attributes that aren’t optional must be unique for each row. One component of a row index can repeat across rows, so read every component, or read the whole index with indexed_value_prefix, as hw.id does in the example. Rows that share every attribute value produce duplicate data points. A scalar or column can set static_attributes to add fixed attributes to its data points, such as hw.limit_type: max in the example. When several scalars or columns collect the same metric, set different static_attributes on each one, such as direction: receive and direction: transmit, so that their data points stay distinct.

Configuration reference

Configure one SNMP integration instance with the following settings. In Helm values, place these settings under collection.cxdot.integrations.snmp. In a Collector configuration file, place them under cxdot.integrations.snmp.

Optional settings

  • enabled Type: boolean. Optional. Default: true. Whether to enable this configuration block. If true, the Collector runs the integration or capability. If false, the Collector doesn’t run it.
  • devices Type: array of object. Optional. Default: []. Network devices to poll. Each endpoint is host:port; include port 161 explicitly for the standard SNMP UDP endpoint.
  • devices[].auth_password Type: string. Optional. Authentication password for SNMP v3. Required when security_level is auth_no_priv or auth_priv.
  • devices[].auth_type Type: string. Optional. Authentication protocol for SNMP v3. Required when security_level is auth_no_priv or auth_priv. Allowed values: MD5, SHA, SHA224, SHA256, SHA384, SHA512.
  • devices[].community Type: string. Optional. Community string for SNMP v1 or v2c.
  • devices[].context_name Type: string. Optional. SNMP context name for an SNMP v3 device.
  • devices[].endpoint Type: string. Required. Device address as host:port, such as router.example.com:161. The port is required, including the standard SNMP port 161. The Collector polls the address over UDP.
  • devices[].namespace Type: string. Optional. Default: default. Minimum length: 1. Network Device Monitoring namespace of the device, the first half of its device.id (<namespace>:<host>). Distinguishes devices that share an address in separate networks.
  • devices[].privacy_password Type: string. Optional. Privacy password for private SNMP v3.
  • devices[].privacy_type Type: string. Optional. Privacy protocol for SNMP v3. Required when security_level is auth_priv. Allowed values: DES, AES, AES192, AES192C, AES256, AES256C.
  • devices[].profile Type: string. Optional. Default: generic-device. Device profile that selects the metrics to collect from this device: the name of a custom profile in profile_paths, or of a built-in profile. A name contains lowercase letters and digits, separated by single hyphens or underscores. Built-in values:
    • apc-pdu: APC rack power distribution units. Collects power distribution metrics, such as load and status for phases, banks, and outlets, along with temperature and humidity sensor readings.
    • cisco-asr: Cisco ASR routers. Collects the standard network metrics of generic-device and BGP peer statistics, along with CPU and memory usage and hardware health such as power supply, fan, and temperature status.
    • cisco-catalyst: Cisco Catalyst switches. Collects the standard network metrics of generic-device and BGP peer statistics, along with CPU and memory usage, interface queue drops, hardware health such as power supply, fan, and temperature status, and sensor readings.
    • cisco-isr: Cisco ISR routers. Collects the standard network metrics of generic-device and BGP peer statistics, along with CPU and memory usage and hardware health such as power supply, fan, and temperature status.
    • cisco-nexus: Cisco Nexus switches. Collects the standard network metrics of generic-device and BGP peer statistics, along with CPU and memory usage, hardware health such as power supply, fan, and temperature status, and sensor readings.
    • generic-device: Any SNMP device. Collects standard network metrics, such as interface traffic and errors, along with IP, TCP, and UDP statistics.
    • idrac: Dell PowerEdge servers with an integrated Dell Remote Access Controller. Collects hardware health metrics, such as power supply, cooling, temperature, and disk status.
  • devices[].security_level Type: string. Optional. Authentication and privacy level for SNMP v3. Required when version is v3. The auth_no_priv level also requires auth_type and auth_password. The auth_priv level requires those settings plus privacy_type and privacy_password. Allowed values: no_auth_no_priv, auth_no_priv, auth_priv.
  • devices[].user Type: string. Optional. User name for SNMP v3. Required when version is v3.
  • devices[].version Type: string. Required. SNMP protocol version the Collector uses to poll the device. Allowed values: v1, v2c, v3.
  • collection_interval Type: duration. Optional. Default: 15s. Time between SNMP polls of each device in devices. Annotated devices take their polling interval from their annotations instead.
  • timeout Type: duration. Optional. Default: 15s. Maximum time for one poll of a device in devices, including retried SNMP requests. The value must not exceed collection_interval. When less than request_timeout remains before this deadline, the Collector shortens the wait for the next request to fit the remaining time.
  • request_timeout Type: duration. Optional. Default: 2s. Time to wait for a response to one SNMP request from a device in devices. The Collector retries a request that gets no response up to retries times, within the limit that timeout sets. The Collector doesn’t retry a request that reads more table columns at once than the device has answered before. When such a request gets no response, the Collector reads those columns again in smaller requests. Annotated devices take this value from their annotations instead.
  • retries Type: integer. Optional. Default: 3. Minimum: 0. Number of times to retry an SNMP request that timed out before abandoning it. The Collector doesn’t retry a request that reads more table columns at once than the device has answered before, and reads those columns again in smaller requests instead.
  • oid_batch_size Type: integer. Optional. Default: 5. Minimum: 1. Maximum: 60. Maximum number of object identifiers in one SNMP request to a device in devices. A request for table rows from an SNMP v2c or v3 device reads up to this many table columns at once. When the device doesn’t answer such a request within request_timeout, or answers only part of it, the Collector reads the same columns again in smaller requests during the same poll. When the device answers such a request with an error, the Collector reads each of those columns in requests of its own. A poll reads table columns in more than one pass. When the device answers a request at the current size and a pass finishes within timeout, later requests read one more column, up to this value. Requests don’t grow to a size that failed twice since the Collector last cleared its failure counts, which it does every hour. A value of 1 reads each table column in requests of its own, for a device that fails every request for several columns. Annotated devices take this value from their annotations instead.
  • bulk_max_repetitions Type: integer. Optional. Default: 10. Minimum: 1. Maximum: 2147483647. Maximum number of rows of each table column that one SNMP request reads from an SNMP v2c or v3 device in devices. A higher value reads a table in fewer requests, and makes each response larger and slower for the device to build. Lower it for a device that doesn’t answer requests for one column within request_timeout. Annotated devices take this value from their annotations instead.
  • profile_paths Type: array of string. Optional. Default: []. Directories and files that contain custom device profiles. For a device whose profile is <name>, the CXDOT Collector reads <name>.yaml from the first of these paths that has it, before the built-in profiles. A directory is searched for that file, a file is used only when its name matches, and a path that doesn’t exist is skipped.