SNMP

本文主要介绍 SNMP 数据采集。

术语¶

• SNMP (Simple network management protocol): 用于收集有关裸机网络设备信息的网络协议。
• OID (Object identifier): 设备上的唯一 ID 或地址，轮询时返回该值的响应代码。例如，OID 是 CPU 或设备风扇速度。
• sysOID (System object identifier): 定义设备类型的特定地址。所有设备都有一个定义它的唯一 ID。例如，Meraki 基础 sysOID 是“1.3.6.1.4.1.29671”。
• MIB (Managed information base): 与 MIB 相关的所有可能的 OID 及其定义的数据库或列表。例如，“IF-MIB”（接口 MIB）包含有关设备接口的描述性信息的所有 OID。

关于 SNMP 协议¶

SNMP 协议分为 3 个版本：v1/v2c/v3，其中：

• v1 和 v2c 是兼容的，很多 SNMP 设备只提供 v2c 和 v3 两种版本的选择。v2c 版本，兼容性最好，很多旧设备只支持这个版本；
• 如果对安全性要求高，选用 v3。安全性也是 v3 版本与之前版本的主要区别；

DataKit 支持以上所有版本。

选择 v1/v2c 版本¶

如果选择 v1/v2c 版本，需要提供 v2_community_string（团体名/团体字符串/未加密的口令），与 SNMP 设备进行交互需要提供这个进行鉴权。另外，有的设备会进一步进行细分，分为只读团体名和读写团体名：顾名思义：

• 只读团体名：设备只会向该方提供内部指标数据，不能修改内部的一些配置（DataKit 用这个就够了）
• 读写团体名：提供方拥有设备内部指标数据查询与部分配置修改权限

选择 v3 版本¶

如果选择 v3 版本，需要提供 v3_user/v3_auth_protocol/v3_auth_key/v3_priv_protocol/v3_priv_key 等，各个设备要求不同，根据设备侧的配置进行填写。

配置¶

采集器配置¶

[[inputs.snmp]]
  ## Filling in specific device IP address, example ["10.200.10.240", "10.200.10.241"].
  ## And you can use auto_discovery and specific_devices at the same time.
  ## If you don't want to specific device, you don't need provide this.
  # specific_devices = [""] # SNMP Device IP.

  ## Filling in autodiscovery CIDR subnet, example ["10.200.10.0/24", "10.200.20.0/24"].
  ## If you don't want to enable autodiscovery feature, you don't need provide this.
  # auto_discovery = [""] # Used in autodiscovery mode only, ignore this in other cases.

  ## Consul server url for consul discovery
  ## We can discovery snmp instance from consul services
  # consul_discovery_url = "http://127.0.0.1:8500"

  ## Consul token, optional.
  # consul_token = "<consul token>"

  ## Instance ip key name. ("IP" case sensitive)
  # instance_ip_key = "IP"

  ## Witch task will collect, according to consul service filed "Address"
  ## [] mean collect all, optional, default to []
  # exporter_ips = ["<ip1>", "<ip2>"...]

  ## Consul TLS connection config, optional.
  # ca_certs = ["/opt/tls/ca.crt"]
  # cert = "/opt/tls/client.crt"
  # cert_key = "/opt/tls/client.key"
  # insecure_skip_verify = true

  ## SNMP protocol version the devices using, fill in 2 or 3.
  ## If you using the version 1, just fill in 2. Version 2 supported version 1.
  ## This is must be provided.
  snmp_version = 2

  ## SNMP port in the devices. Default is 161. In most cases, you don't need change this.
  ## This is optional.
  # port = 161

  ## Password in SNMP v2, enclose with single quote. Only worked in SNMP v2.
  ## If you are using SNMP v2, this is must be provided.
  ## If you are using SNMP v3, you don't need provide this.
  # v2_community_string = ""

  ## Authentication for SNMP v3.
  ## If you are using SNMP v2, you don't need provide this.
  ## If you are using SNMP v3, this is must be provided.
  # 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

  ## Number of workers used to collect and discovery devices concurrently. Default is 100.
  ## Modifying it based on device's number and network scale.
  ## This is optional.
  # workers = 100

  ## Number of max OIDs during walk(default 1000)
  # max_oids = 1000

  ## Number of OIDs retrieved in a single SNMP Get/GetBulk call. Default is 5.
  # oid_batch_size = 5

  ## Max repetitions used in SNMP GetBulk calls. Default is 10.
  # bulk_max_repetitions = 10

  ## Interval between each auto discovery in seconds. Default is "1h".
  ## Only worked in auto discovery feature.
  ## This is optional.
  # discovery_interval = "1h"

  ## Collect metric interval, default is 10s. (optional)
  # metric_interval = "10s"

  ## Collect object interval, default is 5m. (optional)
  # object_interval = "5m"

  ## Enable LLDP topology collection. Default is false. (optional)
  # enable_lldp = false

  ## LLDP collection interval, default is 10m. (optional)
  # lldp_interval = "10m"

  ## Filling in excluded device IP address, example ["10.200.10.220", "10.200.10.221"].
  ## Only worked in auto discovery feature.
  ## This is optional.
  # discovery_ignored_ip = []

  ## Set true to enable election
  # election = true

  ## Device Namespace. Default is "default".
  # device_namespace = "default"

  ## Picking the metric data only contains the field's names below.
  # enable_picking_data = true # Default is "false", which means collecting all data.
  # status = ["sysUpTimeInstance", "tcpCurrEstab", "ifAdminStatus", "ifOperStatus", "cswSwitchState"]
  # speed = ["ifHCInOctets", "ifHCInOctetsRate", "ifHCOutOctets", "ifHCOutOctetsRate", "ifHighSpeed", "ifSpeed", "ifBandwidthInUsageRate", "ifBandwidthOutUsageRate"]
  # cpu = ["cpuUsage"]
  # mem = ["memoryUsed", "memoryUsage", "memoryFree"]
  # extra = []

  ## The matched tags would be dropped.
  # tags_ignore = ["Key1","key2"]

  ## The regexp matched tags would be dropped.
  # tags_ignore_regexp = ["^key1$","^(a|bc|de)$"]

  ## Zabbix profiles
  # [[inputs.snmp.zabbix_profiles]]
    ## Can be full path file name or only file name.
    ## If only file name, the path is "./conf.d/snmp/userprofiles/
    ## Suffix can be .yaml .yml .xml
    # profile_name = "xxx.yaml"
    ## ip_list is optional
    # ip_list = ["ip1", "ip2"]
    ## Device class, Best to use the following words:
    ## 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, 
  ## If module mapping different class, can disassemble yml file.
  # [[inputs.snmp.prom_profiles]]
    # profile_name = "xxx.yml"
    ## ip_list useful when xxx.yml have 1 module 
    # ip_list = ["ip1", "ip2"]
    # class = "net_device"

  # ...

  ## Prometheus consul discovery module mapping.  ("type"/"isp" case sensitive)
  # [[inputs.snmp.module_regexps]]
    # module = "vpn5"
    ## There is an and relationship between step regularization
    # step_regexps = [["type", "vpn"],["isp", "CT"]]

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

  # ...

  ## Field key or tag key mapping. Do NOT edit.
  [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"
    ## We can add more mapping below
    # dev_fan_speed = "fanSpeed"
    # dev_disk_size = "diskTotal

  ## Reserved oid-key mappings. Do NOT edit.
  [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"
    ## We can add more oid-key mapping below

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

  [inputs.snmp.traps]
    enable = true
    bind_host = "0.0.0.0"
    port = 9162
    stop_timeout = 3    # stop timeout in seconds.

多种配置格式¶

内置 Profile 格式¶

内置 Profile 使用 YAML 描述设备的 sysObjectID、采集 OID、指标类型、标签和元数据。

该格式适合以下场景：

• 内置 Profile 未覆盖当前设备型号；
• 需要增加厂商私有 MIB 指标；
• 设备将数值以 String/OCTET STRING 形式返回；
• 需要补充设备元数据。

Profile YAML 与 Zabbix Template、Prometheus snmp_exporter 格式不同，字段不能混用。

准备 OID 信息¶

编写 Profile 前，应先获取设备 MIB/OID 手册，并使用 snmpget 或 snmpwalk 确认设备的实际返回结果。至少需要确认：

• sysObjectID，即 OID 1.3.6.1.2.1.1.2.0 的值；
• 指标是标量还是表格列；
• 指标 OID、数据类型、含义和单位；
• String/OCTET STRING 的完整返回格式；
• 表格索引和能够区分每一行的标签列。

新增 Profile¶

DataKit 会将内置 Profile 释放到安装目录的 conf.d/snmp/profiles/，该目录可能在启动或升级时被覆盖。用户新增或覆盖内置 Profile 时，建议将 YAML 文件放入 conf.d/snmp/extra_profiles/，DataKit 会在默认 Profile 加载流程中合并这两个目录，且 extra_profiles 优先级更高。

示例：

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

文件要求：

• 扩展名必须为 .yaml；
• 文件名不能以 _ 开头，以 _ 开头的文件只作为继承模板；
• 与内置 Profile 同名时，extra_profiles 中的文件优先；如仍需继承原内置内容，可在该文件中 extends 同名文件；
• 不同文件名不应配置相同的 sysobjectid，否则自动匹配时会按重复 Profile 处理。

新增后重启 DataKit。

基本结构¶

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

根级字段说明：

MIB 和 table 用于提高 YAML 可读性，不决定实际 SNMP 查询。DataKit 实际查询的是 symbol、symbols、metric_tags 和 metadata 中配置的 OID。

继承 Profile¶

extends 用于继承已有 Profile。被继承 Profile 中的指标、标签和元数据会合并到当前 Profile，可以减少标准 MIB 的重复配置。

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

DataKit 已安装的内置 Profile 位于 conf.d/snmp/profiles/，用户补充 Profile 位于 conf.d/snmp/extra_profiles/。编写 YAML 前，建议先查看内置目录中以 _ 开头的文件，并根据当前 DataKit 版本选择可复用的模板。常用模板包括：

以 _ 开头的文件只作为继承模板，不独立参与 sysObjectID 自动匹配。也可以继承不以 _ 开头的完整 Profile，例如 generic-router.yaml：

extends:
  - generic-router.yaml

generic-router.yaml 已经继承 _base.yaml、_generic-if.yaml、_generic-ip.yaml、_generic-tcp.yaml、_generic-udp.yaml 和 _generic-ospf.yaml。因此继承它以后，不需要再次显式继承这些文件。

Cisco 设备可以继承通用 Cisco 模板，并追加设备专属指标：

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

sysobjectid: 1.3.6.1.4.1.9.1.<product_id>

注意：

• extends 中的文件名会优先从 conf.d/snmp/extra_profiles/ 查找，再从 conf.d/snmp/profiles/ 查找；
• extra_profiles 中的同名 Profile 可以通过 extends 自身文件名继承内置同名 Profile；
• 支持继承多个 Profile 和多层继承，但不能循环继承；
• 指标、动态标签和静态标签采用追加方式合并；
• 当前 Profile 已定义的同名元数据字段不会被继承内容覆盖；
• 不要重复继承已经被上层 Profile 包含的模板，否则可能产生重复指标或标签；
• 继承的通用模块越多，需要查询的 OID 越多，应按设备实际支持的 MIB 选择。

sysObjectID 匹配¶

精确匹配：

sysobjectid: 1.3.6.1.4.1.99999.1.2

通配匹配：

sysobjectid: 1.3.6.1.4.1.99999.*

匹配多个型号：

sysobjectid:
  - 1.3.6.1.4.1.99999.1.*
  - 1.3.6.1.4.1.99999.2.*

多个 Profile 同时匹配时，DataKit 选择更具体的规则。不同 Profile 不应配置完全相同的 sysobjectid。应尽量使用厂商或产品专属值，避免宽泛规则误匹配其他设备。

例如 1.3.6.1.4.1.8072.3.2.10 是常见的 Net-SNMP Linux sysObjectID，并非某个设备厂商独占。

标量指标¶

标量只有一个值，使用 symbol 定义。标量 OID 通常以 .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

表格指标¶

表格有多行数据，使用 symbols 定义需要采集的列，并使用 metric_tags 区分每一行：

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

表格必须至少配置一个能够区分行的标签，否则多行指标可能拥有相同标签，最终只能保留一行。

也可以从 OID 行索引中生成标签。index 从 1 开始：

metric_tags:
  - index: 1
    tag: disk_index

如果完整索引为 3.24，以下配置会生成 slot:3 和 port:24：

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

String 转数值¶

指标字段值需要是数值类型。纯数字 String/OCTET STRING（如 "52.20"）可直接转换；值中包含单位或其他字符时，使用 extract_value 提取第一个捕获组。

设备返回 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

设备返回 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

注意：

• 正则必须至少包含一个捕获组，DataKit 只使用第一个捕获组；
• 建议使用单引号包裹正则，并使用 ^ 和 $ 完整匹配；
• 使用 Go 正则语法，不支持 lookahead 和 lookbehind；
• 正则不匹配时，当前值不会上报；
• 普通文本 String 不应作为时序指标值，应配置为标签或元数据。

指标类型和数值换算¶

自定义 Profile 推荐使用以下 metric_type：

可以在具体 symbol 中配置，也可以在表格指标根级配置并应用于该表格的所有 symbols。具体 symbol 中的配置优先级更高。不配置时，DataKit 根据 SNMP 返回类型推断，无法推断时按 gauge 处理。

scale_factor 用于数值换算。例如设备返回 5234，实际值为 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 只作用于最终上报的指标数值。String 指标可先使用 extract_value 提取数值，再应用 scale_factor。

固定上报数值 1¶

表格表示一组实体，但没有合适的数值列时，可使用 constant_value_one 为每一行固定上报 1：

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 只能用于表格 symbols，不能用于标量。使用时不填写指标 OID，但必须配置 name，并至少配置一个不含 index_transform、带 OID 的 metric_tags.symbol，以便 DataKit 发现表格行。

标签¶

Profile 根级 static_tags 用于增加固定标签：

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

Profile 根级 metric_tags 从标量 OID 生成应用于设备指标的动态标签：

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

表格内的 metric_tags 可以使用 mapping 将原始值转换为可读标签：

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

使用 match 和 tags 可从一个表格列值生成多个标签：

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'

原始值为 ethernet-12 时，将生成 interface_type:ethernet 和 interface_number:12。配置 match 时必须同时配置非空的 tags，正则不匹配时不会生成标签。

当指标表和标签来源表的索引结构不一致时，可以使用 index_transform 截取并重组索引：

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

如果当前索引为 1.2.3.4.5.6.7.8，转换结果为 2.3.7.8。start 和 end 都从 0 开始，且 end 所在位置包含在结果中。只有在跨表关联时才需要使用该配置。

元数据¶

自定义 Profile 可以通过 metadata.device 补充设备元数据，支持 name、description、sys_object_id、location、serial_number、vendor、version、product_name、model、os_name、os_version、os_hostname 和 type 字段。字段值可以来自标量 OID，也可以使用固定 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

一个字段可配置多个候选 symbols，DataKit 按顺序使用第一个能够取得值的 OID。match_pattern 和 match_value 可从文本中提取或替换内容：

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'

省略 match_value 时默认使用第一个捕获组 $1；正则不匹配时，DataKit 尝试下一个候选 symbol。

继承 _generic-if.yaml 或 generic-router.yaml 后，通用接口元数据已经包含在继承内容中，通常不需要重复配置。

指标命名¶

指标名按以下规则转换后上报：

1. 名称中包含下划线 _ 时，将所有点号 . 替换为下划线 _；
2. 名称中不包含下划线 _ 时，删除点号 .，并将点号后第一个字母转换为大写；
3. 名称中没有点号 . 时，保持不变。

示例：

该转换也适用于标签键，但不会修改标签值。

同一个 Profile 应统一命名风格。可以使用不含下划线的点号分层名称，例如 vendor.disk.used；也可以直接使用不含点号的下划线名称，例如 vendor_disk_used。避免混用点号和下划线，因为点号最终会转换为下划线。现有内置 Profile 常使用 huawei.hwEntityTemperature 这类名称，最终上报为 huaweiHwEntityTemperature。

完整示例¶

以下示例继承通用路由器指标，采集设备元数据、数值标量、String 类型磁盘指标和实体存在性指标：

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

验证和排错¶

常见问题：

• Profile 未匹配：检查设备实际 sysObjectID、通配符范围以及是否存在更具体的匹配规则；
• YAML 未加载：检查文件扩展名、文件名、缩进和 DataKit 日志中的 Profile 校验错误；
• OID 无数据：使用与 DataKit 相同的 SNMP 版本和认证信息运行 snmpget/snmpwalk；
• String 指标未上报：检查 extract_value 是否包含捕获组并匹配实际完整值；
• 表格只上报一行：为表格增加能够区分每一行的 metric_tags；
• 指标被跳过：确认最终值能够转换为数值，并检查 metric_type 和 scale_factor。

Zabbix 格式¶

• 配置

    [[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 = "firewall"
  
    # ...
  

  profile_name 可以是全路径或只包含文件名，只包含文件名的话，文件要放到 ./conf.d/snmp/userprofiles/ 子目录下。

  您可以去 Zabbix 官方下载对应的的配置，也可以去 社区 下载。

  如果您对下载到的 yaml 或 xml 文件不满意，也可以自行修改。

• 自动发现

  • 自动发现在引入的多个 yaml 配置里面匹配采集规则，进行采集。
  • 自动发现请尽量按 C 段配置，配置 B 段可能会慢一些。

  • 万一自动发现匹配不到 yaml ，是因为已有的 yaml 里面没有被采集设备的生产商特征码。

    • 可以在 yaml 的 items 里面人为加入一条 oid 信息，引导自动匹配过程。

    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
    

    • 拟加入的 oid 通过执行以下命令获得，后面加上 .0.0.0.0 是为了防止产生无用的指标。

    $ 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 格式¶

• 配置

    [[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"
  
    # ...
  

  profile 参考 Prometheus snmp_exporter 的 snmp.yml 文件， 建议把不同 class 的 module 拆分成 不同 .yml 配置。

  Prometheus 的 profile 允许为 module 单独配置团体名 community，这个团体名优先于采集器配置的团体名。

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

• 自动发现

  SNMP 采集器支持通过 Consul 服务发现来发现被采集对象，服务注入格式参考 prom 官网。

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

配置被采集 SNMP 设备¶

SNMP 设备在默认情况下，一般 SNMP 协议处于关闭状态，需要进入管理界面手动打开。同时，需要根据实际情况选择协议版本和填写相应信息。

# 适用 v2c 版本
snmpwalk -O bentU -v 2c -c [community string] [SNMP_DEVICE_IP] 1.3.6
# 适用 v3 版本
snmpwalk -v 3 -u user -l authPriv -a sha -A [认证密码] -x aes -X [加密密码] [SNMP_DEVICE_IP] 1.3.6

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

SNMPv3 示例¶

我们以一个 Linux 上的 snmpd 作为示例，来演示如何采集 SNMP v3 的采集。

• 在一台 Ubuntu 机器上，我们可以安装 snmpd 服务：

  sudo apt install snmp snmpd libsnmp-dev
  

• 准备如下一个简易的 snmpd.conf 配置：

  my-snmpd.conf

  # 设定 UDP 161 端口
  agentaddress udp:161
  
  # 设定用户名以及几个认证相关的配置
  createUser snmpv3user1 SHA "authPassAgent1" AES "privPassAgent1"
  
  # 授予用户访问权限 (rouser: read-only, rwuser: read-write)
  rouser snmpv3user1 priv .1.3.6
  

• 先停掉 snmpd 服务，手动启动 snmpd 程序：

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

• 用 snmpwalk 命令检测一下，预期将输出很多 OID 设备信息：

  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
  

• 如果 snmpwalk 命令成功，就可以在 DataKit 上开启本采集器，通过 SNMPv3 来采集指标。关键配置如下：

  conf.d/snmp/snmp.conf

  specific_devices = ["127.0.0.1"] # 此处不要填 localhost
  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
  

LLDP 网络拓扑采集¶

DataKit 支持通过 SNMP 协议采集网络设备的 LLDP（Link Layer Discovery Protocol，链路层发现协议）邻居信息，用于自动构建网络拓扑。

什么是 LLDP¶

LLDP 是一个标准化的链路层协议，允许网络设备（如交换机、路由器）向直连的邻居设备广播自己的身份和能力信息。通过采集 LLDP 数据，可以：

• 自动发现网络拓扑关系
• 了解设备间的物理连接情况
• 获取邻居设备的端口、主机名、系统描述等信息
• 构建可视化的网络拓扑图

启用 LLDP 采集¶

在 DataKit 的 SNMP 配置中启用 LLDP 采集：

[[inputs.snmp]]
  ## 启用 LLDP 拓扑采集
  enable_lldp = true

  ## LLDP 采集间隔（可选，默认 10 分钟）
  lldp_interval = "10m"

被采集设备配置要求¶

网络设备端需要：

• 启用 LLDP

• 配置 SNMP 访问 LLDP MIB 权限

验证配置¶

在设备上验证 LLDP 邻居：

# 华为设备
display lldp neighbor

# Cisco 设备
show lldp neighbor

从 DataKit 主机验证 SNMP 能否查询 LLDP 数据：

# SNMPv2c 验证
snmpwalk -v2c -c [COMMUNITY_STRING] [DEVICE_IP] 1.0.8802.1.1.2.1.4.1

# SNMPv3 验证
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

指标¶

以下所有数据采集，默认会追加全局选举 tag，也可以在配置中通过 [inputs.snmp.tags] 指定其它标签：

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

snmp_metric¶

SNMP device metric data.

对象¶

snmp_object¶

SNMP device object data.

日志¶

snmp_lldp¶

SNMP LLDP (Link Layer Discovery Protocol) topology data.

FAQ¶

DataKit 是如何发现设备的?¶

DataKit 支持 "指定设备" 和 "自动发现" 两种模式。两种模式可以同时开启。

指定设备模式下，DataKit 与指定 IP 的设备使用 SNMP 协议进行通信，可以获知其目前在线状态。

自动发现模式下，DataKit 向指定 IP 网段内的所有地址逐一发送 SNMP 协议数据包，如果其响应可以匹配到相应的 Profile，那么 DataKit 认为该 IP 上有一个 SNMP 设备。

设备不支持采集¶

DataKit 可以从所有 SNMP 设备中收集通用的基线指标。如果你发现被采集的设备上报的数据中没有你想要的指标，那么，你可能需要为该设备自定义一份 Profile。

为了完成上述工作，你很可能需要从设备厂商的官网下载该设备型号的 OID 手册。

开启 SNMP 设备采集但看不到指标¶

尝试为你的设备放开 ACLs/防火墙 规则。

可以在运行 DataKit 的主机上运行命令 snmpwalk -O bentU -v 2c -c <COMMUNITY_STRING> <IP_ADDRESS>:<PORT> 1.3.6。如果得到一个没有任何响应的超时，很可能是有什么东西阻止了 DataKit 从你的设备上收集指标。