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 arens
,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 arens
,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
- If no scheme is supplied, a default of
version
: (default =v2c
): SNMP version options arev1
: SNMP version 1v2c
: SNMP version 2cv3
: SNMP version 3
community
: (default =public
): The community string for the SNMP connection. This is not available for SNMP versionv3
.user
: The user for the SNMP connection. This is only available for SNMP versionv3
.security_level
: (default =no_auth_no_priv
): The security requirements of the SNMP connection. This is only available for SNMP versionv3
. SNMPsecurity_level
options areno_auth_no_priv
: No authentication protocol and no privacy protocol usedauth_no_priv
: Authentication protocol is used but no privacy protocol usedauth_priv
: Both authentication and privacy protocols are used
auth_type
: (default =MD5
): The authentication protocol used for the SNMP connection. This is only available ifsecurity_level
is not set tono_auth_no_priv
. SNMPauth_type
options areMD5
SHA
SHA224
SHA256
SHA384
SHA512
auth_password
: The authentication password used for the SNMP connection. This is only available ifsecurity_level
is not set tono_auth_no_priv
.privacy_type
: (default =DES
): The privacy protocol used for the SNMP connection. This is only available ifsecurity_level
is set toauth_priv
. SNMPprivacy_type
options areDES
AES
AES192
AES256
AES192c
AES256c
privacy_password
: The privacy password used for the SNMP connection. This is only available ifsecurity_level
is set toauth_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 configurationsmetrics
: 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 ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewFactory ¶
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.
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 ¶ added in v0.63.0
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