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
161by 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:-
To poll specific network devices, configure static targets by adding a device list
to the
values.yamlfile for your CXDOT Collector Helm chart. Include the port in every endpoint, such asrouter.example.com:161for the standard SNMP port. The cluster-tier Collector polls static devices, so setSNMP_COMMUNITYin its environment throughclusterCollector.extraEnv. For example:The"${env:SNMP_COMMUNITY}"value reads the community string from theSNMP_COMMUNITYenvironment variable in the Collector environment, so the string doesn’t appear invalues.yaml. In this example,clusterCollector.extraEnvsets that variable from thecommunitykey of a Kubernetes Secret namedsnmp-credentials. Create that Secret in the CXDOT Collector namespace before you applyvalues.yaml, or use your deployment’s secret management to setSNMP_COMMUNITYandIDRAC_SNMP_COMMUNITYin the cluster-tier Collector environment. For SNMP v3, provideauth_passwordandprivacy_passwordthe same way. Setprofilefor 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. -
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 thecommunitykey of thesnmp-credentialsSecret. Because port references resolve only to TCP ports, specify the UDP port (161) directly inendpoint. A device withoutprofileuses thegeneric-deviceprofile. To allow the Collector to read the Secret, add the pod’s namespace toapiServer.metadataServer.secretAllowlistin the Helm values for your CXDOT Collector. -
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:ReplaceNAMESPACEwith the namespace of your CXDOT Collector. -
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.extraVolumesandclusterCollector.extraVolumeMountsvalues. Setprofile_pathsto the mount path, and set each device’sprofileto the name of its custom profile. For example, add the following to thevalues.yamlfile 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. -
Optional: Configure a second integration instance to poll static targets and
annotated targets together. For example, add the following to the
values.yamlfile for your CXDOT Collector Helm chart, and setSNMP_COMMUNITYin the cluster-tier Collector environment as shown in the first step:The baresnmpkey defines the static target instance. Thesnmp/discoveredkey defines a named instance that polls annotated targets.
Validate
To validate the SNMP integration, follow these steps:-
In the
Live Telemetry Analyzer,
add the following filters:
__name__=cxdot.integration.target.healthcxdot.integration.name=snmp
server.addressandserver.portlabels. A device that returns SNMP values reports1, and any other device reports0. -
In
Metrics Explorer,
run the following query:
Confirm that the query reports the interface count of each device that reports
1in the previous step and uses thegeneric-deviceprofile. 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.healthas1but no other metrics: The CXDOT Collector couldn’t load the profile, and its log has afailed to start receivererror 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 ashpe-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:
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.yamlextension. 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 fixedvalue, or reads ascalar_oidand setsmissing_valuefor a device that doesn’t report the OID. Theemptyvalue keeps the attribute with an empty value,omitleaves the attribute out, anderrordrops the device’s data points. The CXDOT Collector addssnmp.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 adescription, aunitin Unified Code for Units of Measure (UCUM) notation, such asByorW, and one ofgaugeorsum. A gauge reports each value as the device reports it. A sum reports a total. It setsmonotonic: truefor a running total that never decreases, such as an SNMP counter, and leavesmonotonicunset for a total that can decrease, such as the power output thathw.power_supply.usagereports. Both setvalue_typetointordouble.scalars: Values that a device reports once, rather than once per table row. Each scalar reads itsoidinto itsmetric.tables: Columns of an SNMP table, which report one value per table row. Each table has aname, thecolumnsto read, and theattributesthat identify each row. Each column reads itsoidinto itsmetric, and the metric’s data point for each row carries every attribute of the table. Instead ofoid, a column can setconstant_valueandpresence_oids, which lists other columns by their OID. The column then reportsconstant_valuefor every row that any of those columns reports, such as1for each power supply that a table lists.
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 from1. For a table indexed by chassis and bay, row0.3has component1equal to0and component2equal to3.indexed_value_prefix: The row index, appended to the prefix this field sets.
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 undercollection.cxdot.integrations.snmp. In a Collector configuration file, place
them under cxdot.integrations.snmp.
Optional settings
-
enabledType: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. -
devicesType:array of object. Optional. Default:[]. Network devices to poll. Each endpoint ishost:port; include port 161 explicitly for the standard SNMP UDP endpoint. -
devices[].auth_passwordType:string. Optional. Authentication password for SNMP v3. Required whensecurity_levelisauth_no_privorauth_priv. -
devices[].auth_typeType:string. Optional. Authentication protocol for SNMP v3. Required whensecurity_levelisauth_no_privorauth_priv. Allowed values:MD5,SHA,SHA224,SHA256,SHA384,SHA512. -
devices[].communityType:string. Optional. Community string for SNMP v1 or v2c. -
devices[].context_nameType:string. Optional. SNMP context name for an SNMP v3 device. -
devices[].endpointType:string. Required. Device address ashost:port, such asrouter.example.com:161. The port is required, including the standard SNMP port161. The Collector polls the address over UDP. -
devices[].namespaceType:string. Optional. Default:default. Minimum length:1. Network Device Monitoring namespace of the device, the first half of itsdevice.id(<namespace>:<host>). Distinguishes devices that share an address in separate networks. -
devices[].privacy_passwordType:string. Optional. Privacy password for private SNMP v3. -
devices[].privacy_typeType:string. Optional. Privacy protocol for SNMP v3. Required whensecurity_levelisauth_priv. Allowed values:DES,AES,AES192,AES192C,AES256,AES256C. -
devices[].profileType:string. Optional. Default:generic-device. Device profile that selects the metrics to collect from this device: the name of a custom profile inprofile_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 ofgeneric-deviceand 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 ofgeneric-deviceand 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 ofgeneric-deviceand 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 ofgeneric-deviceand 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_levelType:string. Optional. Authentication and privacy level for SNMP v3. Required whenversionisv3. Theauth_no_privlevel also requiresauth_typeandauth_password. Theauth_privlevel requires those settings plusprivacy_typeandprivacy_password. Allowed values:no_auth_no_priv,auth_no_priv,auth_priv. -
devices[].userType:string. Optional. User name for SNMP v3. Required whenversionisv3. -
devices[].versionType:string. Required. SNMP protocol version the Collector uses to poll the device. Allowed values:v1,v2c,v3. -
collection_intervalType:duration. Optional. Default:15s. Time between SNMP polls of each device indevices. Annotated devices take their polling interval from their annotations instead. -
timeoutType:duration. Optional. Default:15s. Maximum time for one poll of a device indevices, including retried SNMP requests. The value must not exceedcollection_interval. When less thanrequest_timeoutremains before this deadline, the Collector shortens the wait for the next request to fit the remaining time. -
request_timeoutType:duration. Optional. Default:2s. Time to wait for a response to one SNMP request from a device indevices. The Collector retries a request that gets no response up toretriestimes, within the limit thattimeoutsets. 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. -
retriesType: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_sizeType:integer. Optional. Default:5. Minimum:1. Maximum:60. Maximum number of object identifiers in one SNMP request to a device indevices. 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 withinrequest_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 withintimeout, 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 of1reads 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_repetitionsType: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 indevices. 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 withinrequest_timeout. Annotated devices take this value from their annotations instead. -
profile_pathsType:array of string. Optional. Default:[]. Directories and files that contain custom device profiles. For a device whoseprofileis<name>, the CXDOT Collector reads<name>.yamlfrom 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.