配置详解

概述

参考:

generator.yml 文件详解

generator.yml 文件提供一个模块列表。 最简单的模块只需要具有一个名称和一组要 walk 的 OID

modules:
  ModuleName:  # 模块的名字，可以随意写。写 fuck_you 都行
    # 指定要 walk 的 OID 列表。所谓的 walk 就是指通过类似 snmpwalk 命令获取指定 OID 的信息。
    # 这里 walk 到指定的 OID 之后，会将 OID 转换为 Metrics
    # 小技巧：可以直接写高层次的 OID，这样，该层下面的所有 OID 都将被 walk。
    # 比如我可以写个 1，这样所有 mibs 文件下的所有 OID 都包含了
    walk:
    - 1                          # 等同于 walk 所有 OID
    - 1.3.6.1.2.1.2              # 等同于 "interfaces"
    - sysUpTime                  # 等同于 "1.3.6.1.2.1.1.3"
    - 1.3.6.1.2.1.31.1.1.1.6.40  # 等同于 索引为 40的 ifHCInOctets 这个 OID
    # SNMP 版本，默认为 2。
    # 版本1使用 GETNEXT 方法发送 udp 请求、2和3版本使用 GETBULK 方法发送 udp 请求
    version: 2
    max_repetitions: 25  # How many objects to request with GET/GETBULK, defaults to 25.
                         # May need to be reduced for buggy devices.
    retries: 3   # How many times to retry a failed request, defaults to 3.
    # 每个单独的SNMP请求的超时，默认为5s
    timeout: 5s

    # 配置认证信息
    auth:
      # 用于 SNMP 的 v1 和 v2 版本的认证信息
      # 设置团体名字. 默认为"public".
      community: public

      # SNMP 的 v3 版本的认证配置与 1，2 都不同，且更为复杂
      # Which are required depends on the security_level.
      # The equivalent options on NetSNMP commands like snmpbulkwalk and snmpget are also listed. See snmpcmd(1).
      username: user  # Required, no default. -u option to NetSNMP.
      security_level: noAuthNoPriv  # Defaults to noAuthNoPriv. -l option to NetSNMP.
                                    # Can be noAuthNoPriv, authNoPriv or authPriv.
      password: pass  # Has no default. Also known as authKey, -A option to NetSNMP.
                      # Required if security_level is authNoPriv or authPriv.
      auth_protocol: MD5  # MD5 or SHA, defaults to MD5. -a option to NetSNMP.
                          # Used if security_level is authNoPriv or authPriv.
      priv_protocol: DES  # DES or AES, defaults to DES. -x option to NetSNMP.
                          # Used if security_level is authPriv.
      priv_password: otherPass # Has no default. Also known as privKey, -X option to NetSNMP.
                               # Required if security_level is authPriv.
      context_name: context # Has no default. -n option to NetSNMP.
                            # Required if context is configured on the device.

    lookups:  # Optional list of lookups to perform.
              # The default for `keep_source_indexes` is false. Indexes must be unique for this option to be used.

      # If the index of a table is bsnDot11EssIndex, usually that'd be the label
      # on the resulting metrics from that table. Instead, use the index to
      # lookup the bsnDot11EssSsid table entry and create a bsnDot11EssSsid label
      # with that value.
      - source_indexes: [bsnDot11EssIndex]
        lookup: bsnDot11EssSsid
        drop_source_indexes: false  # If true, delete source index labels for this lookup.
                                    # This avoids label clutter when the new index is unique.

     overrides: # Allows for per-module overrides of bits of MIBs
       metricName:
         ignore: true # Drops the metric from the output.
         regex_extracts:
           Temp: # A new metric will be created appending this to the metricName to become metricNameTemp.
             - regex: '(.*)' # Regex to extract a value from the returned SNMP walks's value.
               value: '$1' # The result will be parsed as a float64, defaults to $1.
           Status:
             - regex: '.*Example'
               value: '1' # The first entry whose regex matches and whose value parses wins.
             - regex: '.*'
               value: '0'
         type: DisplayString # Override the metric type, possible types are:
                             #   gauge:   An integer with type gauge.
                             #   counter: An integer with type counter.
                             #   OctetString: A bit string, rendered as 0xff34.
                             #   DateAndTime: An RFC 2579 DateAndTime byte sequence. If the device has no time zone data, UTC is used.
                             #   DisplayString: An ASCII or UTF-8 string.
                             #   PhysAddress48: A 48 bit MAC address, rendered as 00:01:02:03:04:ff.
                             #   Float: A 32 bit floating-point value with type gauge.
                             #   Double: A 64 bit floating-point value with type gauge.
                             #   InetAddressIPv4: An IPv4 address, rendered as 1.2.3.4.
                             #   InetAddressIPv6: An IPv6 address, rendered as 0102:0304:0506:0708:090A:0B0C:0D0E:0F10.
                             #   InetAddress: An InetAddress per RFC 4001. Must be preceded by an InetAddressType.
                             #   InetAddressMissingSize: An InetAddress that violates section 4.1 of RFC 4001 by
                             #       not having the size in the index. Must be preceded by an InetAddressType.
                             #   EnumAsInfo: An enum for which a single timeseries is created. Good for constant values.
                             #   EnumAsStateSet: An enum with a time series per state. Good for variable low-cardinality enums.
                             #   Bits: An RFC 2578 BITS construct, which produces a StateSet with a time series per bit.

EnumAsInfo 和 EnumAsStateSet

SNMP contains the concept of integer indexed enumerations (enums). There are two ways to represent these strings in Prometheus. They can be “info” metrics, or they can be “state sets”. SNMP does not specify which should be used, and it’s up to the use case of the data. Some users may also prefer the raw integer value, rather than the string.

In order to set enum integer to string mapping, you must use one of the two overrides.

EnumAsInfo should be used for properties that provide inventory-like data. For example a device type, the name of a colour etc. It is important that this value is constant.EnumAsStateSet should be used for things that represent state or that you might want to alert on. For example the link state, is it up or down, is it in an error state, whether a panel is open or closed etc. Please be careful to not use this for high cardinality values as it will generate 1 time series per possible value.

生成 snmp.yml 文件

snmp.yml 文件通过 generator 程序生成

generator 程序将会根据根据 generator.yml 文件 与 mibs 目录下的 MIB 库文件 生成 snmp.yml 文件。

构建 generator 程序

git clone https://github.com/prometheus/snmp_exporter.git
cd snmp_exporter/generator
# 生成 MIB 信息到当前目录的 mibs/ 目录下
make mibs
# 构建 docker 镜像
docker build -t snmp-generator .

其中 Dockerfile 文件需要修改一些内容，以便适应国内环境

Dockerfile 示例如下

FROM golang:1.16

ENV GOPROXY=https://goproxy.cn,https://goproxy.io,https://mirrors.aliyun.com/goproxy/,direct

RUN apt-get update && \
    apt-get install -y libsnmp-dev p7zip-full unzip
RUN export GO111MODULE=on
RUN go install github.com/prometheus/snmp_exporter/generator@latest

WORKDIR "/opt"

ENTRYPOINT ["/go/bin/generator"]

ENV MIBDIRS mibs

CMD ["generate"]

拷贝所需 MIB 文件到项目中的 ./generator/mibs/ 目录下

image.png

配置 generator.yml 文件

下面是一个 generator.yml 示例，使用 h3c 的 Mib 和 网络相关的 MIb 生成 snmp.yml 文件

modules:
  if_mib:
    walk: [sysUpTime, interfaces, ifXTable]
    lookups:
      - source_indexes: [ifIndex]
        lookup: ifAlias
      - source_indexes: [ifIndex]
        # Uis OID to avoid conflict with PaloAlto PAN-COMMON-MIB.
        lookup: 1.3.6.1.2.1.2.2.1.2 # ifDescr
      - source_indexes: [ifIndex]
        # Use OID to avoid conflict with Netscaler NS-ROOT-MIB.
        lookup: 1.3.6.1.2.1.31.1.1.1.1 # ifName
    overrides:
      ifAlias:
        ignore: true # Lookup metric
      ifDescr:
        ignore: true # Lookup metric
      ifName:
        ignore: true # Lookup metric
      ifType:
        type: EnumAsInfo

运行 generator 程序以生成 snmp.yml 文件

运行 generator 程序，generator 会根据 generator.yml 文件及 mibs 目录下的文件生成 snmp.yml 文件

# 进入项目的 generator 目录中
cd XXXX/snmp_exporter/generator
# 通过 docker 启动 generator 并挂载当前目录，以便通过当前目录的信息生成 snmp.yaml 文件
docker run -it --rm \
  -v "${PWD}:/opt/" \
  snmp-generator generate

最后修改 July 23, 2024: clearup observability (4b9f5578)