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.

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.

This receiver supports SNMP versions:

• v1
• v2c
• v3

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:https://localhost:161): SNMP endpoint to connect to in the form of [udp|tcp][:https://]{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.

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 configurations are used to define what resource attributes will be used in a collection.

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

receivers:
  snmp:
    collection_interval: 60s
    endpoint: udp:https://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.