snmpreceiver

README

SNMP Receiver

Status
Stability	alpha: metrics
Distributions	contrib
Issues
Code Owners	@djaglowski, @StefanKurek, @tamir-michaeli

This receiver fetches stats from a SNMP enabled host using a golang snmp client. Metrics are collected based upon different configurations in the config file.

Purpose

The purpose of this receiver is to allow users to generically monitor metrics using SNMP.

If one of the specified SNMP data values cannot be loaded on startup, a warning will be printed, but the application will not fail fast.

Prerequisites

This receiver supports SNMP versions:

• v1
• v2c
• v3

Configuration

Connection Configuration

These configuration options are for connecting to a SNMP host.

• collection_interval: (default = 10s): This receiver collects metrics on an interval. This value must be a string readable by Golang's time.ParseDuration. Valid time units are ns, us (or µs), ms, s, m, h.
• timeout: (default: 5s): Timeout for each SNMP request. This value must be a string readable by Golang's time.ParseDuration. Valid time units are ns, us (or µs), ms, s, m, h.
• endpoint (default: udp://localhost:161): SNMP endpoint to connect to in the form of [udp|tcp][://]{host}[:{port}]
  • If no scheme is supplied, a default of udp is assumed
  • If no port is supplied, a default of 161 is assumed
• version: (default = v2c): SNMP version options are
  • v1: SNMP version 1
  • v2c: SNMP version 2c
  • v3: SNMP version 3
• community: (default = public): The community string for the SNMP connection. This is not available for SNMP version v3.
• user: The user for the SNMP connection. This is only available for SNMP version v3.
• security_level: (default = no_auth_no_priv): The security requirements of the SNMP connection. This is only available for SNMP version v3. SNMP security_level options are
  • no_auth_no_priv: No authentication protocol and no privacy protocol used
  • auth_no_priv: Authentication protocol is used but no privacy protocol used
  • auth_priv: Both authentication and privacy protocols are used
• auth_type: (default = MD5): The authentication protocol used for the SNMP connection. This is only available if security_level is not set to no_auth_no_priv. SNMP auth_type options are
  • MD5
  • SHA
  • SHA224
  • SHA256
  • SHA384
  • SHA512
• auth_password: The authentication password used for the SNMP connection. This is only available if security_level is not set to no_auth_no_priv.
• privacy_type: (default = DES): The privacy protocol used for the SNMP connection. This is only available if security_level is set to auth_priv. SNMP privacy_type options are
  • DES
  • AES
  • AES192
  • AES256
  • AES192c
  • AES256c
• privacy_password: The privacy password used for the SNMP connection. This is only available if security_level is set to auth_priv.

Metric/Attribute Configuration

These configuration options are for determining what metrics and attributes will be created with what SNMP data

• resource_attributes: This may be configured with one or more key value pairs of resource attribute names and resource attribute configurations.
• attributes This may be configured with one or more key value pairs of attribute names and attribute configurations
• metrics: This is the only required parameter. The must be configured with one or more key value pairs of metric names and metric configuration.

Resource Attribute Configuration

Resource attribute configurations are used to define what resource attributes will be used in a collection.

Field Name	Description	Value
oid	Required if no scalar_oid or indexed_value_prefix. This is the column OID in a SNMP table which will use the returned indexed SNMP data to create resource attribute values for unique resources. Metric configurations will reference these resource attribute configurations in order to assign metrics data to resources	string
scalar_oid	Required if no oid or indexed_value_prefix. This is the scalar OID which will return non-indexed SNMP data to create resource attribute values for unique resources. Metric configurations will reference these resource attribute configurations in order to assign metrics data to resources	string
indexed_value_prefix	Required if no scalar_oid or oid. This is a string prefix which will be added to the indices of returned metric indexed SNMP data to create resource attribute values for unique resources. Metric configurations will reference these resource attribute configurations in order to assign metrics data to resources	string
description	Definition of what the resource attribute represents	string

Attribute Configuration

Attribute configurations are used to define what resource attributes will be used in a collection.

Field Name	Description	Value
oid	Required if no indexed_value_prefix or enum. This is the column OID in a SNMP table which will use the returned indexed SNMP data to create attribute values for the attribute. Metric configurations will reference these attribute configurations in order to assign these attributes and indexed data values to metrics and their datapoints	string
indexed_value_prefix	Required if no oid or enum. This is a string prefix which will be added to the indices of returned metric indexed SNMP data to create attribute values the attribute. Metric configurations will reference these attribute configurations in order to assign these attributes and index based value to metrics and their datapoints	string
enum	Required if no oid or indexed_value_prefix. This should be a list of values that are possible for this attribute. Metric configurations will reference these attribute configurations in order to assign these attributes and values to metrics and their datapoints	string[]
description	Definition of what the attribute represents	string

Metric Configuration

Field Name	Description	Value	Default
unit	Required. To display what is actually being measured for this metric	string	1
gauge	Required if no sum. Details that this metric is of the gauge type	GaugeMetric
sum	Required if no gauge. Details that this metric is of the sum type	SumMetric
column_oids	Required if no scalar_oids. Details that this metric is made from one or more columns in an SNMP table. The returned indexed SNMP data for these OIDs might either be datapoints on a single metrics, or datapoints across multiple metrics attached to different resources depending on the column OID configurations	ColumnOID[]
scalar_oids	Required if no column_oids. Details that this metric is made from one or more scalard SNMP values (multiple scalar OIDs would represent multiple datapoints within the same metric)	ScalarOID[]
description	Definition of what the metric represents	string

GaugeMetric Configuration

Field Name	Description	Value	Default
value_type	The value type of this metric's data. Can be either int or double	string	double

SumMetric Configuration

Field Name	Description	Value	Default
value_type	The value type of this metric's data. Can be either int or double	string	double
monotonic	Whether this is a monotonic sum or not	bool	false
aggregation	The aggregation type of this metric's data. Can be either cumulative or delta	string	cumulative

ScalarOID Configuration

Field Name	Description	Value	Default
oid	The SNMP scalar OID value to grab data from (must end in .0).	string
resource_attributes	The names of the related resource attribute configurations, allowing scalar oid metrics to be added to resources that have one or more scalar oid resource attributes. Cannot have indexed resource attributes as values.	string[]
attributes	The names of the related attribute enum configurations as well as the values to attach to this returned SNMP scalar data. This can be used to have a metric config with multiple ScalarOIDs as different datapoints with different attributue values within the same metric	Attribute

ColumnOID Configuration

Field Name	Description	Value	Default
oid	The SNMP scalar OID value to grab data from (must end in .0).	string
attributes	The names of the related attribute configurations as well as the enum values to attach to this returned SNMP indexed data if the attribute configuration has enum data. This can be used to attach a specific metric SNMP column OID to an attribute. In doing so, multiple datapoints for a single metric will be created for each returned SNMP indexed data value for the metric along with different attribute values to differentiate them. This also can be used to have a metric config with multiple ColumnOIDs as different datapoints with different attributue values within the same metric	Attribute[]
resource_attributes	The names of the related resource attribute configurations. This is used to attach a specific metric SNMP column OID to a resource attribute. In doing so, multiple resources will be created for each returned SNMP indexed data value for the metric	string[]

Attribute

Field Name	Description	Value	Default
name	The name of the attribute configuration that this data refers to	string
value	If the referred to attribute configuration is of enum type, the specific enum value that should be used for this specific attribute	string

Example Configuration

receivers:
  snmp:
    collection_interval: 60s
    endpoint: udp://localhost:161
    version: v3
    security_level: auth_priv
    user: otel
    auth_type: "MD5"
    auth_password: ${env:SNMP_AUTH_PASSWORD}
    privacy_type: "DES"
    privacy_password: ${env:SNMP_PRIVACY_PASSWORD}

    resource_attributes:
      resource_attr.name.1:
        indexed_value_prefix: probe
      resource_attr.name.2:
        oid: "1.1.1.1"

    attributes:
      attr.name.1:
        value: a2_new_key
        enum:
          - in
          - out
      attr.name.2:
        indexed_value_prefix: device
      attr.name.3:
        oid: "2.2.2.2"

    metrics:
      # This metric will have multiple datapoints wil 1 attribute on each.
      # Each datapoint will have a (hopefully) different attribute value
      metric.name.1:
        unit: "1"
        sum:
          aggregation: cumulative
          monotonic: true
          value_type: int
        column_oids:
          - oid: "2.2.2.1"
            attributes:
              - name: attr.name.3
      # This metric will have multiple datapoints with 2 attributes on each.
      # Each datapoint will have a guaranteed different attribute indexed value for 1 of the attributes.
      # Half of the datapoints will have the other attribute with a value of "in".
      # The other half will have the other attribute with a value of "out".
      metric.name.2:
        unit: "By"
        gauge:
          value_type: int
        column_oids:
          - oid: "3.3.3.3"
            attributes:
              - name: attr.name.2
              - name: attr.name.1
                value: in
          - oid: "2"
            attributes:
              - name: attr.name.2
              - name: attr.name.1
                value: out
      # This metric will have 2 datapoints with 1 attribute on each
      # One datapoints will have an attribute value of "in".
      # The other will have an attribute value of "out".
      metric.name.3:
        unit: "By"
        sum:
          aggregation: delta
          monotonic: false
          value_type: double
        scalar_oids:
          - oid: "4.4.4.4.0"
            attributes:
              - name: attr.name.1
                value: in
          - oid: "4.4.4.5.0"
            attributes:
              - name: attr.name.1
                value: out
      # This metric will have metrics created with each attached to a different resource.
      # Each resource will have a resource attribute with a guaranteed unique value based on the index.
      metric.name.4:
        unit: "By"
        gauge:
          value_type: int
        column_oids:
          - oid: "5.5.5.5"
            resource_attributes:
              - resource_attr.name.1
      # This metric will have metrics created with each attached to a different resource.
      # Each resource will have a resource attribute with a hopefully unique value.
      metric.name.5:
        unit: "By"
        gauge:
          value_type: int
        column_oids:
          - oid: "1.1.1.2"
            resource_attributes:
              - resource_attr.name.2

The full list of settings exposed for this receiver are documented here with detailed sample configurations here.

Documentation

Overview

Copyright The OpenTelemetry Authors SPDX-License-Identifier: Apache-2.0

Index

• func NewFactory() receiver.Factory
• type Attribute
• type AttributeConfig
• type ColumnOID
• type Config
  • func (cfg *Config) Validate() error
• type GaugeMetric
• type MetricConfig
• type ResourceAttributeConfig
• type SNMPData
• type ScalarOID
• type SumMetric

Functions

func NewFactory

func NewFactory() receiver.Factory

NewFactory creates a new receiver factory for SNMP

Types

type Attribute

type Attribute struct {
	// Name is required and should match the key for an AttributeConfig
	Name string `mapstructure:"name"`
	// Value is optional and is only needed for a matched AttributeConfig's with enum value.
	// Value should match one of the AttributeConfig's enum values in this case
	Value string `mapstructure:"value"`
}

Attribute is a connection between a metric configuration and an AttributeConfig

type AttributeConfig

type AttributeConfig struct {
	// Value is optional, and will allow for a different attribute key other than the attribute name
	Value string `mapstructure:"value"`
	// Description is optional and describes what the attribute represents
	Description string `mapstructure:"description"`
	// Enum is required only if OID and IndexedValuePrefix are not defined.
	// This contains a list of possible values that can be associated with this attribute
	Enum []string `mapstructure:"enum"`
	// OID is required only if Enum and IndexedValuePrefix are not defined.
	// This is the column OID which will provide indexed values to be uased for this attribute (alongside a metric with ColumnOIDs)
	OID string `mapstructure:"oid"`
	// IndexedValuePrefix is required only if Enum and OID are not defined.
	// This is used alongside metrics with ColumnOIDs to assign attribute values using this prefix + the OID index of the metric value
	IndexedValuePrefix string `mapstructure:"indexed_value_prefix"`
}

AttributeConfig contains config info about all of the metric attributes that will be used by this receiver.

type ColumnOID

type ColumnOID struct {
	// OID is required and is the column OID that is associated with a metric
	OID string `mapstructure:"oid"`
	// ResourceAttributes is required only if there are no Attributes associated with non enum
	// AttributeConfigs defined here. Valid values are ResourceAttributeConfig names that will
	// be used to differentiate the indexed values for the column OID
	ResourceAttributes []string `mapstructure:"resource_attributes"`
	// Attributes is required only if there are no ResourceAttributes associated defined here.
	// Valid values are non enum AttributeConfig names that will be used to differentiate the
	// indexed values for the column OID
	Attributes []Attribute `mapstructure:"attributes"`
}

ColumnOID holds OID info for an indexed metric as well as any attributes or resource attributes that are attached to it

type Config

type Config struct {
	scraperhelper.ControllerConfig `mapstructure:",squash"`

	// Endpoint is the SNMP target to request data from. Must be formatted as [udp|tcp|][4|6|]://{host}:{port}.
	// Default: udp://localhost:161
	// If no scheme is given, udp4 is assumed.
	// If no port is given, 161 is assumed.
	Endpoint string `mapstructure:"endpoint"`

	// Version is the version of SNMP to use for this connection.
	// Valid options: v1, v2c, v3.
	// Default: v2c
	Version string `mapstructure:"version"`

	// Community is the SNMP community string to use.
	// Only valid for versions "v1" and "v2c"
	// Default: public
	Community string `mapstructure:"community"`

	// User is the SNMP User for this connection.
	// Only valid for version “v3”
	User string `mapstructure:"user"`

	// SecurityLevel is the security level to use for this SNMP connection.
	// Only valid for version “v3”
	// Valid options: “no_auth_no_priv”, “auth_no_priv”, “auth_priv”
	// Default: "no_auth_no_priv"
	SecurityLevel string `mapstructure:"security_level"`

	// AuthType is the type of authentication protocol to use for this SNMP connection.
	// Only valid for version “v3” and if “no_auth_no_priv” is not selected for SecurityLevel
	// Valid options: “md5”, “sha”, “sha224”, “sha256”, “sha384”, “sha512”
	// Default: "md5"
	AuthType string `mapstructure:"auth_type"`

	// AuthPassword is the authentication password used for this SNMP connection.
	// Only valid for version "v3" and if "no_auth_no_priv" is not selected for SecurityLevel
	AuthPassword configopaque.String `mapstructure:"auth_password"`

	// PrivacyType is the type of privacy protocol to use for this SNMP connection.
	// Only valid for version “v3” and if "auth_priv" is selected for SecurityLevel
	// Valid options: “des”, “aes”, “aes192”, “aes256”, “aes192c”, “aes256c”
	// Default: "des"
	PrivacyType string `mapstructure:"privacy_type"`

	// PrivacyPassword is the authentication password used for this SNMP connection.
	// Only valid for version “v3” and if "auth_priv" is selected for SecurityLevel
	PrivacyPassword configopaque.String `mapstructure:"privacy_password"`

	// ResourceAttributes defines what resource attributes will be used for this receiver and is composed
	// of resource attribute names along with their resource attribute configurations
	ResourceAttributes map[string]*ResourceAttributeConfig `mapstructure:"resource_attributes"`

	// Attributes defines what attributes will be used on metrics for this receiver and is composed of
	// attribute names along with their attribute configurations
	Attributes map[string]*AttributeConfig `mapstructure:"attributes"`

	// Metrics defines what SNMP metrics will be collected for this receiver and is composed of metric
	// names along with their metric configurations
	Metrics map[string]*MetricConfig `mapstructure:"metrics"`
}

Config defines the configuration for the various elements of the receiver.

func (*Config) Validate

func (cfg *Config) Validate() error

Validate validates the given config, returning an error specifying any issues with the config.

type GaugeMetric

type GaugeMetric struct {
	// ValueType is required can can be either int or double
	ValueType string `mapstructure:"value_type"`
}

GaugeMetric contains info about the value of the gauge metric

type MetricConfig

type MetricConfig struct {
	// Description is optional and describes what this metric represents
	Description string `mapstructure:"description"`
	// Unit is required
	Unit string `mapstructure:"unit"`
	// Either Gauge or Sum config is required
	Gauge *GaugeMetric `mapstructure:"gauge"`
	Sum   *SumMetric   `mapstructure:"sum"`
	// Either ScalarOIDs or ColumnOIDs is required.
	// ScalarOIDs is used if one or more scalar OID values is used for this metric.
	// ColumnOIDs is used if one or more column OID indexed set of values is used
	// for this metric.
	ScalarOIDs []ScalarOID `mapstructure:"scalar_oids"`
	ColumnOIDs []ColumnOID `mapstructure:"column_oids"`
}

MetricConfig contains config info about a given metric

type ResourceAttributeConfig

type ResourceAttributeConfig struct {
	// Description is optional and describes what the resource attribute represents
	Description string `mapstructure:"description"`
	// OID is required only if ScalarOID or IndexedValuePrefix is not set.
	// This is the column OID which will provide indexed values to be used for this resource attribute. These indexed values
	// will ultimately each be associated with a different "resource" as an attribute on that resource. Indexed metric values
	// will then be used to associate metric datapoints to the matching "resource" (based on matching indexes).
	OID string `mapstructure:"oid"`
	// ScalarOID is required only if OID or IndexedValuePrefix is not set.
	// This is the scalar OID which will provide a value to be used for this resource attribute.
	// Single or indexed metrics can then be associated with the resource. (Indexed metrics also need an indexed attribute or resource attribute to associate with a scalar metric resource attribute)
	ScalarOID string `mapstructure:"scalar_oid"`
	// IndexedValuePrefix is required only if OID or ScalarOID is not set.
	// This will be used alongside indexed metric values for this resource attribute. The prefix value concatenated with
	// specific indexes of metric indexed values (Ex: prefix.1.2) will ultimately each be associated with a different "resource"
	// as an attribute on that resource. The related indexed metric values will then be used to associate metric datapoints to
	// those resources.
	IndexedValuePrefix string `mapstructure:"indexed_value_prefix"` // required and valid if no oid or scalar_oid field
}

ResourceAttributeConfig contains config info about all of the resource attributes that will be used by this receiver.

type SNMPData

type SNMPData struct {
	// contains filtered or unexported fields
}

SNMPData used for processFunc and is a simpler version of gosnmp.SnmpPDU

type ScalarOID

type ScalarOID struct {
	// OID is required and is the scalar OID that is associated with a metric
	OID string `mapstructure:"oid"`
	// ResourceAttributes is optional and may contain only scalar OID values to associate this metric with
	ResourceAttributes []string `mapstructure:"resource_attributes"`
	// Attributes is optional and may contain names and values associated with enum
	// AttributeConfigs to associate with the value of the scalar OID
	Attributes []Attribute `mapstructure:"attributes"`
}

ScalarOID holds OID info for a scalar metric as well as any {resource} attributes that are attached to it

type SumMetric

type SumMetric struct {
	// Aggregation is required and can be cumulative or delta
	Aggregation string `mapstructure:"aggregation"`
	// Monotonic is required and can be true or false
	Monotonic bool `mapstructure:"monotonic"`
	// ValueType is required can can be either int or double
	ValueType string `mapstructure:"value_type"`
}

SumMetric contains info about the value of the sum metric