snmp

README

SNMP Plugin

The SNMP input plugin gathers metrics from SNMP agents.

Configuration:

See additional SNMP plugin configuration examples here.

Example:

SNMP data:

.1.0.0.0.1.1.0 octet_str "foo"
.1.0.0.0.1.1.1 octet_str "bar"
.1.0.0.0.1.102 octet_str "bad"
.1.0.0.0.1.2.0 integer 1
.1.0.0.0.1.2.1 integer 2
.1.0.0.0.1.3.0 octet_str "0.123"
.1.0.0.0.1.3.1 octet_str "0.456"
.1.0.0.0.1.3.2 octet_str "9.999"
.1.0.0.1.1 octet_str "baz"
.1.0.0.1.2 uinteger 54321
.1.0.0.1.3 uinteger 234

Telegraf config:

[[inputs.snmp]]
  agents = [ "127.0.0.1:161" ]
  version = 2
  community = "public"

  name = "system"
  [[inputs.snmp.field]]
    name = "hostname"
    oid = ".1.0.0.1.1"
    is_tag = true
  [[inputs.snmp.field]]
    name = "uptime"
    oid = ".1.0.0.1.2"
  [[inputs.snmp.field]]
    name = "loadavg"
    oid = ".1.0.0.1.3"
    conversion = "float(2)"

  [[inputs.snmp.table]]
    name = "remote_servers"
    inherit_tags = [ "hostname" ]
    [[inputs.snmp.table.field]]
      name = "server"
      oid = ".1.0.0.0.1.1"
      is_tag = true
    [[inputs.snmp.table.field]]
      name = "connections"
      oid = ".1.0.0.0.1.2"
    [[inputs.snmp.table.field]]
      name = "latency"
      oid = ".1.0.0.0.1.3"
      conversion = "float"

Resulting output:

* Plugin: snmp, Collection 1
> system,agent_host=127.0.0.1,host=mylocalhost,hostname=baz loadavg=2.34,uptime=54321i 1468953135000000000
> remote_servers,agent_host=127.0.0.1,host=mylocalhost,hostname=baz,server=foo connections=1i,latency=0.123 1468953135000000000
> remote_servers,agent_host=127.0.0.1,host=mylocalhost,hostname=baz,server=bar connections=2i,latency=0.456 1468953135000000000

Configuration via MIB:

This example uses the SNMP data above, but is configured via the MIB. The example MIB file can be found in the testdata directory. See the MIB lookups section for more information.

Telegraf config:

[[inputs.snmp]]
  agents = [ "127.0.0.1:161" ]
  version = 2
  community = "public"

  [[inputs.snmp.field]]
    oid = "TEST::hostname"
    is_tag = true

  [[inputs.snmp.table]]
    oid = "TEST::testTable"
    inherit_tags = [ "hostname" ]

Resulting output:

* Plugin: snmp, Collection 1
> testTable,agent_host=127.0.0.1,host=mylocalhost,hostname=baz,server=foo connections=1i,latency="0.123" 1468953135000000000
> testTable,agent_host=127.0.0.1,host=mylocalhost,hostname=baz,server=bar connections=2i,latency="0.456" 1468953135000000000

Config parameters

• agents: Default: [] List of SNMP agents to connect to in the form of IP[:PORT]. If :PORT is unspecified, it defaults to 161.

• version: Default: 2 SNMP protocol version to use.

• community: Default: "public" SNMP community to use.

• max_repetitions: Default: 50 Maximum number of iterations for repeating variables.

• sec_name: Security name for authenticated SNMPv3 requests.

• auth_protocol: Values: "MD5","SHA","". Default: "" Authentication protocol for authenticated SNMPv3 requests.

• auth_password: Authentication password for authenticated SNMPv3 requests.

• sec_level: Values: "noAuthNoPriv","authNoPriv","authPriv". Default: "noAuthNoPriv" Security level used for SNMPv3 messages.

• context_name: Context name used for SNMPv3 requests.

• priv_protocol: Values: "DES","AES","". Default: "" Privacy protocol used for encrypted SNMPv3 messages.

• priv_password: Privacy password used for encrypted SNMPv3 messages.

• name: Output measurement name.

Field parameters:

• oid: OID to get. May be a numeric or textual OID.

• oid_index_suffix: The OID sub-identifier to strip off so that the index can be matched against other fields in the table.

• oid_index_length: Specifies the length of the index after the supplied table OID (in OID path segments). Truncates the index after this point to remove non-fixed value or length index suffixes.

• name: Output field/tag name. If not specified, it defaults to the value of oid. If oid is numeric, an attempt to translate the numeric OID into a texual OID will be made.

• is_tag: Output this field as a tag.

• conversion: Values: "float(X)","float","int","". Default: "" Converts the value according to the given specification.

  • float(X): Converts the input value into a float and divides by the Xth power of 10. Efficively just moves the decimal left X places. For example a value of 123 with float(2) will result in 1.23.
  • float: Converts the value into a float with no adjustment. Same as float(0).
  • int: Convertes the value into an integer.
  • hwaddr: Converts the value to a MAC address.
  • ipaddr: Converts the value to an IP address.

Table parameters:

• oid: Automatically populates the table's fields using data from the MIB.

• name: Output measurement name. If not specified, it defaults to the value of oid. If oid is numeric, an attempt to translate the numeric OID into a texual OID will be made.

• inherit_tags: Which tags to inherit from the top-level config and to use in the output of this table's measurement.

• index_as_tag: Adds each row's index within the table as a tag.

MIB lookups

If the plugin is configured such that it needs to perform lookups from the MIB, it will use the net-snmp utilities snmptranslate and snmptable.

When performing the lookups, the plugin will load all available MIBs. If your MIB files are in a custom path, you may add the path using the MIBDIRS environment variable. See man 1 snmpcmd for more information on the variable.

Documentation

Index

• func Errorf(err error, msg string, format ...interface{}) error
• type Field
• type NestedError
  • func (ne NestedError) Error() string
• type RTable
• type RTableRow
• type Snmp
  • func (s *Snmp) Description() string
  • func (s *Snmp) Gather(acc telegraf.Accumulator) error
  • func (s *Snmp) SampleConfig() string
• type Table
  • func (t Table) Build(gs snmpConnection, walk bool) (*RTable, error)

Functions

func Errorf

func Errorf(err error, msg string, format ...interface{}) error

Errorf is a convenience function for constructing a NestedError.

Types

type Field

type Field struct {
	// Name will be the name of the field.
	Name string
	// OID is prefix for this field. The plugin will perform a walk through all
	// OIDs with this as their parent. For each value found, the plugin will strip
	// off the OID prefix, and use the remainder as the index. For multiple fields
	// to show up in the same row, they must share the same index.
	Oid string
	// OidIndexSuffix is the trailing sub-identifier on a table record OID that will be stripped off to get the record's index.
	OidIndexSuffix string
	// OidIndexLength specifies the length of the index in OID path segments. It can be used to remove sub-identifiers that vary in content or length.
	OidIndexLength int
	// IsTag controls whether this OID is output as a tag or a value.
	IsTag bool
	// Conversion controls any type conversion that is done on the value.
	//  "float"/"float(0)" will convert the value into a float.
	//  "float(X)" will convert the value into a float, and then move the decimal before Xth right-most digit.
	//  "int" will conver the value into an integer.
	//  "hwaddr" will convert a 6-byte string to a MAC address.
	//  "ipaddr" will convert the value to an IPv4 or IPv6 address.
	Conversion string
	// contains filtered or unexported fields
}

Field holds the configuration for a Field to look up.

type NestedError

type NestedError struct {
	// Err is the error from where the NestedError was constructed.
	Err error
	// NestedError is the error that was passed back from the called function.
	NestedErr error
}

NestedError wraps an error returned from deeper in the code.

func (NestedError) Error

func (ne NestedError) Error() string

Error returns a concatenated string of all the nested errors.

type RTable

type RTable struct {
	// Name is the name of the field, copied from Table.Name.
	Name string
	// Time is the time the table was built.
	Time time.Time
	// Rows are the rows that were found, one row for each table OID index found.
	Rows []RTableRow
}

RTable is the resulting table built from a Table.

type RTableRow

type RTableRow struct {
	// Tags are all the Field values which had IsTag=true.
	Tags map[string]string
	// Fields are all the Field values which had IsTag=false.
	Fields map[string]interface{}
}

RTableRow is the resulting row containing all the OID values which shared the same index.

type Snmp

type Snmp struct {
	// The SNMP agent to query. Format is ADDR[:PORT] (e.g. 1.2.3.4:161).
	Agents []string
	// Timeout to wait for a response.
	Timeout internal.Duration
	Retries int
	// Values: 1, 2, 3
	Version uint8

	// Parameters for Version 1 & 2
	Community string

	// Parameters for Version 2 & 3
	MaxRepetitions uint8

	// Parameters for Version 3
	ContextName string
	// Values: "noAuthNoPriv", "authNoPriv", "authPriv"
	SecLevel string
	SecName  string
	// Values: "MD5", "SHA", "". Default: ""
	AuthProtocol string
	AuthPassword string
	// Values: "DES", "AES", "". Default: ""
	PrivProtocol string
	PrivPassword string
	EngineID     string
	EngineBoots  uint32
	EngineTime   uint32

	Tables []Table `toml:"table"`

	// Name & Fields are the elements of a Table.
	// Telegraf chokes if we try to embed a Table. So instead we have to embed the
	// fields of a Table, and construct a Table during runtime.
	Name   string
	Fields []Field `toml:"field"`
	// contains filtered or unexported fields
}

Snmp holds the configuration for the plugin.

func (*Snmp) Description

func (s *Snmp) Description() string

Description returns a one-sentence description on the input.

func (*Snmp) Gather

func (s *Snmp) Gather(acc telegraf.Accumulator) error

Gather retrieves all the configured fields and tables. Any error encountered does not halt the process. The errors are accumulated and returned at the end.

func (*Snmp) SampleConfig

func (s *Snmp) SampleConfig() string

SampleConfig returns the default configuration of the input.

type Table

type Table struct {
	// Name will be the name of the measurement.
	Name string

	// Which tags to inherit from the top-level config.
	InheritTags []string

	// Adds each row's table index as a tag.
	IndexAsTag bool

	// Fields is the tags and values to look up.
	Fields []Field `toml:"field"`

	// OID for automatic field population.
	// If provided, init() will populate Fields with all the table columns of the
	// given OID.
	Oid string
	// contains filtered or unexported fields
}

Table holds the configuration for a SNMP table.

func (Table) Build

func (t Table) Build(gs snmpConnection, walk bool) (*RTable, error)

Build retrieves all the fields specified in the table and constructs the RTable.