SNMP

이 문서는 SNMP 데이터 수집을 설명합니다.

용어¶

• SNMP (Simple network management protocol): 물리 네트워크 장치 정보를 수집하는 네트워크 프로토콜.
• OID (Object identifier): 폴링 시 값을 반환하는 장치의 고유 ID 또는 주소. 예: CPU 또는 장치 팬 속도.
• sysOID (System object identifier): 장치 유형을 정의하는 고유 주소. 예를 들어 Meraki의 기본 sysOID는 “1.3.6.1.4.1.29671”입니다.
• MIB (Managed information base): 관련 OID와 정의를 담은 데이터베이스 또는 목록. 예를 들어 “IF-MIB”는 장치 인터페이스 정보를 설명하는 OID를 포함합니다.

SNMP 프로토콜 정보¶

SNMP에는 v1/v2c/v3 세 가지 버전이 있습니다:

• v1과 v2c는 호환됩니다. 많은 장치는 v2c와 v3만 제공합니다. v2c의 호환성이 가장 높으며 오래된 장치는 이 버전만 지원하는 경우가 많습니다.
• 높은 보안이 필요하면 v3를 선택합니다. 보안은 이전 버전과의 주요 차이점입니다.

DataKit은 위 버전을 모두 지원합니다.

v1/v2c 선택¶

v1/v2c는 장치 인증용 v2_community_string(커뮤니티 이름/문자열/암호화되지 않은 암호)이 필요합니다. 일부 장치는 읽기 전용 커뮤니티와 읽기/쓰기 커뮤니티를 구분합니다:

• 읽기 전용: 내부 메트릭을 읽을 수 있지만 구성을 변경할 수 없습니다. 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"

  ## Collect LLDP/CDP topology links in snmp_object. Default is false. (optional)
  ## Built-in Profiles only; follows object_interval and is independent of enable_lldp.
  ## LLDP is preferred, with CDP used as a fallback.
  # collect_topology = false

  ## Enable standalone LLDP neighbor collection and report snmp_lldp logging data.
  ## Default is false. (optional)
  ## Avoid enabling this together with collect_topology unless both outputs are needed.
  # 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". It is an identity tag and cannot be overridden by custom tags.
  # 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.
    # source = "traps"

다양한 구성 형식¶

기본 제공 Profile 형식¶

기본 제공 Profile은 YAML로 장치 sysObjectID, 수집 OID, 메트릭 유형, tag 및 메타데이터를 정의합니다.

이 형식은 다음 상황에 적합합니다:

• 기본 제공 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의 전체 응답 형식;
• 테이블 인덱스와 각 행을 구분할 tag 열.

Profile 추가¶

DataKit은 기본 Profile을 설치 경로의 conf.d/snmp/profiles/에 풀며 시작 또는 업그레이드 시 덮어쓸 수 있습니다. 추가하거나 재정의할 YAML은 conf.d/snmp/extra_profiles/에 두세요. 기본 로드 과정에서 두 디렉터리를 병합하며 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을 상속합니다. 메트릭, tag, 메타데이터를 현재 Profile에 병합하여 표준 MIB의 중복 구성을 줄입니다.

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

기본 Profile은 conf.d/snmp/profiles/, 사용자 추가 Profile은 conf.d/snmp/extra_profiles/에 있습니다. YAML 작성 전에 _로 시작하는 파일을 확인하고 DataKit 버전에 맞는 템플릿을 선택하세요. 일반적인 템플릿:

_로 시작하는 파일은 상속 전용이며 독립적인 sysObjectID 자동 일치에 참여하지 않습니다. generic-router.yaml처럼 _로 시작하지 않는 전체 Profile도 상속할 수 있습니다:

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 및 다단계 상속을 지원하지만 순환 상속은 허용하지 않습니다;
• 메트릭, 동적 tag 및 정적 tag는 추가 방식으로 병합합니다;
• 현재 Profile에 정의된 같은 이름의 메타데이터 필드는 덮어쓰지 않습니다;
• 상위 Profile에 이미 포함된 템플릿을 중복 상속하면 메트릭이나 tag가 중복될 수 있습니다;
• 상속하는 공통 모듈이 많을수록 조회 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

행을 구분하는 tag가 하나 이상 필요합니다. 없으면 여러 행의 tag가 같아져 최종적으로 한 행만 남을 수 있습니다.

OID 행 인덱스에서도 tag를 생성할 수 있습니다. 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을 숫자로 변환¶

메트릭 필드 값은 숫자여야 합니다. "52.20"처럼 숫자만 있는 String/OCTET STRING은 직접 변환합니다. 단위나 다른 문자가 있으면 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은 시계열 메트릭 값이 아니라 tag 또는 메타데이터로 구성하세요.

메트릭 유형 및 값 변환¶

사용자 정의 Profile에는 다음 metric_type을 권장합니다:

개별 symbol 또는 테이블 메트릭 루트에서 모든 symbols에 설정할 수 있습니다. 개별 설정이 우선합니다. 미설정 시 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은 필수입니다. 행 검색을 위해 OID가 있고 index_transform이 없는 metric_tags.symbol을 하나 이상 구성해야 합니다.

태그¶

Profile 루트의 static_tags는 고정 tag를 추가합니다:

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

Profile 루트의 metric_tags는 스칼라 OID에서 장치 메트릭용 동적 tag를 생성합니다:

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

테이블의 metric_tags는 mapping으로 원래 값을 읽기 쉬운 tag로 변환할 수 있습니다:

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로 하나의 열 값에서 여러 tag를 생성할 수 있습니다:

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가 필수이며 정규식이 일치하지 않으면 tag를 생성하지 않습니다.

메트릭 테이블과 tag 소스 테이블의 인덱스 구조가 다르면 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 위치도 포함됩니다. 테이블 간 연결에만 필요한 구성입니다.

메타데이터¶

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을 사용하며 정규식이 일치하지 않으면 다음 symbol 후보를 시도합니다.

_generic-if.yaml 또는 generic-router.yaml을 상속하면 공통 인터페이스 메타데이터가 포함되므로 보통 다시 구성할 필요가 없습니다.

메트릭 이름 지정¶

메트릭 이름은 다음 규칙으로 변환한 뒤 보고합니다:

1. 이름에 _이 있으면 모든 .을 _로 바꿉니다;
2. _이 없으면 .을 제거하고 바로 뒤 첫 글자를 대문자로 바꿉니다;
3. .이 없으면 변경하지 않습니다.

예:

이 변환은 tag key에도 적용되지만 tag 값은 바꾸지 않습니다.

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를 지정할 수 있으며 수집기 구성의 community보다 우선합니다.

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

• 자동 검색

  SNMP 수집기는 Consul 서비스 검색을 지원합니다. 등록 형식은 Prometheus 공식 문서를 참고하세요.

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

수집 대상 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

  # 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
  

• 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"] # 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
  

LLDP 네트워크 토폴로지 수집¶

DataKit은 SNMP로 네트워크 장치의 LLDP(Link Layer Discovery Protocol) 이웃 정보를 수집하여 네트워크 토폴로지를 자동 구성합니다.

LLDP란¶

LLDP는 스위치나 라우터가 직접 연결된 이웃 장치에 자신의 식별 정보와 기능을 알리는 표준 링크 계층 프로토콜입니다. 데이터를 수집하면 다음이 가능합니다:

• 네트워크 토폴로지 관계 자동 검색
• 장치 간 물리 연결 파악
• 이웃 장치 포트, 호스트 이름 및 시스템 설명 획득
• 네트워크 토폴로지 시각화

LLDP 수집 활성화¶

LLDP 이웃을 snmp_object 객체의 링크 메타데이터로 추가하는 것이 좋습니다:

[[inputs.snmp]]
  ## 객체와 함께 LLDP 이웃을 수집하고 토폴로지 링크를 snmp_object의 links 필드에 기록합니다
  collect_topology = true

collect_topology는 기본 비활성화됩니다. 활성화하면 객체 수집 주기에 LLDP/CDP MIB를 추가 조회하고 로컬 및 원격 장치/인터페이스 메타데이터를 JSON 배열로 인코딩하여 snmp_object의 links에 씁니다. LLDP 링크를 우선하며 없을 때만 CDP를 사용합니다.

snmp_object를 보고하는 기본 Profile 모드에만 적용되며 사용자 Profile의 snmp_<class> 객체에는 적용되지 않습니다.

links 필드¶

links를 디코딩한 LLDP 링크 예제입니다. //는 필드 설명 주석입니다:

[
  {
    // 로컬 장치의 토폴로지 이웃 레코드 ID.
    // LLDP 형식: <device_namespace>:<관리 IP>:<lldpRemLocalPortNum>.<lldpRemIndex>;
    // CDP 형식: <device_namespace>:<관리 IP>:<cdpCacheIfIndex>.<cdpCacheDeviceIndex>.
    "id": "default:192.0.2.10:7.1",
    // 이웃 데이터 소스: lldp 또는 cdp.
    "source_type": "lldp",
    // 수집 통합 이름. 현재 snmp로 고정.
    "integration": "snmp",
    // DataKit이 직접 수집하는 로컬 링크 엔드포인트.
    "local": {
      // 로컬 장치.
      "device": {
        // 확인된 로컬 장치 ID: <device_namespace>:<관리 IP>.
        "resolved_id": "default:192.0.2.10"
      },
      // 로컬 인터페이스.
      "interface": {
        // 확인된 로컬 인터페이스 ID: <local.device.resolved_id>:<ifIndex>.
        // LLDP 로컬 포트를 IF-MIB 인터페이스에 연결할 수 없으면 누락될 수 있습니다.
        "resolved_id": "default:192.0.2.10:12",
        // LLDP의 lldpLocPortId. CDP 링크는 현재 빈 문자열.
        "id": "82:a5:6e:a5:c9:01",
        // lldpLocPortIdSubtype에서 변환한 로컬 포트 ID 유형. CDP에서는 보통 누락.
        "id_type": "mac_address"
      }
    },
    // 이웃 프로토콜로 검색한 원격 엔드포인트. DataKit이 직접 수집하는 장치라는 뜻은 아닙니다.
    "remote": {
      // 원격 장치.
      "device": {
        // LLDP의 lldpRemChassisId 또는 CDP의 cdpCacheDeviceId.
        "id": "01:00:00:00:01:02",
        // lldpRemChassisIdSubtype에서 변환한 LLDP Chassis ID 유형. CDP에서는 보통 누락.
        "id_type": "mac_address",
        // LLDP의 lldpRemSysName 또는 CDP의 cdpCacheSysName.
        "name": "switch-b",
        // LLDP의 lldpRemSysDesc 또는 CDP의 cdpCacheVersion.
        "description": "remote switch",
        // 원격 관리 IP. LLDP는 원격 관리 주소 테이블 인덱스에서 파싱합니다;
        // CDP는 기본, 보조, 캐시 관리 주소 순으로 시도합니다. 장치가 보고하지 않으면 누락.
        "ip_address": "10.250.0.6"
      },
      // 원격 인터페이스.
      "interface": {
        // LLDP의 lldpRemPortId 또는 CDP의 cdpCacheDevicePort.
        "id": "Ethernet1/7",
        // LLDP 원격 포트 ID 유형. CDP는 interface_name으로 고정.
        "id_type": "interface_name",
        // LLDP의 lldpRemPortDesc. CDP에서는 보통 누락.
        "description": "remote uplink"
      }
    }
  }
]

LLDP 장치/포트 ID 유형에는 mac_address, network_address, interface_name, interface_alias, port_component, local 등이 있습니다. 구조상 필수 필드 외에 이름, 설명, 관리 IP 및 확인하지 못한 객체 ID는 결과에서 누락될 수 있습니다.

기존 enable_lldp는 lldp_interval에 따라 실행되어 snmp_lldp 로그를 보고하는 독립 수집 기능이며 기존 구성 호환성을 위해 유지합니다:

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

두 스위치는 독립적이며 기본값은 false입니다. 보통 하나의 출력만 활성화하면 됩니다. 둘 다 활성화하면 각각의 주기로 LLDP를 조회하고 객체 링크와 로그를 모두 생성합니다.

대상 장치 구성 요구 사항¶

네트워크 장치 측 요구 사항:

• LLDP 활성화

• LLDP MIB에 대한 SNMP 접근 허용

구성 검증¶

장치에서 LLDP 이웃 확인:

# Huawei device
display lldp neighbor

# Cisco device
show lldp neighbor

DataKit 호스트에서 SNMP로 LLDP 조회 가능 여부 확인:

# 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

메트릭¶

다음 수집 데이터에는 기본적으로 전역 선출 tag를 추가합니다. [inputs.snmp.tags]로 다른 tag도 지정할 수 있습니다:

[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은 지정 장치와 자동 검색 두 모드를 지원하며 동시에 활성화할 수 있습니다.

지정 모드에서는 지정 IP 장치와 SNMP로 통신하여 온라인 상태를 확인합니다.

자동 검색에서는 지정 서브넷의 모든 주소로 SNMP 패킷을 보내고 응답이 Profile과 일치하면 해당 IP에 SNMP 장치가 있다고 판단합니다.

장치 수집 미지원¶

DataKit은 모든 SNMP 장치에서 공통 기본 메트릭을 수집할 수 있습니다. 필요한 메트릭이 없으면 사용자 정의 Profile이 필요할 수 있습니다.

이를 위해 공급업체 공식 사이트에서 해당 모델의 OID 설명서를 다운로드해야 할 수 있습니다.

SNMP 수집을 활성화했지만 메트릭이 표시되지 않음¶

장치의 ACL/방화벽 규칙에서 접근을 허용해 보세요.

DataKit 호스트에서 snmpwalk -O bentU -v 2c -c <COMMUNITY_STRING> <IP_ADDRESS>:<PORT> 1.3.6을 실행합니다. 응답 없이 시간 초과가 발생하면 메트릭 수집 접근이 차단되었을 가능성이 큽니다.