New component: SNMP Receiver

[tamir-michaeli]

The purpose and use-cases of the new component

The SNMP Receiver will use polling to gather metrics from SNMP agents. Similar to Telegraf's SNMP input plugin

Example configuration for the component

receivers:
  snmp:
    #  format:  targets: ["<scheme:https://><hostname>:<port>"]
    #   scheme:  optional, either udp, udp4, udp6, tcp, tcp4, tcp6.
    #            default is udp
    targets: [] # ["127.0.0.1:161","1.2.3.4:161"]
    version: ""  # [1,2,3]
    interval: "" # in seconds
    community_string: ""

    ## SNMPv3 authentication and encryption options.
    ## Security Name.
    security_name: ""
    ## Authentication protocol; one of "MD5", "SHA", "SHA224", "SHA256", "SHA384", "SHA512" or "".
    auth_protocol: ""
    ## Authentication password.
    auth_password: ""
    ## Security Level; one of "noAuthNoPriv", "authNoPriv", or "authPriv".
    security_level: ""
    ## Context Name.
    context_name: ""
    ## Privacy protocol used for encrypted messages; one of "DES", "AES", "AES192", "AES192C", "AES256", "AES256C", or "".
    ### Protocols "AES192", "AES192", "AES256", and "AES256C" require the underlying net-snmp tools
    ### to be compiled with --enable-blumenthal-aes (http:https://www.net-snmp.org/docs/INSTALL.html)
    privacy_protocol: ""
    ## Privacy password used for encrypted messages.
    privacy_password: ""

    fields:
    - oid:  "" # "RFC1213-MIB::sysUpTime.0"
      name:  "" # Metric name to be used - defaults to OID name 
      tag: ""

    tables:
    - oid: "" # "IF-MIB::ifTable"
      name: "" # Metric name to be used - defaults to OID name 
      tag: "" #will be added to each element of the table

Telemetry data types supported

Metrics.

Sponsor (Optional)

None.

[djaglowski]

I believe @StefanKurek is working on a similar proposal.

One thing I would like to see with such a component is that it is possible to fully define the data model of each metric, similar to how windowsperfcountersreceiver works.

[tamir-michaeli]

@djaglowski something like the following?

    fields:
    - oid:  # "RFC1213-MIB::sysUpTime.0"
      name:  # Metric name to be used - defaults to OID name 
      tag: ""
      sum: # optional - default is gauge
        aggregation: # cumulative/delta
        monotonic: # true/false

    tables:
    - oid: # "IF-MIB::ifTable"
      name: "" # Metric name to be used - defaults to OID name 
      tag: "" #will be added to each element of the table
      fields:
        - oid:  # ""IF-MIB::ifDescr""
          name:  # Metric name to be used - defaults to OID name 
          sum: # optional - default is gauge
            aggregation: # cumulative/delta
            monotonic: # true/false

And maybe @StefanKurek will be interested in being a sponsor?

[StefanKurek]

@tamir-michaeli Hello. I have been working on a possible configuration for a SNMP Receiver. I'll post it here and you can let me know what you think. It's a little different (OTEL First config) than what you proposed (SNMP First config). Let me know what your thoughts are.

Connection Configuration

Parameter	Default	Type	Notes
collection_interval	60s	Duration
endpoint	“localhost:161”	String	Must be formatted as {host}:{port}
version	“v2c”	String	Valid Options: “v1”“v2c”“v3”
community	“public”	String
user		String	Only valid for version “v3”
security_level	“no_auth_no_priv”	String	Only valid for version “v3”Valid Options:“no_auth_no_priv”“auth_no_priv”“auth_priv”
authentication_type	“md5”	String	Only valid for version “v3” and if “no_auth_no_priv” not selected for security_levelValid Options:“md5”“sha”“sha224”“sha256”“sha384”“sha512”
auth_password		String	Only valid if authentication_type specified
privacy_type	“des”	String	Only valid for version “v3” and if “auth_priv” selected for security_levelValid Options:“des”“aes”“aes192”“aes256”“aes192c”“aes256c”
privacy_password		String	Only valid if privacy_type specified

Configuration

snmp:
  collection_interval: <duration> # default = "1m"
  endpoint: <host:port>
  version: <string> # default = “v2c”
  community: <string> # default = “public”

  resource_attributes:
    <attribute name>: # name of attribute
      description: <description>
      type: <type>
   # used to assign return values from one or more indexed OIDs to a resource attribute using
   #   a new indexed OID within the same table
      oid: <OID> # indexed value OID within same table as one or more metric indexed OIDs
    <attribute name>: # name of attribute
      description: <description>
      type: <type>
   # used to assign return values from one or more indexed OIDs to a simple resource attribute 
   #   when no alternate indexed OID attributes are used for resource attributes
   #   Example: 
   #   tech.name:
   #     indexed_value_prefix: probe
   #
   #   might result in a resource attributes of “tech.name: probe1”, “tech.name: probe2”, and 
   #  “tech.name: probe3” being assigned to one each of a metric’s values
      indexed_value_prefix: <attribute value prefix> # required and valid if no oid field

  attributes:
    <attribute name>:
      value: <attribute label> # optional, will match <attribute_name> if not included
      description: <description>
   # used to uniquely label overlapping multiple scalar or indexed oid return values belonging to 
   #   a single metric
      enum: [enum val 1] # required and valid if no oid or indexed_value_prefix fields
    <attribute name>:
      value: <attribute label> # optional, will match <attribute_name> if not included
      description: <description>
   # used to uniquely label indexed oid return values belonging to a single metric using a new
   #   indexed OID within the same table
      oid: <OID> # required and valid if no enum or indexed_value_prefix fields
    <attribute name>:
      value: <attribute label> # optional, will match <attribute_name> if not included
      description: <description>
   # used to uniquely label return values from one or more OIDs belonging to a single metric
   #   when no alternate indexed OID attributes are used for uniquely labeling
   #   Example: 
   #   tech.name:
   #     indexed_value_prefix: probe
   #
   #   might result in attributes of “tech.name: probe1”, “tech.name: probe2”, and 
   #  “tech.name: probe3” being assigned to one each of a metric’s values
      indexed_value_prefix: <attribute value prefix> # required and valid if no enum or oid fields
      
  metrics:
    <metric name>:
      description: <description>
      unit: <unit type>
      gauge:
        value_type: <value type>
   # this would allow for a single metric which can handle multiple OID values, each with a
   # different set of assigned attribute key/values
      scalar_oids:
        - oid: <OID> # scalar OID for simple metric
          attributes: # required unless only a single oid in the array
            # only an “enum” attribute may be used for scalar OID metrics
            - name: <attribute name>
              value: <attribute value> 
    <metric name>:
      description: <description>
      unit: <unit type>
      gauge:
        value_type: <value type>      
      indexed_oids: 
        - oid: <OID> # indexed oid for multiple metric values
          resource_attributes:
            - <attribute name>
          attributes:
            - name: <attribute name>
              value: <attribute value> # this is only required for an enum attribute 
    <metric name>:
      description: <description>
      unit: <unit type>
      sum:
        aggregation: <cumulative or delta>
        monotonic: <true or false>
        value_type: <value type>
      indexed_oids: 
        - oid: <OID> # indexed oid for multiple metric values
          resource_attributes:
            - <attribute name>
          attributes:
            - name: <attribute name>
              value: <attribute value> # this is only required for an enum attribute 

Example:

snmp:
  collection_interval: 1m
  endpoint: 127.0.0.1:161
  version: v2c  
  community: public

  resource_attributes:
    probe.name:
      type: string
      indexed_value_prefix: probe
      description: Used for generically naming the various probes
    
  attributes:
    probe.type:
      value: type
      description: The type of the temperature probe
      oid: “1.3.6.1.4.1.674.10892.5.4.700.20.1.8”
    chassis.index:
      value: chassis_index
      description: The index of the related system chassis
      oid: “1.3.6.1.4.1.674.10892.5.4.700.20.1.1”
    probe.index:
      value: probe_index
      description: The index of the probe
      oid: “1.3.6.1.4.1.674.10892.5.4.700.20.1.2”


  metrics:
    system_chassis_height:
      description: “The standard system chassis height”
      unit: {{U}}
      gauge:
        value_type: int
      scalar_oids:
        - oid: “1.3.6.1.4.1.674.10892.5.1.3.16” 
    probe_temperature:
      description: “The value returned for this attribute is the temperature that the probe is reading in degrees Centigrade”
      unit: Cel
      gauge:
        value_type: int
      indexed_oids:
        - oid: “1.3.6.1.4.1.674.10892.5.4.700.20.1.6”
          resource_attributes:
           - probe.name
          attributes:
            - name: probe.type
            - name: chassis.index
            - name: probe.index
    probe_discrete_temperature:
      description: “The value returned for this attribute is determines whether the probe is reading a good or bad temperature (1 -> good and 2 -> bad)”
      unit: 1
      gauge:
        value_type: int
      indexed_oids:
        - oid: “1.3.6.1.4.1.674.10892.5.4.700.20.1.16”
          resource_attributes:
           - probe.name
          attributes:
            - name: probe.type
            - name: chassis.index
            - name: probe.index

[djaglowski]

@StefanKurek, the config makes sense to me.

@tamir-michaeli, any feedback on this proposal?

[tamir-michaeli]

@djaglowski @StefanKurek Makes more sense than my proposal. Do we have an ETA for it?

[djaglowski]

I'll sponsor this.

Since it's a fairly complex component, would you both be interested in being code owners?

[StefanKurek]

@djaglowski sounds good to me.

@tamir-michaeli I do not currently have an ETA. I may not be able to get to this for a few weeks actually, so if you would like to start on it sooner, I can at least be on the lookout for PRs. Let me know what you think.

[tamir-michaeli]

@StefanKurek Sounds good. I'll start working on it.

[Dylan-M]

I feel like MIB support should be a part of this.

[djaglowski]

I feel like MIB support should be a part of this.

The receiver would useful even without this, but it could be added later.

[StefanKurek]

@tamir-michaeli how is the work going? I was just wondering how close you were to releasing a first PR? I now have some time to devote to this if you need any help, so please let me know. Thanks!

[tamir-michaeli]

@StefanKurek I manage to do some work, but not as much as i wanted (some urgent stuff came in the way), so its mostly a work in progress. I wont be available to work on it for most of next week, but can continue after that.
I created a branch in my local repo, gave you permissions in case you think its a good start.

[djaglowski]

@StefanKurek, I'd be happy to review a PR if you want to make one sooner.

[StefanKurek]

@tamir-michaeli I will start working based off of your branch. Let me know when you have time again and we can sync up.

[tamir-michaeli]

@StefanKurek Im available.

[StefanKurek]

@tamir-michaeli Hello. I have had a few things come up this week, so I am also not as far along as I would have liked, but I do currently have scalar OID metrics with attributes working. I have my work currently in a branch called stefan-snmp-receiver on your fork if you'd like to take a look. I also wrote up a loose plan of work that remains to be done.

I private messaged you on the Cloud Native Computing Foundation Slack to see if you'd like to try and coordinate work going forward. Let me know. Thanks!

[github-actions]

This issue has been inactive for 60 days. It will be closed in 60 days if there is no activity. To ping code owners by adding a component label, see Adding Labels via Comments, or if you are unsure of which component this issue relates to, please ping @open-telemetry/collector-contrib-triagers. If this issue is still relevant, please ping the code owners or leave a comment explaining why it is still relevant. Otherwise, please close it.

[djaglowski]

Closed by PRs linked above.