SNMP traps data source

SNMP traps are a standard way to notify your network central management of significant issues and events in your network infrastructure.

Dynatrace provides you with a framework to extend your insights into data related to SNMP traps issued in your infrastructure.

We assume the following:

Your devices are capable of issuing SNMP traps
You know how to configure those devices to send traps and have authority to do so
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.236+
ActiveGate version 1.235+

Supported SNMP versions

SNMP v2c
SNMP v1

Supported authentication

SNMP v2c and SNMP v1 support only community authentication.

Define data scope

By their nature, traps are events, but this version of the SNMP traps data source doesn't support event forwarding. The SNMP traps data source is currently limited to reporting a single metric that counts the number of traps sent by a defined source during a defined interval. The only elements that you can declare for SNMP traps extensions are:

Extension name
Extension version
Frequency of metric collection (interval)
Metric name
Two available dimensions: trap sender and trap OID

Example YAML definition file

yaml
name: custom:snmptraps-extension-example
version: 1.0.0
minDynatraceVersion: "1.235"
author:
    name: Dynatrace SNMP traps data source team
snmptraps:
    - group: generic
      interval:
          minutes: 1
      featureSet: basic
      dimensions:
         - key: host_ip
           value: const:sender
         - key: trap_oid
           value: const:trapOID
      metrics:
         - key: number-of-traps-received
           value: calculated
           type: count,delta

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

Dimensions

To define a dimension, provide its key and value.

Dimension key

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

Dimension value

SNMP traps currently provide you with just two possible dimensions:

The IP address of the host sending the trap (value: const:trapOID)
The trap OID (const:trapOID)

For example:

yaml
dimensions:
  - key: host_ip
    value: const:sender
  - key: trap_oid
    value: const:trapOID

Metrics

SNMP traps collect just one metric that counts the number of traps sent by a source defined in your monitoring configuration during a defined interval. Your only customization option is to provide its key.

For example:

yaml
metrics:
  - key: myExtension.number-of-traps-received
    value: calculated
    type: count,delta

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

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.

Feature set

Feature sets are categories into which you organize the data collected by the extension. For more information, see Feature sets. You can define feature sets at the extension, group, or individual metric level.

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. The maximum interval is 2880 minutes (2 days, 48 hours).

For example:

yaml
interval:
     minutes: 5

Note: This format is supported starting with version 1.217. For earlier versions, use the following format:

yaml
interval: 5m

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.

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:

json
[
  {
    "scope": "ag_group-default",
    "value": {
      "version": "1.0.0",
      "description": "traps from routers",
      "enabled": true,
      "featureSets": [
        "basic"
      ],
      "snmptraps": {
        "sources" : [
          {
            "ip": "172.10.11.0/8",
            "port": 8162,
            "authentication": {
              "community": "x120a1f"
            }
          },
          {
            "ip": "0.0.0.0/0",
            "port": 162,
            "authentication": {
              "community": "public"
            }
          }
        ]
      }
    }
  }
]

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.

The Dynatrace Hub-based extension activation wizard contains a dynamically updated JSON payload with your monitoring configuration

You can also 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:

shell
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.

Scope is the ActiveGate group that will execute the extension. Only one ActiveGate from the group will run this monitoring configuration at a time. 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:

json
"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.

Sources

You have to define the sources of traps in a monitoring configuration. To define a source, add the following details:

The network that sends packets with traps provided in the CDIR notation. To configure a single interface address, add the 32 subnet mask after the IP address, for example 172.10.11.0/32.
UDP port to which traps are sent
Authentication credentials
- Only SNMPv2c and SNMPv1 are supported and they both use authentication with community name

Feature sets

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

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