Extension YAML file

Your extension.yaml file defines the generic scope of your extension and is the core element of your extension package. It stores your environment configuration and is uploaded to your environment as a part of the extension ZIP package.

This topic describes core elements of the extension.yaml file applicable to any kind of extension from the Dynatrace Extensions 2.0 framework. For elements specific to particular data source types, see:

Schemas

When you create the extension.yaml file, make sure to rely on the schemas provided through the Extensions 2.0 API. We recommend that you use an editor supporting schema validation and snippets, which significantly simplifies extension.yaml editing.

We recommend using the Dynatrace Extensions VS Code add-on provided by Dynatrace. For more information, see Add-on for VS Code.

To download Extensions 2.0 schemas:

Alternatively, you can use the Dynatrace GitHub repository for Extensions schemas.

Start extension YAML file

The extension YAML file starts with basic information about the extension. It also contains optional references to assets used by the extension.

Groups and subgroups

You can organize your metrics into groups and subgroups to assign metrics within a group to specific dimensions or feature sets, or control the interval at which they're reported at a group level.

For each extension, you can define 10 groups, and each group can contain 10 subgroups.

For example:

name: com.dynatrace.cisco-catalyst-health
version: 1.0.0
minDynatraceVersion: "1.238"
author:
  name: Joe Doe

snmp:
  - group: Device health
    interval:
      minutes: 1
    dimensions:
      - key: device.name
        value: oid:1.3.6.1.2.1.1.5.0
      - key: device.contact
        value: oid:1.3.6.1.2.1.1.4.0

    subgroups:
      - subgroup: Device health (Temperature)
        table: true
        dimensions:
          - key: envmon.temperature.desc
            value: oid:1.3.6.1.4.1.9.9.13.1.3.1.2
        metrics:
          - key: envmon.temperature.value
            value: oid:1.3.6.1.4.1.9.9.13.1.3.1.3
            type: gauge

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:

interval:
     minutes: 5

interval: 5m

Metrics

You can define metrics at the extension, group, and subgroup level. The details on how you extract metric values vary depending on the data source type. See:

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.

Dimensions

You can define a dimension at the metric, group, and subgroup level. The details on how you extract dimension values vary depending on the data source type. See:

Variables

If you want to make your extension customizable with 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:

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

There are three types of variables that can be used in your variables definition:

Filters

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.

filter: var:ifNameFilter

Define the filter based on a condition as follows: