Objects

Objects define the SNMP objects and attributes that may be polled by the SNMP Input.

The location of the object definition files is specified by EF_INPUT_SNMP_OBJECT_DEFINITIONS_DIRECTORY_PATH in the collectors configuration options. The default location is /etc/elastiflow/snmp/objects.

Configuration Example

IF-MIB::ifEntry:
  mib: IF-MIB
  object: ifEntry
  index:
    - type: Integer
      oid: .1.3.6.1.2.1.2.2.1.1
      name: netif
      syntax: InterfaceIndex
  discovery_attribute: ifDescr
  attributes:
    ifDescr:
      oid: .1.3.6.1.2.1.2.2.1.2
      tag: true
      name: netif.descr
      syntax: DisplayString
    ifType:
      oid: .1.3.6.1.2.1.2.2.1.3
      tag: true
      name: netif.type
      syntax: IANAifType
    ifSpeed:
      oid: .1.3.6.1.2.1.2.2.1.5
      name: netif.bandwidth.bw
      syntax: Gauge32
    ifPhysAddress:
      oid: .1.3.6.1.2.1.2.2.1.6
      tag: true
      name: netif.mac
      syntax: PhysAddress
    ifAdminStatus:
      oid: .1.3.6.1.2.1.2.2.1.7
      name: netif.state.admin
      syntax: EnumInteger
    ifOperStatus:
      oid: .1.3.6.1.2.1.2.2.1.8
      name: netif.state.oper
      syntax: EnumInteger
    ifInOctets:
      oid: .1.3.6.1.2.1.2.2.1.10
      name: netif.bytes.in
      syntax: Counter32
    ifInUcastPkts:
      oid: .1.3.6.1.2.1.2.2.1.11
      name: netif.packets.ucast.in
      syntax: Counter32
    ifInDiscards:
      oid: .1.3.6.1.2.1.2.2.1.13
      name: netif.packets.discard.in
      syntax: Counter32
    ifInErrors:
      oid: .1.3.6.1.2.1.2.2.1.14
      name: netif.packets.error.in
      syntax: Counter32
    ifInUnknownProtos:
      oid: .1.3.6.1.2.1.2.2.1.15
      name: netif.packets.unkproto.in
      syntax: Counter32
    ifOutOctets:
      oid: .1.3.6.1.2.1.2.2.1.16
      name: netif.bytes.out
      syntax: Counter32
    ifOutUcastPkts:
      oid: .1.3.6.1.2.1.2.2.1.17
      name: netif.packets.ucast.out
      syntax: Counter32
    ifOutDiscards:
      oid: .1.3.6.1.2.1.2.2.1.19
      name: netif.packets.discard.out
      syntax: Counter32
    ifOutErrors:
      oid: .1.3.6.1.2.1.2.2.1.20
      name: netif.packets.error.out
      syntax: Counter32

Configuration Attributes

mib

Contains the name of the SNMP MIB where the object is defined.

EXAMPLE: mib: IF-MIB

object

Contains the name of the SNMP object which the attributes. This is usually one level up from where the attributes are defined.

EXAMPLE: object: ifEntry

index (optional)

The Object Identifier (OID) of a value provided by an agent is made of of the OID of the values definition and the ID of the index of the value within the agent. Scalar SNMP values will always have an index of .0. The index of values within an SNMP conceptual table is defined in the MIB by the INDEX clause.

This option describes the contents of the index, and how the collector will process them. The following are examples of index definitions.

:::caution An contains attributes from a conceptual table must include either index or augments definition. If both are omitted, the object's attributes must be only scalar values. :::

A single value index:

index:
  - type: Integer
    oid: .1.3.6.1.2.1.2.2.1.1
    name: netif
    syntax: InterfaceIndex

A multi-value index:

index:
  - type: IpAddress
    oid: .1.3.6.1.2.1.14.17.1.1
    name: ospf.lsdb.link_local.lsa.netif # ospfLocalLsdbIpAddress
    syntax: IpAddress
  - type: Integer32
    oid: .1.3.6.1.2.1.14.17.1.2
    name: ospf.lsdb.link_local.lsa.netif # ospfLocalLsdbAddressLessIf
    syntax: InterfaceIndexOrZero
  - type: Integer
    oid: .1.3.6.1.2.1.14.17.1.3
    name: ospf.lsdb.link_local.lsa.type # ospfLocalLsdbType
    syntax: EnumInteger
  - type: IpAddress
    oid: .1.3.6.1.2.1.14.17.1.4
    name: ospf.lsdb.link_local.lsa.lsid # ospfLocalLsdbLsid
    syntax: IpAddressNoSuffix
  - type: IpAddress
    oid: .1.3.6.1.2.1.14.17.1.5
    name: ospf.lsdb.link_local.lsa.router.id # ospfLocalLsdbRouterId
    syntax: IpAddressNoSuffix # RouterID

type

Defines the type of the index value. Valid values are:

  • Integer

  • OctetString

  • ImplicitOctetString

  • ObjectIdentifier

  • ImplicitObjectIdentifier

  • Integer32

  • IpAddress

  • MacAddress

  • Unsigned32

  • Opaque

oid

The OID of the index value's MIB definition.

EXAMPLE: oid: .1.3.6.1.2.1.2.2.1.1

name

The name of the field in the output record to which the value will be assigned.

syntax

The syntax of the value. See below for details on all supported syntax values.

augments (optional)

An object which "augments" another object shares the index definition of that object.

:::caution An contains attributes from a conceptual table must include either index or augments definition. If both are omitted, the object's attributes must be only scalar values. :::

EXAMPLE: augments: IF-MIB::ifEntry

discovery_attribute

The attribute defined in the attributes section which will be inspected to discover all available indices.

attributes

The attributes section contains a list of SNMP MIB values to collect for this object.

oid

The OID of the value's MIB definition.

EXAMPLE: oid .1.3.6.1.2.1.31.1.1.1.6

tag (optional)

Specifies whether the attribute is "tag", also referred to as a "label" or "dimension" by various time-series datastores, or a metric value.

Default: tag: false

name

The name of the field in the output record to which the attribute's value will be assigned.

syntax

The syntax of the value. See below for details on all supported syntax values.

overrides (optional)

A common SNMP pattern is the instrumentation of both 32-bit and 64-bit variations of a value. In such scenarios it is unnecessary to collect both values. For example, when the 64-bit value is available it should be preferred, or "override" the 32-bit version.

This attribute defines the object and attribute that an attribute should override, if available.

EXAMPLE:

overrides:
  object: IF-MIB::ifEntry
  attribute: ifOutOctets

object

The object of the attribute to be overridden.

attribute

The attribute of to be overridden.

rediscover

Defines whether the attribute can trigger a rediscovery, and how the value is evaluated to trigger the rediscovery. Valid values are:

  • OnChange - Any change in the value compared to the previous poll.

  • OnReset - A reduction in the value compared to the previous poll.

Supported syntax Types

The syntax field specifies how the raw SNMP values should be interpreted by the ElastiFlow Unified SNMP Collector. Object index and attribute definitions support the follow syntax values.

SNMPv2-SMI (RFC 2578) Types

syntaxoutput type

Integer

64-bit integer

IntegerAsID

64-bit integer, which may be stored as a string/keyword

Integer32

64-bit integer

UnsignedAsID

64-bit unsigned, which may be stored as a string/keyword

Unsigned32

64-bit unsigned

Gauge32

64-bit unsigned

Counter32

64-bit unsigned

Counter64

64-bit unsigned

OctetString

hex string

ObjectIdentifier

string

IpAddress

IPv4 or IPv6 address, output with .ip.addr suffix added

IpAddressNoSuffix

IPv4 or IPv6 address, output without an added suffix

IpAddressAsID

IPv4 address, output as an IP, which may be stored as a string/keyword

IpAddressAsUnsigned32

IPv4 address, output as a unsigned 32-bit integer

TimeTicks

64-bit unsigned

Opaque

hex string

SNMPv2-TC (RFC 2579) Types

syntaxoutput type

DisplayString

string

PhysAddress

MAC-formatted string

MacAddress

MAC-formatted string, output with .addr suffix added

MacAddressNoSuffix

MAC-formatted string, output without an added suffix

TruthValue

enumerated .value & .state

AutonomousType

string

InstancePointer

string

VariablePointer

string

RowPointer

string

RowStatus

enumerated ID & name

TimeStamp

duration normalized to EF_PROCESSOR_DURATION_PRECISION

TimeInterval

duration normalized to EF_PROCESSOR_DURATION_PRECISION

DateAndTime

timestamp normalized to EF_PROCESSOR_TIMESTAMP_PRECISION

StorageType

enumerated ID & name

TDomain

string

TAddress

hex string

FLOAT-TC-MIB (RFC 6340) Types

syntaxoutput type

Float32

64-bit float

Float64

64-bit float

HCNUM-TC (RFC 2856) Types

syntaxoutput type

CounterBasedGauge64

64-bit unsigned

ZeroBasedCounter64

64-bit unsigned

Common MIB-defined Types

syntaxoutput type

IanaL4Proto

enumerated .id & .name

IanaSafi

enumerated .id & .name

IANAifType

enumerated .id & .name

InterfaceIndex

output with .index suffix added

InterfaceIndexOrZero

output with .index suffix added

InetAddressType

enumerated .id & .name

InetVersion

enumerated .id & .name

Enumerated Types

syntaxoutput type

EnumBitmap

enumerated .bits & .tags - see Enumerations

EnumInteger

enumerated .id & .name - see Enumerations

EnumIntegerKeepID

enumerated .id & .name - see Enumerations

EnumObjectIdentifier

enumerated .oid & .name - see Enumerations

EnumObjectIdentifierKeepOID

enumerated .oid & .name - see Enumerations

Unit Types

Unit types can be defined for any attribute with an underlying type of Integer, Integer32, Unsigned32, Gauge32, Counter32, Counter64, Float32 or Float64.

Bandwidth Types

Bandwidth types are normalized to bits/sec and output as a 64-bit unsigned value.

syntaxdescription

BandwidthBits

bits

BandwidthKBits

kilobits (1000 bits)

BandwidthMBits

megabits (1000000 bits)

BandwidthGBits

gigabits (1000000000 bits)

BandwidthTBits

terabits (1000000000000 bits)

BandwidthBytes

bytes (8 bits)

BandwidthKBytes

kilobytes (8000 bits)

BandwidthMBytes

megabytes (8000000 bits)

BandwidthGBytes

gigabytes (8000000000 bits)

BandwidthTBytes

terabytes (8000000000000 bits)

Byte Types

Byte types are normalized to bytes and output as a 64-bit unsigned value.

syntaxdescription

BytesB

bytes

BytesB4

4-byte units

BytesKB

kilobytes (1000 bytes)

BytesMB

megabytes (1000000 bytes)

BytesGB

gigabytes (1000000000 bytes)

BytesTB

terabytes (1000000000000 bytes)

BytesKiB

kibibytes (1024 bytes)

BytesMiB

mebibytes (1048576 bytes)

BytesGiB

gibibytes (1073741824 bytes)

BytesTiB

tibibytes (1099511627776 bytes)

Decibel Types

Decibel types are normalized to decibels and output as a 64-bit float value.

syntaxdescription

Decibel

decibels

Signal Level Types

Signal Level types are normalized to dBm and output as a 64-bit float value.

syntaxdescription

SignalDBm

dBm

SignalDeciDBm

1/10th of a dBm

SignalCentiDBm

1/100th of a dBm

SignalMilliDBm

1/1000th of a dBm

Current Types

Current types are normalized to amps and output as a 64-bit float value.

syntaxdescription

CurrentKiloAmp

kiloamps

CurrentAmp

amps

CurrentDeciAmp

1/10th of an amp

CurrentCentiAmp

1/100th of an amp

CurrentMilliAmp

milliamps

CurrentMicroAmp

microamps

CurrentNanoAmp

nanoamps

Energy Types

Energy types are normalized to joules and output as a 64-bit float value.

syntaxdescription

EnergyGigaJoule

gigajoules

EnergyMegaJoule

megajoules

EnergyKiloJoule

kilojoules

EnergyJoule

joules

EnergyDeciJoule

1/10th of a joule

EnergyCentiJoule

1/100th of a joule

EnergyMilliJoule

millijoules

EnergyMicroJoule

microjoules

EnergyNanoJoule

nanojoules

Timestamp Types

Timestamp types are normalized to a quantity of time units since epoch, as specified by EF_PROCESSOR_TIMESTAMP_PRECISION, and output as a 64-bit unsigned value.

syntaxdescription

EpochSec

seconds since epoch

EpochDeciSec

1/10ths of a second since epoch

EpochCentiSec

1/100ths of a second since epoch

EpochMilliSec

milliseconds since epoch

EpochMicroSec

microseconds since epoch

EpochNanoSec

nanoseconds since epoch

Frequency Types

Frequency types are normalized to hertz and output as a 64-bit float value.

syntaxdescription

FreqGHz

gigahertz

FreqMHz

megahertz

FreqKHz

kilohertz

FreqHz

hertz

FreqDeciHz

decihertz

FreqCentiHz

centihertz

FreqMilliHz

millihertz

Length Types

Length types are normalized to meters and output as a 64-bit float value.

syntaxdescription

LengthKiloMeter

kilometers

LengthMeter

meters

LengthDeciMeter

decimeters

LengthCentiMeter

centimeters

LengthMilliMeter

millimeters

LengthMicroMeter

micrometers

LengthNanoMeter

nanometers

Operation Duration Types

Operation Duration types are normalized to nanoseconds and output as a 64-bit float value.

syntaxdescription

OpTicksSec

seconds

OpTicksDeciSec

1/10ths of a second

OpTicksCentiSec

1/100ths of a second

OpTicksMilliSec

milliseconds

OpTicksHundredMicroSec

100 microseconds

OpTicksTenMicroSec

10 microseconds

OpTicksMicroSec

microseconds

OpTicksHundredNanoSec

100 nanoseconds

OpTicksTenNanoSec

10 nanoseconds

OpTicksNanoSec

nanoseconds

OpTicksHundredPicoSec

100 picoseconds

OpTicksTenPicoSec

10 picoseconds

OpTicksPicoSec

picoseconds

Percentage Types

Percentage types are normalized to either a 0-1 or 0-100 based percentage, as specified by EF_PROCESSOR_PERCENT_NORM, and output as a 64-bit float value.

syntaxdescription

Percent1

0-1 based percentage

PercentDeci1

0-1 based percentage in 1/10ths of a percent

PercentCenti1

0-1 based percentage in 1/100ths of a percent

PercentMilli1

0-1 based percentage in 1/1000ths of a percent

Percent100

0-100 based percentage

PercentDeci100

0-100 based percentage in 1/10ths of a percent

PercentCenti100

0-100 based percentage in 1/100ths of a percent

PercentMilli100

0-100 based percentage in 1/1000ths of a percent

Power Types

Power types are normalized to watts and output as a 64-bit float value.

syntaxdescription

PowerGigaWatt

gigawatts

PowerMegaWatt

megawatts

PowerKiloWatt

kilowatts

PowerWatt

watts

PowerDeciWatt

deciwatts

PowerCentiWatt

centiwatts

PowerMilliWatt

milliwatts

PowerMicroWatt

microwatts

PowerNanoWatt

nanowatts

Rate Types

Rate types are normalized to quantity/sec and output as a 64-bit float value.

syntaxdescription

RateMin

a quantity per minute

RateSec

a quantity per second

RateDeciSec

a quantity per 1/10th of a second

RateCentiSec

a quantity per 1/100th of a second

RateMilliSec

a quantity per millisecond

RateMicroSec

a quantity per microsecond

RateNanoSec

a quantity per nanosecond

Temperature Types

Temperature types are normalized to degrees celsius and output as a 64-bit float value.

syntaxdescription

TemperatureC

degrees celsius

TemperatureDeciC

1/10th degrees celsius

TemperatureCentiC

1/100th degrees celsius

TemperatureMilliC

1/1000th degrees celsius

Duration Types

Duration types are normalized to a quantity of time units, as specified by EF_PROCESSOR_DURATION_PRECISION, and output as a 64-bit unsigned value.

syntaxdescription

TicksMin

minutes

TicksSec

seconds

TicksDeciSec

1/10ths of a second

TicksCentiSec

1/100ths of a second

TicksMilliSec

milliseconds

TicksMicroSec

microseconds

TicksNanoSec

nanoseconds

Voltage Types

Voltage types are normalized to volts and output as a 64-bit float value.

syntaxdescription

VoltageKiloVolt

kilovolts

VoltageVolt

volts

VoltageDeciVolt

1/10ths of a volt

VoltageCentiVolt

1/100ths of a volt

VoltageMilliVolt

millivolts

VoltageMicroVolt

microvolts

VoltageNanoVolt

nanovolts

Wavelength Types

Wavelength types are normalized to nanometers and output as a 64-bit float value.

syntaxdescription

WavelengthKiloMeter

kilometers

WavelengthMeter

meters

WavelengthDeciMeter

decimeters

WavelengthCentiMeter

centimeters

WavelengthMilliMeter

millimeters

WavelengthMicroMeter

micrometers

WavelengthNanoMeter

meters