Create SNMP extension

Dynatrace provides you with a framework that you can use to extend your observability into data acquired directly from your SNMP monitored devices.

We assume the following:

• You possess sufficient SNMP subject matter expertise to create an SNMP extension.
• You're familiar with Extensions 2.0 basic concepts and the general structure of the extension YAML file.

Prerequisites and support

Learn the prerequisites and scope of the supported technologies. For limits applying to your extension, see Extensions 2.0 limits.

Supported Dynatrace versions

• Dynatrace version 1.215+
• ActiveGate version 1.215+

Supported SNMP versions

• SNMP v2c
• SNMP v3

Supported authentication

SNMP v2c

Community strings.

SNMP v3

Supported authentication protocols

Supported privacy protocols

See SNMP authentication to learn how to define authentication in your monitoring configuration.

Define data scope

Create the definition of the data set to be pulled from your SNMP infrastructure and ingested into Dynatrace by the extension.

Create an inventory of the SNMP object identifiers (OIDs) that you want to reference in your extension (as values for your metrics and dimensions).

In our example, we use an extension collecting data from generic SNMP devices.

yamlcopydownload
name: custom:snmp-example
version: 1.0.0
minDynatraceVersion: "1.217"
author:
  name: Dynatrace

metrics:
  - key: snmp.generic.snmp.in.pkts
  - key: snmp.generic.silentdrops
  - key: snmp.generic.if.lastchange
  - key: snmp.generic.if.in.errors
    

snmp:
  - group: generic-device
    interval:
    minutes: 5
    dimensions:
      - key: snmp.generic.device.address
        value: this:device.address
      - key: snmp.generic.device.port
        value: this:device.port

    subgroups:
      - subgroup: SNMP health
        table: false
        metrics:
          - key: snmp.generic.snmp.in.pkts
            value: oid:1.3.6.1.2.1.11.1.0
            type: count
          - key: snmp.generic.silentdrops
            value: oid:1.3.6.1.2.1.11.31.0
            type: count
      - subgroup: NIC status
        table: true
        dimensions:
          - key: snmp.generic.if.descr
            value: oid:1.3.6.1.2.1.2.2.1.2
          - key: snmp.generic.if.type
            value: oid:1.3.6.1.2.1.2.2.1.3
        metrics:
          - key: snmp.generic.if.lastchange
            value: oid:1.3.6.1.2.1.2.2.1.9
            type: gauge
          - key: snmp.generic.if.in.errors
            value: oid:1.3.6.1.2.1.2.2.1.14
            type: count

dashboards:
  - path: "generic-device-dashboard.json"

Your SNMP monitoring scope definition starts with the snmp YAML node. All the settings under the node pertain to the declared data source type, which in this case is SNMP.

SNMP extensions rely on the OIDs that identify all the MIB objects, including values for metrics and device details.

Dimensions

For each level (extension, group, subgroup), you can define up to 25 dimensions.

For example:

yamlcopydownload
dimensions:
  - key: cisco-catalyst-health.temperature.desc
    value: oid:1.3.6.1.4.1.9.9.13.1.3.1.2

Dimension key

The dimension key string must conform to the metrics ingestion protocol.

Note: For Dynatrace versions 1.215 and 1.217, a dimension node requires the id parameter in place of 'key'. Starting with Dynatrace version 1.219, it is recommended to use the key parameter, as id will be considered as deprecated.

Dimension value

Apart from simply instructing the extension to extract a dimension value from an OID, you can also use the following methods:

• Plain text. Prefix with const:

  yamlcopydownload
  - key: snmp.com.dt.generic.extension.owner
    value: const:Joe.Doe@somedomain.com

• Monitoring configuration defined variable. Prefix with var:. For details, see Variables.

  yamlcopydownload
  - key: snmp.com.dt.generic.activation.tag
    value: var:ext.activationtag

• Monitoring configuration–defined device details, such as device IP address or port. Prefix with this:. Use device.address and device.port.

  yamlcopydownload
  - key: snmp.com.dt.generic.device.address
    value: this:device.address
  - key: snmp.com.dt.generic.device.port
    value: this:device.port

Use variables with dimensions

If you want to make your extension dimension customizable with the data from the monitoring configuration, you can use variables that will be replaced by values passed from the monitoring configuration. You can use variables directly as the dimension value or with filters. To use variables, you must first declare them in your extension YAML file:

yamlcopydownload
vars:
 - id: ifNameFilter
   displayName: Pattern matching interfaces for which metrics should be queried
   type: pattern
 - id: ext.activationtag
   displayName: Extension activation tag
   type: pattern

Then you can reference them in the dimension definition. Prefix the variable name with var.

yamlcopydownload
dimensions:
 - key: interface_description
   value: oid:.1.3.6.1.2.1.2.2.1.2
   filter: var:ifNameFilter
 - key: snmp.com.dt.generic.activation.tag
   value: var:ext.activationtag

Filter extracted dimensions

When extracting the dimension value, you can add filtering logic that will result in reporting only the dimensions matching the filtering criteria.

• Define the filter in the monitoring configuration and pass it to the extension as a variable, which gives you full flexibility without the need to modify the extension

  yamlcopydownload
  filter: var:variableFromActivationConfig

• Report dimensions only for values that start with the string of your choice

  yamlcopydownload
  filter: const:$prefix(xyz)

• Report dimensions only for values that end with the string of your choice

  yamlcopydownload
  filter: const:$suffix(xyz)

• Report dimensions only for values containing a string of your choice

  yamlcopydownload
  filter: const:$contains(xyz)

• Report dimensions only for values that are equal to the string of your choice

  yamlcopydownload
  filter: const:$eq(xyz)

Metrics

For each level (extension, group, subgroup), you can define up to 100 metrics.

For example:

yamlcopydownload
snmp:
  - group: catalyst-health
    featureSet: temperature
    interval: 5m
    dimensions:
      - key: device_name
        value: oid:1.3.6.1.2.1.1.5
      - key: this.device.address
        value: this:device.address
    metrics:
      - key: cisco-catalyst-health.temperature.value
        value: oid:1.3.6.1.4.1.9.9.13.1.3.1.3
        type: gauge
        featureSet: basic
        interval: 5m

Metric key

The metric key string must conform to the metrics ingestion protocol.

Note: For Extension 2.0 schema versions 1.215, a metric node requires the id parameter in place of key. Starting with Extension 2.0 schema version 1.217, it is required to use the key parameter.

Best practices for metric keys

The metrics you ingest into Dynatrace using your extension are just some of the thousands of metrics, built-in and custom, processed by Dynatrace. To make your metrics keys unique and easy to identify in Dynatrace, the best practice is to prefix the metric name with the extension name. This guarantees that the metric key is unique and you can easily appoint a metric to a particular extension in your environment.

Metric value

The OID from which you want to extract metric value.

Type

The Dynatrace Extensions 2.0 framework supports metric payloads in the gauge (gauge) or count value (count) formats. For details, see Metric payload. To indicate the metric type, use the type attribute.

Metric metadata

An Extension can define metadata for each metric available in Dynatrace. For example, you might want to add the metric display name and the unit, both of which can be used for filtering in the Metrics browser.

yamlcopydownload
name: custom:example-extension-name
version: 1.0.0
minDynatraceVersion: "1.218"
author:
  name: Dynatrace

metrics:
  - key: your.metric.name
    metadata:
        displayName: Display name of the metric visible in Metrics browser
        unit: Count

Feature set

Feature sets are categories into which you organize the data collected by the extension. In this example, we create an SNMP extension monitoring your network devices and collecting metrics related to overall packet traffic and transport layer statistics. This is reflected by metrics organization into related feature sets, total traffic and `transport layer statistics".

yamlcopydownload
snmp:
  - group: health
    interval: 5~
    dimensions:
      - key: device_name
        value: oid:1.3.6.1.2.1.1.5
      - key: this.device.address
        value: this:device.address
    subgroups:
    - subgroup: Traffic
      featureSet: total traffic
      metrics:
        - key: outgoing_packets
          value: oid:.1.3.6.1.2.1.11.1
          type: count
        - key: incoming_packets
          value: oid:.1.3.6.1.2.1.11.1
          type: count
    - subgroup: TCP
      featureSet: transport layer statistics
      metrics:
        - key: tcpActiveOpens
          value: oid:1.3.6.1.2.1.6.5.0
          type: count
        - key: tcpPassiveOpens
          value: oid:1.3.6.1.2.1.6.6.0
          type: count
    - subgroup: UDP
      featureSet: transport layer statistics
      metrics:
        - key: udpNoPorts
          value: oid:1.3.6.1.2.1.7.2.0
          type: count
        - key: udpInErrors
          value: oid:1.3.6.1.2.1.7.3.0
          type: count

When activating your extension using monitoring configuration, you can limit monitoring to one of the feature sets.

In highly segmented networks, feature sets can reflect the segments of your environment. Then, when you create monitoring configuration, you can select a feature set and a corresponding ActiveGate group that can connect to this particular segment.

All metrics that aren't categorized into any feature set are considered to be default and are always reported.

Interval

The interval at which the data measurement will be taken. You can define intervals at the group, subgroup, or individual metric level. You can define intervals with the granularity of one minute (for example, 5m). The maximum interval is 2880m (2 days, 48 hours).

For example

yamlcopydownload
snmp:
  - group: snmp-generic
    interval: 5m
    dimensions:
      - key: device_name
        value: oid:1.3.6.1.2.1.1.5
        type: count
    metrics:
      - key: incoming_packets
        value: oid:.1.3.6.1.2.1.11.1
        type: count

Monitoring configuration

After you define the scope of your configuration, you need to identify the network devices you'd like to collect data from and identify the ActiveGates that will execute the extension and connect to your devices.

Make sure that all the ActiveGates from the ActiveGate group you'll define as the scope can connect to a respective data source. You can assign an ActiveGate to a group during installation by using the --set-group-name installation parameter for Linux and Windows, or by configuring your ActiveGate.

The monitoring configuration is a JSON payload defining the connection details, credentials, and feature sets that you want to monitor. For details, see Start monitoring.

Example payload to activate an SNMP extension:

jsoncopydownload
[
 {
    "scope": "ag_group-my-activegate-group",
    "value": {
      "version": "1.0.0",
      "description": "my monitoring configuration",
      "enabled": true,
      "snmp": {
        "devices": [
          {
            "ip": "snmp.company.org",
            "port": 161,
            "timeoutSecs": 5,
            "retries": 0,
            "maxRepetitions": 50,
            "authentication": {
              "type": "SNMPv2c",
              "community": "public"
            }
          }
        ]

      },
      "featureSets": [
        "all"
      ]
    }
  }
]

When you have your initial extension YAML ready, package it, sign it, and upload it to your Dynatrace environment. For details, see Manage extension lifecyle.

Then you can use the Dynatrace API to download the schema for your extension that will help you create the JSON payload for your monitoring configuration.

Use GET an extension schema endpoint.

Issue the following request:

bashcopydownload
curl -X GET "{env-id}.live.dynatrace.com/api/v2/extensions/{extension-name}/{extension-version}/schema" \
   -H "accept: application/json; charset=utf-8" \
   -H "Authorization: Api-Token {api-token}"

Replace {extension-name} and {extension-version} with values from your extension YAML file. A successful call returns the JSON schema.

Scope

Note that each ActiveGate host running your extension needs the root certificate to verify the authenticity of your extension. For more information, see Sign extension.

An ActiveGate group that will execute the extension. Only one ActiveGate from the group will run this monitoring configuration. If you plan to use a single ActiveGate, assign it to a dedicated group. You can assign an ActiveGate to a group during installation with the --set-group-name installation parameter for Linux and Windows, or by configuring your ActiveGate.

Use the following format when defining the ActiveGate group:

jsoncopydownload
"scope": "ag_group-<ActiveGate-group-name>",

Replace <ActiveGate-group-name> with the actual name.

Version

Version of this monitoring configuration. Note that a single extension can run multiple monitoring configurations.

Description

Human-readable description of the specifics of this monitoring configuration.

Enabled

If set to true, the configuration is active and Dynatrace starts monitoring immediately.

Devices

You can define up to 100 devices in a single monitoring configuration. To define a device, add the following details:

• IP address or device name
• Port
• Authentication credentials
  • Type: SNMPv2c or SNMPv3 (note that SNMPv2c by design uses the community authentication)

You can also define the following additional properties for your connection:

• timeoutSecs
  The maximum time (in seconds) to wait for an SNMP query to return data. 2 seconds by default.
• retries The maximum number of retries for a query if it fails (total time for a query is timeoutSecs x retries). 3 retries by default.
• maxRepetitions
  Can be used to limit the amount of data returned for a single query and might in turn increase the number of requests sent to the device until all required data is collected. 50 repetitions by default.

Authentication

Authentication details passed to Dynatrace API when activating monitoring configuration are obfuscated and it's impossible to retrieve them.

Depending on the security level, construct the authentication details using one of the examples below. See the list of supported protocols.

jsoncopydownload
{
 "ip": "10.10.10.10",
 "port": 161,
 "authentication": {
 "type": "SNMPv3",
 "userName": "snmptest_SHA_AES256",
 "securityLevel": "AUTH_PRIV",
 "authPassword": "916cb7fe3c80fc273413797bd063b8e320237e6159a47c06278ec818da58e3a4fb5f715bdb63313439f2d5e25a434386b3fe82dd0a643507d7452340b3c56d30=",
 "authProtocol": "SHA512",
 "privPassword": "EAB559FF7A04D73D77FE017271A3250B786FB2FD4DA0D45F60C9BE31311221262DB510A4AEC53A418297FC260DB6C91429880030BCAA8416FA1C2810C8E7B928=",
 "privProtocol": "AES256C"
}

jsoncopydownload
{
 "ip": "10.10.10.10",
 "port": 161,
 "authentication": {
 "type": "SNMPv3",
 "userName": "snmptest_SHA_AES256",
 "securityLevel": "AUTH_NO_PRIV",
 "authPassword": "916cb7fe3c80fc273413797bd063b8e320237e6159a47c06278ec818da58e3a4fb5f715bdb63313439f2d5e25a434386b3fe82dd0a643507d7452340b3c56d30=",
 "authProtocol": "SHA512"
}

jsoncopydownload
{
 "ip": "10.10.10.12",
 "port": 161,
 "authentication": {
 "type": "SNMPv3",
 "userName": "snmptest_SHA_AES256",
 "securityLevel": "NO_AUTH_NO_PRIV"
}

Feature sets

Add a list of feature sets you want to monitor. To report all feature sets, add all.

jsoncopydownload
"featureSets": [
  "basic",
  "advanced"
  ]

Variables

If your extension declares variables, you can define values that will be passed as filters or plain strings to your extension. For more information, see Declare variable.

jsoncopydownload
"vars":
  {
  "ifNameFilter": "$contains(1/1/1)",
  "ifSpeedFilter": "$eq(4294967295)"
  }