SNMP

This article focuses on SNMP data collection.

Terminology¶

• SNMP (Simple network management protocol): A network protocol that is used to collect information about bare metal networking gear.
• OID (Object identifier): A unique ID or address on a device that when polled returns the response code of that value. For example, OIDs are CPU or device fan speed.
• sysOID (System object identifier): A specific address that defines the device type. All devices have a unique ID that defines it. For example, the Meraki base sysOID is 1.3.6.1.4.1.29671.
• MIB (Managed information base): A database or list of all the possible OIDs and their definitions that are related to the MIB. For example, the IF-MIB (interface MIB) contains all the OIDs for descriptive information about a device’s interface.

About SNMP Protocol¶

The SNMP protocol is divided into three versions: v1/v2c/v3, of which:

• V1 and v2c are compatible. Many SNMP devices only offer v2c and v3 versions. v2c version, the best compatibility, many older devices only support this version.
• If the safety requirements are high, choose v3. Security is also the main difference between v3 version and previous versions.

DataKit supports all of the above versions.

Choosing v1/v2c version¶

When selecting the v1/v2c version, a v2_community_string must be provided for authentication when interacting with SNMP devices. Additionally, some devices further subdivide this into read-only community strings and read-write community strings. As the names suggest:

• Read-only community name: The device will only provide internal metrics data to that party, and cannot modify some internal configurations (this is enough for DataKit).
• Read-write community name: The provider has the permission to query the internal metrics data of the equipment and modify some configurations.

Choosing v3 version¶

If you choose v3 version, you need to provide v3_user/v3_auth_protocol/v3_auth_key/v3_priv_protocol/v3_priv_key, etc. Each device is different and should be configured as same as configuration in SNMP device.

Configuration¶

Input Configuration¶

[[inputs.snmp]]
  ## SNMP version: 1, 2 (v2c), or 3.
  snmp_version = 2
  # port = 161

  ## Community string, required for SNMP v1/v2c.
  # v2_community_string = ""

  ## SNMP v3 credentials; authentication and privacy settings must match the device.
  # v3_user              = ""
  # v3_auth_protocol     = "" # MD5/SHA/SHA224/SHA256/SHA384/SHA512 or empty
  # v3_auth_key          = ""
  # v3_priv_protocol     = "" # DES/AES/AES192/AES192C/AES256/AES256C or empty
  # v3_priv_key          = ""
  # v3_context_engine_id = "" # optional
  # v3_context_name      = "" # optional

  ## Namespace used in device identity; cannot be overridden by custom tags.
  # device_namespace = "default"

  ## Device IPs, e.g. ["10.200.10.240"]; can be combined with auto_discovery.
  ## With Zabbix/Prometheus profiles, use their ip_list instead.
  # specific_devices = [""]

  ## Autodiscovery subnets in CIDR notation, e.g. ["10.200.10.0/24"].
  # auto_discovery       = [""]
  # discovery_interval   = "1h"
  # discovery_ignored_ip = [] # Device IPs excluded from autodiscovery.

  ## Consul discovery with Prometheus profiles and module_regexps below.
  # consul_discovery_url = "http://127.0.0.1:8500"
  # consul_token         = "<consul token>"  # Optional.
  # instance_ip_key      = "IP"              # Device IP metadata key (case-sensitive).
  # exporter_ips         = ["<ip1>", "<ip2>"] # Filter by service Address; defaults to [] (all).
  ## TLS settings for Consul.
  # ca_certs             = ["/opt/tls/ca.crt"]
  # cert                 = "/opt/tls/client.crt"
  # cert_key             = "/opt/tls/client.key"
  # insecure_skip_verify = true

  ## Metric collection interval.
  # metric_interval = "10s"

  ## Device object collection; optional topology links follow object_interval.
  ## Topology uses built-in Profiles, preferring LLDP with CDP as a fallback.
  # object_interval  = "5m"
  # collect_topology = false

  ## Collect LLDP neighbors as snmp_lldp logs, independently of object topology.
  ## Enable with collect_topology only if both outputs are needed.
  # enable_lldp   = false
  # lldp_interval = "10m"

  ## Collection concurrency and request sizes.
  # workers              = 100  # Concurrent discovery and collection workers.
  # max_oids             = 1000 # Maximum OIDs allowed per Get call.
  # oid_batch_size       = 5    # OIDs requested per Get/GetBulk call.
  # bulk_max_repetitions = 10   # Maximum repetitions per GetBulk call.

  ## Enable election.
  # election = true

  ## Optional filtering for built-in Profiles; collect data containing any listed field.
  # enable_picking_data = true # Defaults to false (collect all metric data).
  # status = ["sysUpTimeInstance", "tcpCurrEstab", "ifAdminStatus", "ifOperStatus", "cswSwitchState"]
  # speed = ["ifHCInOctets", "ifHCInOctetsRate", "ifHCOutOctets", "ifHCOutOctetsRate", "ifHighSpeed", "ifSpeed", "ifBandwidthInUsageRate", "ifBandwidthOutUsageRate"]
  # cpu = ["cpuUsage"]
  # mem = ["memoryUsed", "memoryUsage", "memoryFree"]
  # extra = []

  ## Drop tags by exact key or regular expression.
  # tags_ignore        = ["Key1","key2"]
  # tags_ignore_regexp = ["^key1$","^(a|bc|de)$"]

  ## Zabbix profiles.
  # [[inputs.snmp.zabbix_profiles]]
    ## Full path or file name under ./conf.d/snmp/userprofiles/ (.yaml, .yml, or .xml).
    # profile_name = "xxx.yaml"
    ## Optional device IPs.
    # ip_list = ["ip1", "ip2"]
    ## Recommended device classes:
    ## access_point, firewall, load_balancer, pdu, printer, router, sd_wan, sensor, server, storage, switch, ups, wlc, net_device
    # class = "server"

  # [[inputs.snmp.zabbix_profiles]]
    # profile_name = "yyy.xml"
    # ip_list = ["ip3", "ip4"]
    # class = "switch"

  # ...

  ## Prometheus snmp_exporter profiles; split files by device class if needed.
  # [[inputs.snmp.prom_profiles]]
    # profile_name = "xxx.yml"
    ## ip_list applies only to single-module profiles.
    # ip_list = ["ip1", "ip2"]
    # class = "net_device"

  # ...

  ## Map Consul services to Prometheus modules; metadata keys are case-sensitive.
  # [[inputs.snmp.module_regexps]]
    # module = "vpn5"
    ## All regular expressions must match (AND).
    # step_regexps = [["type", "vpn"],["isp", "CT"]]

  # [[inputs.snmp.module_regexps]]
    # module = "switch"
    # step_regexps = [["type", "switch"]]

  # ...

  ## Field and tag key mappings for Zabbix/Prometheus profiles. Do NOT edit existing entries.
  [inputs.snmp.key_mapping]
    CNTLR_NAME = "unit_name"
    DISK_NAME = "unit_name"
    ENT_CLASS = "unit_class"
    ENT_NAME = "unit_name"
    FAN_DESCR = "unit_desc"
    IF_OPERS_TATUS = "unit_status"
    IFADMINSTATUS = "unit_status"
    IFALIAS = "unit_alias"
    IFDESCR = "unit_desc"
    IFNAME = "unit_name"
    IFOPERSTATUS = "unit_status"
    IFTYPE = "unit_type"
    PSU_DESCR = "unit_desc"
    SENSOR_LOCALE = "unit_locale"
    SNMPINDEX = "snmp_index"
    SNMPVALUE = "snmp_value"
    TYPE = "unit_type"
    SENSOR_INFO = "unit_desc"
    ## Add custom mappings below.
    # dev_fan_speed = "fanSpeed"
    # dev_disk_size = "diskTotal"

  ## OID-to-key mappings for Zabbix/Prometheus profiles. Do NOT edit existing entries.
  [inputs.snmp.oid_keys]
    "1.3.6.1.2.1.1.3.0" = "netUptime"
    "1.3.6.1.2.1.25.1.1.0" = "uptime"
    "1.3.6.1.2.1.2.2.1.13" = "ifInDiscards"
    "1.3.6.1.2.1.2.2.1.14" = "ifInErrors"
    "1.3.6.1.2.1.31.1.1.1.6" = "ifHCInOctets"
    "1.3.6.1.2.1.2.2.1.19" = "ifOutDiscards"
    "1.3.6.1.2.1.2.2.1.20" = "ifOutErrors"
    "1.3.6.1.2.1.31.1.1.1.10" = "ifHCOutOctets"
    "1.3.6.1.2.1.31.1.1.1.15" = "ifHighSpeed"
    "1.3.6.1.2.1.2.2.1.8" = "ifNetStatus"
    ## Add custom OID-to-key mappings below.

  # [inputs.snmp.tags]
    # tag1 = "val1"
    # tag2 = "val2"

  ## Enable to receive device traps and report them as logs.
  [inputs.snmp.traps]
    enable = false
    bind_host = "0.0.0.0"
    port = 9162
    stop_timeout = 3    # Shutdown timeout in seconds.
    # source = "traps"

sudo datakit debug --input-conf /usr/local/datakit/conf.d/snmp/snmp.conf

Multiple configuration formats¶

Built-in Profile Format¶

A built-in Profile uses YAML to describe the device sysObjectID, OIDs to collect, metric types, tags, and metadata.

This format is suitable when:

• The built-in Profiles do not cover the device model;
• Vendor-specific MIB metrics need to be added;
• The device returns numeric values as String/OCTET STRING;
• Device metadata needs to be added.

Profile YAML is different from Zabbix Template and Prometheus snmp_exporter formats. Their fields cannot be mixed.

Prepare OID Information¶

Before writing a Profile, obtain the device MIB/OID manual and use snmpget or snmpwalk to verify the actual values returned by the device. At minimum, confirm:

• The sysObjectID, which is the value of OID 1.3.6.1.2.1.1.2.0;
• Whether each metric is a scalar or a table column;
• The metric OID, data type, meaning, and unit;
• The complete String/OCTET STRING value format;
• The table index and tag columns that distinguish each row.

Add a Profile¶

DataKit releases built-in Profiles to conf.d/snmp/profiles/ under the installation directory, and this directory may be overwritten during startup or upgrade. To add a site-specific Profile or override a built-in Profile, place the YAML file in conf.d/snmp/extra_profiles/. DataKit merges both directories during the default Profile loading flow, with extra_profiles taking precedence.

Example:

/usr/local/datakit/conf.d/snmp/extra_profiles/vendor-router.yaml

File requirements:

• The extension must be .yaml;
• The file name must not start with _; files starting with _ are inheritance templates only;
• If a file has the same name as a built-in Profile, the file in extra_profiles takes precedence; to keep the built-in content, extend the same file name in the supplemental Profile;
• Different file names should not use the same sysobjectid, otherwise automatic matching treats them as duplicate Profiles.

Restart DataKit after adding the file.

Basic Structure¶

extends:
  - generic-router.yaml

sysobjectid: 1.3.6.1.4.1.<enterprise_id>.<product_id>

device:
  vendor: vendor_name

static_tags:
  - "device_type:router"

metadata:
  device:
    fields:
      model:
        symbol:
          OID: 1.3.6.1.4.1.<enterprise_id>.1.1.0
          name: vendorModel

metric_tags:
  - symbol:
      OID: 1.3.6.1.2.1.1.5.0
      name: sysName
    tag: snmp_host

metrics:
  - MIB: VENDOR-MIB
    symbol:
      OID: 1.3.6.1.4.1.<enterprise_id>.2.1.0
      name: vendor.system.cpu_usage
      metric_type: gauge

Root-level fields:

MIB and table improve YAML readability but do not determine which SNMP queries are executed. DataKit queries the OIDs configured in symbol, symbols, metric_tags, and metadata.

Inherit Profiles¶

Use extends to inherit existing Profiles. Metrics, tags, and metadata from inherited Profiles are merged into the current Profile, reducing duplicate standard MIB configuration.

extends:
  - _base.yaml
  - _generic-if.yaml

Built-in Profiles are located in conf.d/snmp/profiles/, and site-specific supplemental Profiles are located in conf.d/snmp/extra_profiles/. Before writing YAML, check the files starting with _ in the built-in directory and select reusable templates provided by the current DataKit version. Common templates include:

Files starting with _ are inheritance templates and do not independently participate in automatic sysObjectID matching. A complete Profile without the _ prefix can also be inherited. For example:

extends:
  - generic-router.yaml

generic-router.yaml already inherits _base.yaml, _generic-if.yaml, _generic-ip.yaml, _generic-tcp.yaml, _generic-udp.yaml, and _generic-ospf.yaml. Do not inherit these files again after inheriting generic-router.yaml.

For a Cisco device, inherit the common Cisco template and add device-specific metrics:

extends:
  - _base.yaml
  - _cisco-generic.yaml

sysobjectid: 1.3.6.1.4.1.9.1.<product_id>

Notes:

• File names in extends are resolved from conf.d/snmp/extra_profiles/ first, then from conf.d/snmp/profiles/;
• A same-name Profile in extra_profiles can extend its own file name to inherit the built-in Profile with the same name;
• Multiple and nested inheritance are supported, but circular inheritance is not allowed;
• Metrics, dynamic tags, and static tags are appended during merging;
• A metadata field defined by the current Profile is not overwritten by inherited content;
• Do not inherit a template that an upper-level Profile already includes, or duplicate metrics and tags may be generated;
• More inherited modules result in more OID queries. Select modules according to the MIBs supported by the device.

sysObjectID Matching¶

Exact match:

sysobjectid: 1.3.6.1.4.1.99999.1.2

Wildcard match:

sysobjectid: 1.3.6.1.4.1.99999.*

Match multiple models:

sysobjectid:
  - 1.3.6.1.4.1.99999.1.*
  - 1.3.6.1.4.1.99999.2.*

When multiple Profiles match, DataKit selects the more specific rule. Different Profiles must not define the same sysobjectid. Use vendor- or product-specific values whenever possible to prevent a broad rule from matching unrelated devices.

For example, 1.3.6.1.4.1.8072.3.2.10 is a common Net-SNMP Linux sysObjectID, not a value exclusive to a specific device vendor.

Scalar Metrics¶

A scalar has one value and is defined with symbol. Scalar OIDs usually end with .0:

metrics:
  - MIB: VENDOR-SYSTEM-MIB
    symbol:
      OID: 1.3.6.1.4.1.99999.1.2.0
      name: vendor.system.cpu_usage
      metric_type: gauge

Table Metrics¶

A table contains multiple rows. Use symbols to define the columns to collect and metric_tags to distinguish each row:

metrics:
  - MIB: IF-MIB
    table:
      OID: 1.3.6.1.2.1.2.2
      name: ifTable
    symbols:
      - OID: 1.3.6.1.2.1.2.2.1.10
        name: vendor.interface.in_octets
        metric_type: monotonic_count
      - OID: 1.3.6.1.2.1.2.2.1.16
        name: vendor.interface.out_octets
        metric_type: monotonic_count
    metric_tags:
      - symbol:
          OID: 1.3.6.1.2.1.31.1.1.1.1
          name: ifName
        tag: interface

A table must have at least one tag that distinguishes its rows. Otherwise, multiple rows may have identical tags and only one row will be retained.

Tags can also be generated from the OID row index. index starts at 1:

metric_tags:
  - index: 1
    tag: disk_index

For a composite row index of 3.24, the following configuration generates slot:3 and port:24:

metric_tags:
  - index: 1
    tag: slot
  - index: 2
    tag: port

Convert String Values to Numbers¶

Metric field values must be numeric. A numeric String/OCTET STRING such as "52.20" can be converted directly. If the value contains a unit or other characters, use extract_value to extract the first capture group.

For a device value of STRING: "5331MB":

- OID: 1.3.6.1.4.1.99999.2.1.4
  name: vendor.disk.used
  extract_value: '^([0-9]+[.]?[0-9]*)MB$'
  metric_type: gauge

For a device value of STRING: "52.20%":

- OID: 1.3.6.1.4.1.99999.2.1.6
  name: vendor.disk.used_percent
  extract_value: '^([0-9]+[.]?[0-9]*)%?$'
  metric_type: gauge

Notes:

• The regular expression must contain at least one capture group. DataKit only uses the first group;
• Enclose regular expressions in single quotes and use ^ and $ to match the complete value;
• Go regular expression syntax is used. Lookahead and lookbehind are not supported;
• A value is not reported when the regular expression does not match;
• Plain text String values should be configured as tags or metadata instead of time-series metric values.

Metric Types and Value Scaling¶

The following metric_type values are recommended for custom Profiles:

metric_type can be configured on an individual symbol, or at the table metric root to apply to all its symbols. A value configured on an individual symbol takes precedence. When omitted, DataKit infers the type from the SNMP return type and uses gauge when it cannot infer a type.

Use scale_factor for numeric conversion. For example, if the device returns 5234 but the actual value is 52.34%:

- OID: 1.3.6.1.4.1.99999.1.2.0
  name: vendor.system.cpu_usage
  scale_factor: 0.01
  metric_type: gauge

scale_factor only affects the final reported metric value. For a String metric, use extract_value first and then apply scale_factor.

Report a Fixed Value of 1¶

When a table represents a set of entities but has no suitable numeric column, use constant_value_one to report a fixed value of 1 for every row:

metrics:
  - MIB: VENDOR-DISK-MIB
    table:
      OID: 1.3.6.1.4.1.99999.3.1
      name: vendorDiskTable
    symbols:
      - name: vendor.disk.present
        constant_value_one: true
    metric_tags:
      - symbol:
          OID: 1.3.6.1.4.1.99999.3.1.1
          name: diskName
        tag: disk_name
      - symbol:
          OID: 1.3.6.1.4.1.99999.3.1.2
          name: diskState
        tag: disk_state
        mapping:
          1: normal
          2: warning
          3: failed

constant_value_one can only be used in table symbols, not scalar metrics. Do not configure an OID for this symbol, but configure its name and at least one OID-based metric_tags.symbol without index_transform, so DataKit can discover the table rows.

Tags¶

Use root-level static_tags to add fixed tags:

static_tags:
  - "device_type:router"
  - "environment:production"

Root-level metric_tags generate dynamic tags from scalar OIDs and apply them to device metrics:

metric_tags:
  - symbol:
      OID: 1.3.6.1.2.1.1.5.0
      name: sysName
    tag: snmp_host

Within a table, metric_tags can use mapping to convert raw values into readable tag values:

metric_tags:
  - symbol:
      OID: 1.3.6.1.4.1.99999.3.1.2
      name: diskState
    tag: disk_state
    mapping:
      1: normal
      2: warning
      3: failed

Use match and tags to generate multiple tags from one table column value:

metric_tags:
  - symbol:
      OID: 1.3.6.1.4.1.99999.4.1.2
      name: interfaceLabel
    match: '^([A-Za-z]+)-([0-9]+)$'
    tags:
      interface_type: '$1'
      interface_number: '$2'

For a raw value of ethernet-12, this generates interface_type:ethernet and interface_number:12. A non-empty tags mapping is required when match is configured. No tag is generated when the regular expression does not match.

When the metric table and tag source table use different index structures, use index_transform to extract and rebuild the index:

metric_tags:
  - symbol:
      OID: 1.3.6.1.4.1.99999.5.1.2
      name: parentName
    index_transform:
      - start: 1
        end: 2
      - start: 6
        end: 7
    tag: parent_name

For a current index of 1.2.3.4.5.6.7.8, the transformed index is 2.3.7.8. Both start and end are zero-based, and the value at end is included. This option is only needed for cross-table association.

Metadata¶

A custom Profile can add device metadata through metadata.device. Supported fields are name, description, sys_object_id, location, serial_number, vendor, version, product_name, model, os_name, os_version, os_hostname, and type. A field can obtain its value from a scalar OID or use a fixed value:

metadata:
  device:
    fields:
      name:
        symbol:
          OID: 1.3.6.1.2.1.1.5.0
          name: sysName
      serial_number:
        symbol:
          OID: 1.3.6.1.4.1.99999.1.1.0
          name: vendorSerialNumber
      vendor:
        value: vendor_name
      type:
        value: router

A field can define multiple candidate symbols. DataKit uses the first OID that returns a value. Use match_pattern and match_value to extract or replace text:

metadata:
  device:
    fields:
      model:
        symbols:
          - OID: 1.3.6.1.4.1.99999.1.2.0
            name: vendorModel
          - OID: 1.3.6.1.2.1.1.1.0
            name: sysDescr
            match_pattern: 'Model[=: ]+([A-Za-z0-9._-]+)'
            match_value: '$1'

When match_value is omitted, the first capture group $1 is used. If the regular expression does not match, DataKit tries the next candidate symbol.

After inheriting _generic-if.yaml or generic-router.yaml, common interface metadata is already included and usually does not need to be configured again.

Metric Naming¶

Metric names are converted before reporting according to these rules:

1. If the name contains an underscore _, all dots . are replaced with underscores _;
2. If the name contains no underscore _, dots . are removed and the first letter after each dot is converted to uppercase;
3. A name without dots . remains unchanged.

Examples:

The same conversion applies to tag keys but not tag values.

Use one naming style consistently within a Profile. A dot-separated name without underscores, such as vendor.disk.used, or an underscore name without dots, such as vendor_disk_used, can be used. Avoid mixing dots and underscores because all dots will then be converted to underscores. Existing built-in Profiles commonly use names such as huawei.hwEntityTemperature, which is reported as huaweiHwEntityTemperature.

Complete Example¶

The following example inherits common router metrics and collects device metadata, a numeric scalar, String disk metrics, and an entity-presence metric:

extends:
  - generic-router.yaml

sysobjectid: 1.3.6.1.4.1.99999.1.2

device:
  vendor: vendor_name

metadata:
  device:
    fields:
      model:
        symbol:
          OID: 1.3.6.1.4.1.99999.1.1.0
          name: vendorModel

metrics:
  - MIB: VENDOR-SYSTEM-MIB
    symbol:
      OID: 1.3.6.1.4.1.99999.1.2.0
      name: vendor.system.cpu_usage
      metric_type: gauge

  - MIB: VENDOR-DISK-MIB
    table:
      OID: 1.3.6.1.4.1.99999.2.1
      name: vendorDiskTable
    symbols:
      - OID: 1.3.6.1.4.1.99999.2.1.4
        name: vendor.disk.used
        extract_value: '^([0-9]+[.]?[0-9]*)MB$'
        metric_type: gauge
      - OID: 1.3.6.1.4.1.99999.2.1.6
        name: vendor.disk.used_percent
        extract_value: '^([0-9]+[.]?[0-9]*)%?$'
        metric_type: gauge
      - name: vendor.disk.present
        constant_value_one: true
    metric_tags:
      - index: 1
        tag: disk_index
      - symbol:
          OID: 1.3.6.1.4.1.99999.2.1.2
          name: diskName
        tag: disk_name

Validation and Troubleshooting¶

Common issues:

• Profile not matched: Check the device's actual sysObjectID, wildcard range, and whether a more specific matching rule exists;
• YAML not loaded: Check the file extension, file name, indentation, and Profile validation errors in the DataKit logs;
• No OID data: Run snmpget or snmpwalk with the same SNMP version and authentication settings as DataKit;
• String metric not reported: Check that extract_value contains a capture group and matches the complete actual value;
• Only one table row reported: Add metric_tags that distinguish every row;
• Metric skipped: Confirm that the final value can be converted to a number, and check metric_type and scale_factor.

Zabbix format¶

• Config

  [[inputs.snmp.zabbix_profiles]]
    profile_name = "xxx.yaml"
    ip_list = ["ip1", "ip2"]
    class = "server"

  [[inputs.snmp.zabbix_profiles]]
    profile_name = "yyy.xml"
    ip_list = ["ip3", "ip4"]
    class = "switch"

  # ...

profile_name can be full path file name or only file name. If only file name, the path is ./conf.d/snmp/userprofiles/

profile_name can from Zabbix official, or from community .

You can modify the yaml or xml.

• AutoDiscovery

  • Automatic discovery matches the collection rules in the imported multiple yaml configurations and performs collection.

  • Please try to configure according to class C. Configuring class B may be slower.

  • If automatic discovery fails to match yaml, it is because these yaml does not contain the manufacturer's signature code of the collected device.

    • Add an oid message to the items of yaml to guide the automatic matching process.

    zabbix_export:
      templates:
      - items:
        - snmp_oid: 1.3.6.1.4.1.2011.5.2.1.1.1.1.6.114.97.100.105.117.115.0.0.0.0
    

    • The oid to be added is obtained by executing the following command. .0.0.0.0 is added at the end to prevent the generation of useless indicators.

    $ snmpwalk -v 2c -c public <ip> 1.3.6.1.2.1.1.2.0
    iso.3.6.1.2.1.1.2.0 = OID: iso.3.6.1.4.1.2011.2.240.12
    
    $ snmpgetnext -v 2c -c public <ip> 1.3.6.1.4.1.2011.2.240.12
    iso.3.6.1.4.1.2011.5.2.1.1.1.1.6.114.97.100.105.117.115 = STRING: "radius"
    

Prometheus format¶

• Config

    [[inputs.snmp.prom_profiles]]
      profile_name = "xxx.yml"
      ip_list = ["ip1", "ip2"]
      class = "server"
  
    [[inputs.snmp.prom_profiles]]
      profile_name = "yyy.yml"
      ip_list = ["ip3", "ip4"]
      class = "firewall"
  
    # ...
  

  Please refer to the snmp.yml file of Prometheus snmp_exporter for the profile. It is recommended to split module of different classes into different .yml configurations.

  Prometheus profile allows you to configure a separate community name for a module. This community name takes precedence over the community name configured for the input.

  switch:
    walk:
    ...
    get:
    ...
    metrics:
    ...
    auth:
      community: xxxxxxxxxxxx
  

• AutoDiscovery

The SNMP collector can discovery instance through Consul service, and the service injection format can be found on prom official website。

Configure SNMP device¶

When SNMP devices are in the default, the general SNMP protocol is closed, you need to enter the management interface to open manually. At the same time, it is necessary to select the protocol version and fill in the corresponding information according to the actual situation.

# Applicable v2c version
snmpwalk -O bentU -v 2c -c [community string] [SNMP_DEVICE_IP] 1.3.6
# Applicable v3 version
snmpwalk -v 3 -u user -l authPriv -a sha -A [AUTH_PASSWORD] -x aes -X [ENCRYPT_PASSWORD] [SNMP_DEVICE_IP] 1.3.6

sudo yum install net-snmp net-snmp-utils # CentOS
sudo apt–get install snmp                # Ubuntu

SNMPv3 Example¶

We take an snmpd service on Linux as an example to demonstrate how to collecting SNMPv3 data.

• On an Ubuntu machine, install the snmpd service:

  sudo apt install snmp snmpd libsnmp-dev
  

• Prepare a simple snmpd.conf configuration as follows:

  my-snmpd.conf

  # Set the UDP 161 port
  agentaddress udp:161
  
  # Define a user and related authentication configurations
  createUser snmpv3user1 SHA "authPassAgent1" AES "privPassAgent1"
  
  # Grant user access permissions (rouser: read-only, rwuser: read-write)
  rouser snmpv3user1 priv .1.3.6
  

• Stop the snmpd service first, then manually start the snmpd process:

  sudo /usr/sbin/snmpd -f -Lo -C \
    -p x.pid -Ddump,usm,acl,header,context,pdu,snmpv3 \
    -c my-snmpd.conf
  

• Use the snmpwalk command to test, which is expected to output extensive OID device information:

  snmpwalk -v3 -l authPriv \
    -u snmpv3user1 \
    -a SHA \
    -A "authPassAgent1" \
    -x AES \
    -X "privPassAgent1" \
    udp:127.0.0.1:161 .1.3.6.1.2.1.1
  

• If the snmpwalk command succeeds, enable the collector on DataKit to collect metrics via SNMPv3. The key configuration is as follows:

  conf.d/snmp/snmp.conf

  specific_devices = ["127.0.0.1"] # Do not use "localhost" here
  snmp_version     = 3
  port             = 161
  
  v3_user                = "snmpv3user1"
  v3_auth_protocol       = "SHA" # MD5/SHA/SHA224/SHA256/SHA384/SHA512 or empty
  v3_auth_key            = "authPassAgent1"
  v3_priv_protocol       = "AES" # DES/AES/AES192/AES192C/AES256/AES256C or empty
  v3_priv_key            = "privPassAgent1"
  # v3_context_engine_id = "" # Optional
  # v3_context_name      = "" # Optional
  

SNMP Trap Configuration¶

SNMP Trap logging is disabled by default. When enabled, Trap events sent by devices are reported as logs, which may increase log usage and costs.

Update [inputs.snmp.traps] in snmp.conf, then restart DataKit:

[inputs.snmp.traps]
  enable = true
  bind_host = "0.0.0.0"
  port = 9162
  stop_timeout = 3
  # source = "traps"

• bind_host: Local listening address; 0.0.0.0 listens on all IPv4 addresses. port: Trap UDP listening port, defaulting to 9162.
• stop_timeout: Timeout for stopping the Trap service, in seconds. Defaults to 5 when omitted or set to 0.
• source: Log source, defaulting to traps.

Enable Trap sending on the device, set its destination to a reachable DataKit IP and listening port, and allow UDP traffic.

Traps reuse the SNMP credentials from the same [[inputs.snmp]] instance. Configure matching credentials on the device.

To disable Trap logging, set enable = false and restart DataKit.

LLDP Network Topology Collection¶

DataKit supports collecting LLDP (Link Layer Discovery Protocol) neighbor information from network devices via SNMP protocol for automatic network topology construction.

What is LLDP¶

LLDP is a standardized link-layer protocol that allows network devices (such as switches and routers) to broadcast their identity and capability information to directly connected neighbor devices. By collecting LLDP data, you can:

• Automatically discover network topology relationships
• Understand physical connection status between devices
• Obtain neighbor device port, hostname, system description, and other information
• Build visualized network topology diagrams

Enable LLDP Collection¶

The recommended mode attaches LLDP neighbors to the snmp_object object as link metadata:

[[inputs.snmp]]
  ## Collect LLDP neighbors with object data and write topology links to
  ## the links field of snmp_object
  collect_topology = true

collect_topology is disabled by default. When enabled, DataKit queries the LLDP/CDP MIB during each object collection cycle and writes local-device, local-interface, remote-device, and remote-interface link metadata to the links field of snmp_object as a JSON array. LLDP is preferred when LLDP links are available; CDP is used only as a fallback.

This option only applies to the built-in Profile collection mode that reports snmp_object; it does not apply to snmp_<class> custom objects generated by user Profiles.

links Field¶

The following is an annotated decoded LLDP example from the links field. Lines beginning with // describe the fields:

[
  {
    // Topology neighbor-record ID on the local device.
    // LLDP format: <device_namespace>:<management IP>:<lldpRemLocalPortNum>.<lldpRemIndex>;
    // CDP format: <device_namespace>:<management IP>:<cdpCacheIfIndex>.<cdpCacheDeviceIndex>.
    "id": "default:192.0.2.10:7.1",
    // Neighbor data source: lldp or cdp.
    "source_type": "lldp",
    // Collection integration name. It is currently fixed to snmp.
    "integration": "snmp",
    // Local link endpoint directly collected by DataKit.
    "local": {
      // Local device.
      "device": {
        // Resolved local device ID in the form <device_namespace>:<management IP>.
        "resolved_id": "default:192.0.2.10"
      },
      // Local interface.
      "interface": {
        // Resolved local interface ID in the form <local.device.resolved_id>:<ifIndex>.
        // It can be absent when an LLDP local port cannot be resolved to an IF-MIB interface.
        "resolved_id": "default:192.0.2.10:12",
        // LLDP lldpLocPortId; currently an empty string for a CDP link.
        "id": "82:a5:6e:a5:c9:01",
        // Local port ID type converted from lldpLocPortIdSubtype; usually absent from a CDP link.
        "id_type": "mac_address"
      }
    },
    // Remote endpoint discovered by the neighbor protocol.
    // It does not imply that DataKit directly collects the remote device.
    "remote": {
      // Remote device.
      "device": {
        // LLDP lldpRemChassisId or CDP cdpCacheDeviceId.
        "id": "01:00:00:00:01:02",
        // LLDP chassis ID type converted from lldpRemChassisIdSubtype; usually absent from a CDP link.
        "id_type": "mac_address",
        // LLDP lldpRemSysName or CDP cdpCacheSysName.
        "name": "switch-b",
        // LLDP lldpRemSysDesc or CDP cdpCacheVersion.
        "description": "remote switch",
        // Remote management IP. LLDP derives it from the remote-management-address table index;
        // CDP tries the primary, secondary, and cached management addresses. It is absent if not advertised.
        "ip_address": "10.250.0.6"
      },
      // Remote interface.
      "interface": {
        // LLDP lldpRemPortId or CDP cdpCacheDevicePort.
        "id": "Ethernet1/7",
        // LLDP remote port ID type; fixed to interface_name for CDP.
        "id_type": "interface_name",
        // LLDP lldpRemPortDesc; usually absent from a CDP link.
        "description": "remote uplink"
      }
    }
  }
]

LLDP device and port identifier types can include mac_address, network_address, interface_name, interface_alias, port_component, and local. Except for structurally required fields, names, descriptions, management IPs, and unresolved object IDs can be absent from the result.

The existing enable_lldp option is an independent LLDP collection path. It runs on lldp_interval and reports snmp_lldp logging data, and is retained for compatibility with existing configurations:

[[inputs.snmp]]
  enable_lldp = true
  lldp_interval = "10m"

The two options are independent and both default to false. Normally, enable only the output you need. If both are enabled, DataKit queries LLDP data on both schedules and produces both object-link and logging outputs.

Device Configuration Requirements¶

Network devices need to:

• Enable LLDP

• Configure SNMP access to LLDP MIB

Verify Configuration¶

Verify LLDP neighbors on device:

# Huawei device
display lldp neighbor

# Cisco device
show lldp neighbor

Verify SNMP can query LLDP data from DataKit host:

# SNMPv2c verification
snmpwalk -v2c -c [COMMUNITY_STRING] [DEVICE_IP] 1.0.8802.1.1.2.1.4.1

# SNMPv3 verification
snmpwalk -v3 -u [USERNAME] -l authPriv \
  -a SHA -A [AUTH_PASSWORD] \
  -x AES -X [PRIV_PASSWORD] \
  [DEVICE_IP] 1.0.8802.1.1.2.1.4.1

Metric¶

For all of the following data collections, the global election tags will added automatically, we can add extra tags in [inputs.snmp.tags] if needed:

 [inputs.snmp.tags]
  # some_tag = "some_value"
  # more_tag = "some_other_value"
  # ...

snmp_metric¶

SNMP device metric data.

Object¶

snmp_object¶

SNMP device object data.

Logging¶

SNMP Trap Logs¶

See SNMP Trap Configuration for setup instructions. In the log explorer, select the configured log source (traps by default) to view the following main contents:

snmp_lldp¶

SNMP LLDP (Link Layer Discovery Protocol) topology data.

FAQ¶

How dows DataKit find devices?¶

DataKit supports "Specified device mode" and "auto-discovery mode" two modes. The two modes can enabled at the same time.

In "specified device mode", DataKit communicates with the specified IP device using the SNMP protocol to know its current online status.

In "auto-discovery mode", DataKit sends SNMP packets to all address in the specified IP segment one by one, and if the response matches the corresponding profile, DataKit assumes that there is a SNMP device on that IP.

Device Not Supported¶

DataKit collects common baseline metrics from SNMP devices. If the collected data does not contain the required metrics, you may need to add a custom Profile.

To do this, obtain the OID manual for the device model from the vendor's website.

Can't see any metrics after configuration?¶

Try loosening ACLs/firewall rules for your devices.

Run snmpwalk -O bentU -v 2c -c <COMMUNITY_STRING> <IP_ADDRESS>:<PORT> 1.3.6 from the host DataKit is running on. If you get a timeout without any response, there is likely something blocking DataKit from collecting metrics from your device.