snmpreceiver

package module
v0.150.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 13, 2026 License: Apache-2.0 Imports: 22 Imported by: 9

README

SNMP Receiver

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

Status
Stability alpha: metrics
Distributions contrib
Issues Open issues Closed issues
Code coverage codecov
Code Owners @tamir-michaeli
Emeritus @StefanKurek

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 attribute 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 attribute 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 in config.go with detailed sample configurations in testdata/config.yaml.

Documentation

Overview

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

Index

Constants

This section is empty.

Variables

This section is empty.

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 used 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 and can be either int or double
	ValueType string `mapstructure:"value_type"`
	// contains filtered or unexported fields
}

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
	// contains filtered or unexported fields
}

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

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"`
	// contains filtered or unexported fields
}

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 and can be either int or double
	ValueType string `mapstructure:"value_type"`
	// contains filtered or unexported fields
}

SumMetric contains info about the value of the sum metric

Source Files

View all Source files

Directories

Path Synopsis
internal
metadata
mocks

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.