SNMP data source reference
This is a general description of an SNMP data source–based extension YAML file and ways to declare metrics and dimensions you would like to collect using your extension.
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 that collects data from generic SNMP devices.
1name: custom:snmp-example2version: 1.0.03minDynatraceVersion: '1.235'4author:5 name: Dynatrace67metrics:8 - key: snmp.generic.snmp.in.pkts9 - key: snmp.generic.silentdrops10 - key: snmp.generic.if.lastchange11 - key: snmp.generic.if.in.errors1213snmp:14 - group: generic-device15 interval:16 minutes: 517 dimensions:18 - key: snmp.generic.device.address19 value: this:device.address20 - key: snmp.generic.device.port21 value: this:device.port2223 subgroups:24 - subgroup: SNMP health25 table: false26 metrics:27 - key: snmp.generic.snmp.in.pkts28 value: oid:1.3.6.1.2.1.11.1.029 type: count30 - key: snmp.generic.silentdrops31 value: oid:1.3.6.1.2.1.11.31.032 type: count33 - subgroup: NIC status34 table: true35 dimensions:36 - key: snmp.generic.if.descr37 value: oid:1.3.6.1.2.1.2.2.1.238 - key: snmp.generic.if.type39 value: oid:1.3.6.1.2.1.2.2.1.340 metrics:41 - key: snmp.generic.if.lastchange42 value: oid:1.3.6.1.2.1.2.2.1.943 type: gauge44 - key: snmp.generic.if.in.errors45 value: oid:1.3.6.1.2.1.2.2.1.1446 type: count4748dashboards:49 - 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:
1dimensions:2 - key: cisco-catalyst-health.temperature.desc3 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.
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:
1- key: snmp.com.dt.generic.extension.owner2 value: const:Joe.Doe@somedomain.com -
Monitoring configuration defined variable. Prefix with
var:
. For details, see Variables.1- key: snmp.com.dt.generic.activation.tag2 value: var:ext.activationtag -
Monitoring configuration–defined device details, such as device IP address or port. Prefix with
this:
. Usedevice.address
anddevice.port
.1- key: snmp.com.dt.generic.device.address2 value: this:device.address3- key: snmp.com.dt.generic.device.port4 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:
1vars:2 - id: ifNameFilter3 displayName: Pattern matching interfaces for which metrics should be queried4 type: pattern5 - id: ext.activationtag6 displayName: Extension activation tag7 type: pattern
Then you can reference them in the dimension definition. Prefix the variable name with var
.
1dimensions:2 - key: interface_description3 value: oid:.1.3.6.1.2.1.2.2.1.24 filter: var:ifNameFilter5 - key: snmp.com.dt.generic.activation.tag6 value: var:ext.activationtag
Filter extracted dimensions
After you define the filter as a variable, you can add filtering logic that will result in reporting only the dimensions that match the filtering criteria.
1filter: var:ifNameFilter
Define the filter based on a condition as follows:
- Starts with – use a
const:$prefix
qualifier. Example:1filter: const:$prefix(xyz) - Ends with – use a
const:$suffix
qualifier. Example:1filter: const:$suffix(xyz) - Contains - use a
const:$contains
qualifier. Example:1filter: const:$contains(xyz) - Equals – use a
const:$eq
qualifier. Example:1filter: const:$eq(xyz)
Metrics
For each level (extension, group, subgroup), you can define up to 100 metrics.
For example:
1snmp:2 - group: catalyst-health3 featureSet: temperature4 interval:5 minutes: 56 dimensions:7 - key: device_name8 value: oid:1.3.6.1.2.1.1.59 - key: this.device.address10 value: this:device.address11 metrics:12 - key: cisco-catalyst-health.temperature.value13 value: oid:1.3.6.1.4.1.9.9.13.1.3.1.314 type: gauge15 featureSet: basic16 interval:17 minutes: 5
Metric key
The metric key string must conform to the metrics ingestion protocol.
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.
1name: custom:example-extension-name2version: 1.0.03minDynatraceVersion: "1.236"4author:5 name: Dynatrace67metrics:8 - key: your.metric.name9 metadata:10 displayName: Display name of the metric visible in Metrics browser11 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".
1snmp:2 - group: health3 interval:4 minutes: 55 dimensions:6 - key: device_name7 value: oid:1.3.6.1.2.1.1.58 - key: this.device.address9 value: this:device.address10 subgroups:11 - subgroup: Traffic12 featureSet: total traffic13 metrics:14 - key: outgoing_packets15 value: oid:.1.3.6.1.2.1.11.116 type: count17 - key: incoming_packets18 value: oid:.1.3.6.1.2.1.11.119 type: count20 - subgroup: TCP21 featureSet: transport layer statistics22 metrics:23 - key: tcpActiveOpens24 value: oid:1.3.6.1.2.1.6.5.025 type: count26 - key: tcpPassiveOpens27 value: oid:1.3.6.1.2.1.6.6.028 type: count29 - subgroup: UDP30 featureSet: transport layer statistics31 metrics:32 - key: udpNoPorts33 value: oid:1.3.6.1.2.1.7.2.034 type: count35 - key: udpInErrors36 value: oid:1.3.6.1.2.1.7.3.037 type: count
When activating your extension using monitoring configuration, you can limit monitoring to one of the feature sets. To work properly the extension has to collect at least one metric after the activation.
In highly segmented networks, feature sets can reflect the segments of your environment. Then, when you create a 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 the default and are always reported.
A metric inherits the feature set of a subgroup, which in turn inherits the feature set of a group. Also, the feature set defined on the metric level overrides the feature set defined on the subgroup level, which in turn overrides the feature set defined on the group level.
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:
1interval:2 minutes: 5
The above format is supported starting with schema version 1.217. For earlier schema versions, use the following format (supported up to schema version 1.251):
1interval: 5m
For example
1snmp:2 - group: snmp-generic3 interval:4 minutes: 55 dimensions:6 - key: device_name7 value: oid:1.3.6.1.2.1.1.58 metrics:9 - key: incoming_packets10 value: oid:.1.3.6.1.2.1.11.1
MIB files
Management Information Base (MIB) is the database managing the entities in a network identified by OIDs. MIB provides a source of additional information related to OIDs declared in your extension.
ActiveGate comes with a default set of MIB files. You can also extend the default set with your own files.
OID resolution
If the MIB files accessible to the extension contain appropriate information, you can declare OIDs using their names instead of OID numeric values. For example:
1subgroups:2 - subgroup: Device health (Temperature)3 table: true4 dimensions:5 - key: envmon.temperature.desc6 value: oid:ciscoEnvMonTemperatureStatusDescr7 metrics:8 - key: envmon.temperature.value9 value: oid:ciscoEnvMonTemperatureStatusValue10 name: The current testpoint temperature (deg Celsius)11 type: gauge
Network address resolution
An IP address returned from an OID can be automatically resolved to a string in the IPv4 or IPv6 format. A MIB file determines which format to use.
For example, the OID 1.3.6.1.4.1.3375.2.2.10.1.2.1.3
(ltmVirtualServAddr
), virtual server IP address, is returned as a binary (hex) value. With MIB, it's reported in IPv4 or IPv6 format, as determined by the information from ltmVitualServAddrType
.
1subgroups:2 - subgroup: virtualServer3 table: true4 dimensions:5 - key: ltmvirtualserveraddrvalue6 value: oid:1.3.6.1.4.1.3375.2.2.10.1.2.1.3
Enumerated value translation
When an OID is an enumerated type, the extension reports the OID value as a string with a name rather than just a number.
For example, the OID 1.3.6.1.2.1.2.2.1.7
(ifAdminStatus
) is an enumerated type with possible values (1-up, 2-down, 3-testing)
. With MIB, the extension will report the full string as its value (for example, 1-up
instead of 1
) for an interface with the up
state.
Add your own MIB file
If some of the OIDs from your extension are not available in the default MIB files, you can add your own MIB file to the extension.
Ship the MIB file with your extension
Create the snmp
directory next to your extension.yaml
and place the MIB file there. For example:
1extension.zip2│ extension.yaml3│4└───alerts5│ | alert.json6│7└───dashboards8| │ dashboard.json9|10└───snmp11│ | IF-MIB.txt
Missing information is logged and the original value is reported. For example, if the data source is unable to determine the network address type based on available MIB files, the log throws the following message and the hex value is reported.
1"inetAddress translation: Unable to find inetAddress type. X, dimension: Y"`.
MIB file locations
Default MIB files are saved in:
- Linux:
/opt/dynatrace/remotepluginmodule/agent/res/mib-files
- Windows:
C:\%PROGRAMFILES%\dynatrace\remotepluginmodule\agent\res\mib-files
A MIB file added to the extension is saved in:
- Linux:
/var/lib/dynatrace/remotepluginmodule/agent/runtime/datasources/working_directories/[ID]/snmp
- Windows:
C:\%PROGRAMDATA%\dynatrace\remotepluginmodule\agent\runtime\datasources\working_directories\[ID]\snmp
where [ID]
is a string containing the monitoring configuration identifier and timestamp.
Custom MIB ActiveGate directory
Alternatively, you can add your custom MIB files directly to your ActiveGate. These MIB files are then used by all the SNMP and SNMP Traps extensions running on this ActiveGate.
Place your custom MIB files in the mib-files-custom
directory:
- Linux:
/var/lib/dynatrace/remotepluginmodule/agent/conf/userdata/mib-files-custom/
- Windows:
C:\%PROGRAMDATA%\dynatrace\remotepluginmodule\agent\conf\userdata\mib-files-custom\
The files stored in the mib-files-custom
directory are preserved between updates.
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 or after installation. For more information, see ActiveGate group.
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:
1[2 {3 "scope": "ag_group-my-activegate-group",4 "value": {5 "version": "1.0.0",6 "description": "my monitoring configuration",7 "enabled": true,8 "snmp": {9 "devices": [10 {11 "ip": "snmp.company.org",12 "port": 161,13 "timeoutSecs": 5,14 "retries": 0,15 "maxRepetitions": 50,16 "authentication": {17 "type": "SNMPv2c",18 "community": "public"19 }20 }21 ]2223 },24 "featureSets": [25 "all"26 ]27 }28 }29]
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:
1curl -X GET "{env-id}.live.dynatrace.com/api/v2/extensions/{extension-name}/{extension-version}/schema" \2 -H "accept: application/json; charset=utf-8" \3 -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.
The scope is 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 or after installation. For more information, see ActiveGate group.
Use the following format when defining the ActiveGate group:
1"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
orSNMPv3
(note thatSNMPv2c
by design uses the community authentication)
- Type:
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 istimeoutSecs
xretries
). 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.
1{2 "ip": "10.10.10.10",3 "port": 161,4 "authentication": {5 "type": "SNMPv3",6 "userName": "snmptest_SHA_AES256",7 "securityLevel": "AUTH_PRIV",8 "authPassword": "916cb7fe3c80fc273413797bd063b8e320237e6159a47c06278ec818da58e3a4fb5f715bdb63313439f2d5e25a434386b3fe82dd0a643507d7452340b3c56d30=",9 "authProtocol": "SHA512",10 "privPassword": "EAB559FF7A04D73D77FE017271A3250B786FB2FD4DA0D45F60C9BE31311221262DB510A4AEC53A418297FC260DB6C91429880030BCAA8416FA1C2810C8E7B928=",11 "privProtocol": "AES256C"12}
Feature sets
Add a list of feature sets you want to monitor. To report all feature sets, add all
.
1"featureSets": [2 "basic",3 "advanced"4 ]
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.
1"vars":2 {3 "ifNameFilter": "$contains(1/1/1)",4 "ifSpeedFilter": "$eq(4294967295)"5 }