Tutorial: Writing a custom yaml file for SNMP

Tutorial: Write a custom yaml file describing a MIB.

This page will walk through creating a yaml file used for polling a custom set of oids. Ktranslate ships with a built in set of these at https://github.com/kentik/ktranslate/tree/main/config/profiles/kentik_snmp.

As a base, we will be using Palo Alto Network's PAN-COMMON-MIB.

Each yaml file has three top level sections: extends, sysobjectid, and metrics.

Extends

extends lists the other yaml files which this file inherits. List only the file name. A runtime error will occur if a listed file is not found. For example:

extends:
  - system-mib.yml
  - if-mib.yml

Will add in all mibs found in system-mib.yml and if-mib.yml

Sysobjectid

sysobjectid lists which system object ids will be matched to this profile. They can be specified either exactly:

sysobjectid: 1.3.6.1.4.1.9.1.111

As a list:

sysobjectid:
  - 1.3.6.1.4.1.9.1.111
  - 1.3.6.1.4.1.9.1.170

Or using a wildcard:

sysobjectid: 1.3.6.1.4.1.25461.*

Wildcards will match all oids with the value before the * as a prefix.

Metrics

metrics define the actual oids to poll. The simplest section here lists oids one by one with a name:

metrics:
  - MIB: PAN-COMMON-MIB
    symbol:
      OID: 1.3.6.1.4.1.25461.2.1.2.3.1.0
      name: panSessionUtilization
  - MIB: PAN-COMMON-MIB
    symbol:
      OID: 1.3.6.1.4.1.25461.2.1.2.3.2.0
      name: panSessionMax

Ktranslate will poll each of these oids and create metrics called kentik.snmp.panSessionUtilization and kentik.snmp.panSessionMax

Tables are supported as follows:

  - MIB: PAN-ENTITY-EXT-MIB
    table:
      OID: 1.3.6.1.4.1.25461.1.1.7.1.2.1
      name: panEntityFRUModuleTable
    symbols:
      - OID: 1.3.6.1.4.1.25461.1.1.7.1.2.1.1.1
        name: panEntryFRUModulePowerUsed
      - OID: 1.3.6.1.4.1.25461.1.1.7.1.2.1.1.2
        name: panEntryFRUModuleNumPorts
    metric_tags:
      - MIB: ENTITY-MIB
        column:
          OID: 1.3.6.1.2.1.47.1.1.1.1.2
          name: entPhysicalDescr
        table: entPhysicalTable
        tag: entity_description

This will create metrics kentik.snmp.panEntryFRUModulePowerUsed and kentik.snmp.panEntryFRUModuleNumPorts. Furthermore, the attribute entPhysicalDescr will be added to these metrics.

The final result for this mib is at https://github.com/kentik/ktranslate/blob/main/config/profiles/kentik_snmp/palo_alto/palo-alto.yml.

Enums

Some snmp values come back as enumerated integers. For example, look at http://oidref.com/1.3.6.1.4.1.318.1.1.12.2.3.1.1.3 which describes a PDU. From the description:

Getting this OID will return the phase/bank load state.

phaseLoadNormal(1) indicates that the phase/bank is
operating properly within the rPDULoadConfigLowLoadThreshold
and rPDULoadConfigNearOverloadThreshold OID values.

To encode this in the yaml file, add an enum block:

      - OID: 1.3.6.1.4.1.318.1.1.12.2.3.1.1.3
        name: rPDULoadStatusLoadState
        enum:
          phaseLoadNormal: 1
          phaseLoadLow: 2
          phaseLoadNearOverload: 3
          phaseLoadOverload: 4

This creates the metric kentik.snmp.rPDULoadStatusLoadState. It will be a gauge with a value of 1-4. There will also be an attribute rPDULoadStatusLoadState which is the string version of this value.

Running

Now you have your awesome-custom-mib.yaml file. Add it to a directory my_custom_profiles and launch ktranslate with a new docker flag:

-v `pwd`/my_custom_profiles:/etc/profiles/my_custom_profiles

For example

docker run -ti --name ktranslate --rm --net=host \
  -v `pwd`/my_custom_profiles:/etc/profiles/my_custom_profiles
  -v `pwd`/snmp-base.yaml:/snmp-base.yaml \
  kentik/ktranslate:v2 \
    -snmp=/snmp-base.yaml \
    -log_level=info \
    -format=json 

yaml or yml?

Doesn't matter! Pick one and stick to it.