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:
-
Check available schema versions using the GET all schemas endpoint. Schema version relate to Dynatrace Cluster versions.
curl -X GET "{env-id}.live.dynatrace.com/api/v2/extensions/schemas" \-H "accept: application/json; charset=utf-8" \-H "Authorization: Api-Token {api-token}"Response:
{"versions": ["1.213.0","1.215.0",]} -
Use the GET all files endpoint to list all available schemas for a specific Dynatrace version. For example:
curl -X GET "{env-id}.live.dynatrace.com/api/v2/extensions/schemas/{dynatrace-version}" \-H "accept: application/json; charset=utf-8" \-H "Authorization: Api-Token {api-token}"Response:
{"files": ["metric.metadata.schema.json","topology.schema.json","generic.types.schema.json","generic.relationships.schema.json","snmp.schema.json","metric.schema.json","wmi.schema.json","extension.schema.json"]} -
Use the GET a file endpoint to download a specific file in a specific version. For example, to download
extension.schema.json
, version1.215
:curl -X GET "{env-id}.live.dynatrace.com/api/v2/extensions/schemas/1.215/extension.schema.json" \-H "accept: application/json; charset=utf-8" \-H "Authorization: Api-Token {api-token}"
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.
name
—the name of your extension. A custom extension name (an extension not developed by Dynatrace) must start withcustom:
. The string must comply with the metric ingestion protocol requirements for dimensions.version
—the version of your extension inmajor
.minor
.build
format, such as1.0.0
. Your Dynatrace environment can store 10 extension versions, but only one can be active at the time.minDynatraceVersion
—the earliest Dynatrace version supported by the extension enclosed in quotes ("
), such as"1.213"
.author
—the extension developer or company.dashboards
—the path to the dashboard definitions in theextension.zip
archive relative to the extension YAML file. You can add up to 10 definitions.alerts
—the path to the custom metric events definitions in theextension.zip
archive relative to the extension YAML file. You can add up to 10 definitions.
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-healthversion: 1.0.0minDynatraceVersion: "1.238"author:name: Joe Doesnmp:- group: Device healthinterval:minutes: 1dimensions:- key: device.namevalue: oid:1.3.6.1.2.1.1.5.0- key: device.contactvalue: oid:1.3.6.1.2.1.1.4.0subgroups:- subgroup: Device health (Temperature)table: truedimensions:- key: envmon.temperature.descvalue: oid:1.3.6.1.4.1.9.9.13.1.3.1.2metrics:- key: envmon.temperature.valuevalue: oid:1.3.6.1.4.1.9.9.13.1.3.1.3type: 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).
Setting the interval is not possible for JMX data sources.
For example:
interval: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):
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: ifNameFilterdisplayName: Pattern matching interfaces for which metrics should be queriedtype: text- id: ext.activationtagdisplayName: Extension activation tagtype: text
There are three types of variables that can be used in your variables definition:
-
text
—allows you to provide a plain text value.- id: textVariabletype: textdisplayName: Variabledescription: "Detailed information about this variable"maxLength: 2000required: truedefaultValue: "#ff1"pattern: ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$displayName
—the name visible in Dynatrace Hub.maxLength
—the maximum length of the variable value (up to 10,000).required
—whether providing a value is required for this variable.defaultValue
—the default value if no value is specified in the REST API.pattern
—a regular expression pattern that must be fulfilled by the provided value.
-
multiline-text
—allows you to provide plain text with the new line symbols. For details on multiline YAML syntax, see YAML Multiline.- id: multilineVariabletype: multiline-textdisplayName: Variabledescription: Detailed information about this variablemaxLength: 2000required: truedefaultValue: |PipestylemultilinemaxLength
—the maximum length of a variable value (up to 10,000).required
—whether providing a value is required for this variable.defaultValue
—the default value if no value is specified in the REST API.
-
enum
—allows you to define your own set of possible values.- id: Colorstype: enumdefaultValue: greendescription: Choose your favorite color!availableValues:- value: reddisplayName: Red as a rose- value: greendisplayName: Green as grass- value: whitedisplayName: White as snow- optional
defaultValue
—if defined, sets the default value for the whole set and makes the variable required.
Define the possible values in
availableValues
list:value
—the value passed to the extension.displayName
—the name visible in Dynatrace Hub.
- optional
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:
-
Starts with – use a
const:$prefix
qualifier. Example:filter: const:$prefix(xyz) -
Ends with – use a
const:$suffix
qualifier. Example:filter: const:$suffix(xyz) -
Contains – use a
const:$contains
qualifier. Example:filter: const:$contains(xyz) -
Equals – use a
const:$eq
qualifier. Example:filter: const:$eq(xyz)For the expressions mentioned above, you can also use qualifiers:
const:$and
– to chain two or more expressions with AND operator. Example:filter: const:$and(<expr1>,<expr2>)- a
const:$or
– to chain two or more expressions with OR operator. Example:filter: const:$or(<expr1>,<expr2>) - a
const:$not
– to negate an expression. Example:filter: const:$not(<expr>)
The filtering logic is different for WMI extensions, where you pass the condition as a query. For more information, see Filter extracted dimensions.