Monaco configuration YAML file structure

• Latest Dynatrace
• Reference
• 14-min read
• Updated on Sep 10, 2025

The configs YAML file contains a list of configurations to be deployed.

Here is a basic example of an SLO configs YAML file:

configs:
- id: newSLO
  type: slo-v2
  config:
    parameters:
      target: 95
      title: myNewSLO
      entityScope: HOST-#######
    template: slo-cpu-usage.json
    skip: false

The top-level element of the configuration file is configs. Its value is a list of configurations.

required Each configuration requires the following fields: id, type, and config.

id field

The id field identifies a config within the configurations. It must be unique for the same configType and project. This field is needed to reference the parameters and describe dependencies between single configs.

It is possible to have, for example, two dashboards with the same id but in two different projects.

type field

The type field defines the type of Dynatrace configuration.

For a detailed list, see Monaco configuration YAML file - list of type fields.

The types and subcategories

Additional and optional fields

Depending on the configuration type, you might need to define additional fields or add optional fields.

Configuration type fields

config field

The config field specifies the single configuration instance of the selected type and references the JSON template containing the JSON payload uploaded to the Dynatrace API endpoints.

The following fields

String escape in config

All YAML values are generally escaped before being added to a configuration and uploaded to Dynatrace. Using string escape ensures that filled-out templates are valid JSON when uploading. Any new lines, special characters such as double quotes, are escaped.

parameters:
  name: "Dev"
  example1: "This is \\n already escaped."
  example2: "This will \n be escaped."
  example3: This "will" be escaped too.
  text: |
    This will also
    be escaped.

name property

Configurations of type api

If the specified configuration is an api type, the name is used to identify configurations in a Dynatrace environment and ensure that they're updated when they already exist.

For this, the name needs to be used in the JSON template to fill the configuration's specific name property. Usually, this is also just a name, but for some configurations, this may differ. For more information, see the exceptional cases described for JSON templates Work with Dynatrace Monaco CLI commands for Latest Dynatrace and refer to the API documentation if in doubt.

When downloading, the names are automatically extracted and placed in the YAML for you.

Use the name property in JSON like this "{{ .name }}".

Other configuration types

The name property isn't used to identify Dynatrace objects. Instead, the configuration's coordinate, a combination of project, type, and configuration ID, or originObjectId, if present, is used.

The name property can still be used and, for some types, is automatically extracted when downloading.

skip field

The skip field allows you to omit or skip the deployment of a specific configuration. If skip is set to true, the Dynatrace Monaco CLI won't deploy the configuration.

The skip field behaves like parameters and you can define it as a value or an environment parameter. Typically, it's defined directly as a shorthand value.

It's most useful with environment overrides, where you want to deploy a configuration to one environment but exclude it from another.

parameters field

The parameters field is used to provide selected values in a configuration template. It's defined as YAML object with a type entry. This type then further decides how the parameter object is interpreted. The value of a parameter is only evaluated if it's referenced by a configuration that is going to be deployed.

The following parameter types are available:

value parameter

The value parameter is the simplest form of a parameter. Besides the type property, it also requires the value property. You can define anything as the value, even nested maps. This value is then accessible in the template file. Because the value parameters are the most common parameter type, there is a special short-form syntax to define them. You can provide the value if your parameter is neither an array nor a map.

An example of setting the value parameter:

parameters:
  threshold: 15
  complexThreshold:
    type: value
    value:
      amount: 15
      unit: sec

In the JSON template of this configuration, the threshold parameter can be accessed via {{ .threshold }}. To access, for example, the amount of the complexThreshold, you could use {{ .complexThreshold.amount }}.

environment parameter

The environment type parameter allows you to reference an environment variable. The environment variable's name to reference is defined via a name property.

You can provide a default value via the default property if the environment variable is absent.

The parameter can't be resolved if the default property is not set and the environment variable is missing. The deployment fails when the default property is not set and the environment variable is missing.

The following example defines an owner and target parameter:

reference parameter

Dynatrace configurations often reference other configurations to support more complex use cases. Monaco provides a specific reference parameter to support such configuration references.

To use the parameter reference type, provide the following required fields:

The Dynatrace Monaco CLI ensures the configuration is deployed in order, with the dependent configuration is being deployed first.

Shorthand form syntax notion

The reference parameters are one of the most common parameter types; there is a special shorthand form syntax to define them as an array:

Partial reference

It's possible to omit some reference fields. In this case, they're filled with the same value as the current config. This can be used to simplify referencing configurations within the same project.

parameters:
  mz_id:
    type: reference
    configType: management-zone
    configId: main
    property: id

While it's possible to omit configType and even configId, you can only leave the uppermost level empty, and you can't leave a gap. So if configType is omitted, it must be the project.

Below is a complete sample using shorthand references:

compound parameter

The compound parameter comprises other parameters of the same configuration.

This parameter requires a couple of properties:

The format string can be any string. To use parameters in it, use the syntax {{ .parameter }}, where the parameter's name of the compound parameter you fill in.

An example of using a compound parameter:

parameters:
  example:
    type: compound
    format: "{{ .resource.name }}: {{ .resource.percent }}%"
    references:
    - resource
  progress:
    type: value
    value:
      name: "Health"
      percent: 40

This example produces the following outcome: Health: 40%.

Even though referenced parameters can only be from the same configuration, using the reference parameter can create a compound parameter with other configs. This is also true for environment variables.

An example of using a compound parameter:

parameters:
  example:
    type: compound
    format: "{{ .user }}'s dashboard is {{ .status }}"
    references:
    - user
    - status
  user:
    type: environment
    name: USER_NAME
  status:
    type: reference
    configType: dashboarddocument
    configId: my-dashboard
    property: status

list parameter

The type list parameter allows you to define lists of value parameters. When these are in a template, they're written as a JSON list surrounded by square brackets and separated by commas. This parameter type generally applies when you require a simple list of things, such as emails or identifiers, that can be filled with any value parameter.

An example of using a list parameter:

Configs:
- id: myservice-slo-availability
  config:
    name: CasC-sample myService availability
    parameters:
      service_id:
        name: SERVICE_ID
        type: environment
      tags: #INPUT: Customize your SLO with tags
        type: list
        values: ["service:myService", "dt.owner:myTeam"]
    template: myservice-slo-availability.json
    skip: false
  type: slo-v2

An example of using a list parameter and a JSON template called myservice-slo-availability.json:

{
  "criteria": [
    {
      "target": 95,
      "timeframeFrom": "now-7d",
      "timeframeTo": "now"
    }
  ],
  "customSli": {
    "filterSegments": [],
    "indicator": "timeseries { total=sum(dt.service.request.count) ,failures=sum(dt.service.request.failure_count) }\n  , by: { dt.entity.service }\n  , filter: { in (dt.entity.service, { \"{{ .service_id }}\" }) }\n| fieldsAdd sli=(((total[]-failures[])/total[])*(100))\n| fieldsAdd entityName(dt.entity.service)\n| fieldsRemove total, failures"
  },
  "description": "Measures the proportion of successful service requests over time.",
  "name": "{{ .name }}",
  "tags": {{ .tags }}
}

As shown in the example above, you can define the list values in YAML either line by line or as an array.

file parameter

Dynatrace Monaco CLI version 2.14.0+

The type file parameter allows you to load content from a file on a disk.

An example of using a file parameter:

parameters:
  comment: "// hello special comment"
  myWf:
    type: file        # parameter type "file"
    path: "myWf.js"   # relative path to the file
    references:       # other parameters names referenced in the content of the file
      - comment

In the example, the parameter myWf is dynamically resolved to include the myWf.js content relative to the current configuration location.

You can reference this parameter within the JSON template as follows:

{ "script" : {{ .myWf }} }

You can include references to other parameters within the content of the referenced file. Each reference parameter must be defined as a separate parameter and listed in the references section of the file parameter type.

In the given example, you can reference the additional parameter called comment within the content specified by the file parameter using the notation {{ .comment }}.

originObjectId

When using the Dynatrace Monaco CLI to download existing configurations from Dynatrace, the created YAML files contain an originObjectId for some configuration types.

The originObjectId holds the ID of the downloaded Dynatrace object. Use originObjectId when you're planning on deploying again to the same Dynatrace environment to ensure that the existing object is correctly updated with the downloaded configuration.

For example, you could use it for an existing Settings 2.0 object that you extend with the data used to identify it correctly.

Override configurations per environment or environment-group

There are many cases in which a configuration is similar but not the same between environments.

For example:

To allow this, you can use the groupOverrides and environmentOverrides fields to override configuration values on an environment and environment-group level.

Both are generally defined similarly, differing only in whether they're applied to a group or a single environment. You can define the environment or environment-group name to target and any configuration properties to modify.

In this example, a configuration gets some special configuration applied for two environments, and skip ensures that the configuration won't be deployed to the production-environments group:

configs:
- id: test-dashboard
  type:
    api: dashboard
  config:
    name: Test Dashboard
    template: dashboard.json
    parameters:
      owner: Test User
      content: "Some Text ..."
  environmentOverrides:
  - environment: dev-env-42
    override:
      name: Special Dev Dashboard
      parameters:
        content: "Some even better Text!"
  - environment: staging-env-21
    override:
      name: Special Staging Dashboard
      parameters:
        content: "Some much better Text!"
  groupOverrides:
  - group: production-environments
    override:
      skip: true