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 Unified SNMP Collector. Object index and attribute definitions support the follow syntax values.

SNMPv2-SMI (RFC 2578) Types

syntax	output 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

syntax	output 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

syntax	output type
Float32	64-bit float
Float64	64-bit float

HCNUM-TC (RFC 2856) Types

syntax	output type
CounterBasedGauge64	64-bit unsigned
ZeroBasedCounter64	64-bit unsigned

Common MIB-defined Types

syntax	output 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

syntax	output 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.

syntax	description
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.

syntax	description
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.

syntax	description
Decibel	decibels

Signal Level Types

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

syntax	description
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.

syntax	description
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.

syntax	description
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.

syntax	description
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.

syntax	description
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.

syntax	description
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.

syntax	description
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.

syntax	description
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.

syntax	description
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.

syntax	description
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.

syntax	description
TemperatureC	degrees celsius
TemperatureDeciC	1/10th degrees celcius
TemperatureCentiC	1/100th degrees celcius
TemperatureMilliC	1/1000th degrees celcius

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.

syntax	description
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.

syntax	description
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.

syntax	description
WavelengthKiloMeter	kilometers
WavelengthMeter	meters
WavelengthDeciMeter	decimeters
WavelengthCentiMeter	centimeters
WavelengthMilliMeter	millimeters
WavelengthMicroMeter	micrometers
WavelengthNanoMeter	meters