Monaco configuration YAML file - list of special configuration types

• Latest Dynatrace
• Reference
• 6-min read
• Published Sep 14, 2025

This section describes how only one, single configuration end point should be present. It also describes the configuration types with non-standard behavior and specific constraints when working with the related APIs. For more information, see supported Configuration API types.

Single configuration endpoint

These configurations are global to a Dynatrace environment and a one-off. Unlike other configurations, there is usually some default configuration that you can update.

Non-unique name

Monaco assumes a unique configuration name and uses it as the identifier when creating or updating a configuration. This is true for most configurations created in the Dynatrace web UI or via API calls.

Some configurations can have the same names, which causes issues for the Dynatrace Monaco CLI. For example, there can be several dashboards named MyDashboard. If more than one name configuration is present, the Dynatrace Monaco CLI can't ensure that the correct one is updated when searching by name. Similar problems are present when downloading.

Dynatrace Monaco CLI specially handles these configuration APIs to ensure the following:

Calculated metrics

Calculated metric type names should be globally unique. Otherwise, Monaco may return duplicate config name errors.

Generally, calculated metrics behave as non-unique name types but use a metricKey that you can define as an identifier, so the automated handling described above is impossible.

While the API and web UI allow you to create several configurations with the same name, the Dynatrace Monaco CLI can't uniquely identify these configurations. After a download, you may see duplicate config name errors for calculated metric types.

Settings 2.0 objects

The handling of Settings 2.0 objects differs from classic configurations. Unlike the latter, which are typically identified by name, Settings 2.0 objects might not have a unique name or any name at all. Instead, they are assigned an external identifier called externalId that enables them to be uniquely identified.

The externalId consists of the prefix monaco: followed by an identifier generated by the Dynatrace Monaco CLI on deployment.

To ensure that the existing Settings 2.0 objects are reliably updated, the Dynatrace Monaco CLI records the original Dynatrace object IDs when downloading and includes them in the YAML configuration field originObjectId.

Settings objects also have special requirements for their JSON templates. For more details, see Settings JSON below.

Special requirements for JSON templates

Some types of configuration have special requirements for their JSON payloads and may need manual attention.

Dashboard JSON

When you create a dashboard, it's private by default. All the dashboards defined via Configuration as Code need to be shared publicly with other users; otherwise, only the owner of the access token used to deploy can view them. You can change this in the dashboard's Settings or by changing your checked-in json file.

We recommend the following values for the dashboardMetadata:

"dashboardMetadata": {
    "name": "{{ .name }}",
    "shared": true,
    "sharingDetails": {
      "linkShared": true,
      "published": true
    },
    "dashboardFilter": {
      "timeframe": "",
      "managementZone": {
        "id": "{{ .managementZoneId }}",
        "name": "{{ .managementZoneName }}"
      }
    }
  }

This configuration does the following:

Filtering the whole dashboard by management zone ensures that only data that is meant to be displayed is picked up by the dashboard tiles, and it eliminates the possible need to define filters for individual tiles.

Calculated log metrics JSON

The calculated log metrics API requires the following specific naming conventions. To ensure Dynatrace Monaco considers these configurations, the log metric's metricKey must be reused as the configuration's name.

You need to reference at least the metricKey of the log metric, as {{ .name }} in the JSON file as shown here:

configs:
- id: some-log-metric-config
  config:
    name:  "cal.log:this-is-some-metric"
[...]

And in the corresponding JSON:

{
  "metricKey": "{{ .name }}",
  "active": true,
  "displayName": "{{ .name }}",
  [...]
}

Conditional naming JSON

The conditional naming API does not provide a name parameter. Since Dynatrace Monaco CLI requires a name property in the config.yaml, it needs to be mapped to the displayName field in the JSON template.

The PROCESS_GROUP type:

{
  "type": "PROCESS_GROUP",
  "nameFormat": "Test naming PG for {Host:DetectedName}",
  "displayName": "{{ .name }}",
  [...]
}

The HOST type:

{
  "type": "HOST",
  "nameFormat": "Test - {Host:DetectedName}",
  "displayName": "{{ .name }}",
  [...]
}

The SERVICE type:

{
  "type": "SERVICE",
  "nameFormat": "{ProcessGroup:KubernetesNamespace} - {Service:DetectedName}",
  "displayName": "{{ .name }}",
  ...
}

Settings 2.0 JSON

The Settings API has additional properties unrelated to the specific schemas. This requires Dynatrace Monaco CLI to set further parameters.

For example, while the API response for a Davis Anomaly Detector config (builtin:davis.anomaly-detectors) is:

{
  "items": [
    {
      "objectId": "XYZ",
      "value": {
        "enabled": false,
        "title": "Error when adding item to cart",
        "description": "",
        "source": "Davis Anomaly Detection",
        "executionSettings": {
          "queryOffset": 3
        },
        "analyzer": {
          "name": "dt.statistics.ui.anomaly_detection.StaticThresholdAnomalyDetectionAnalyzer",
          "input": [
            {
              "key": "query",
              "value": "timeseries cartFailedToAddItem=sum(log.cartFailedToAddItem)"
            },
            {
              "key": "slidingWindow",
              "value": "3"
            },
            {
              "key": "violatingSamples",
              "value": "1"
            },
            {
              "key": "dealertingSamples",
              "value": "3"
            },
            {
              "key": "alertCondition",
              "value": "ABOVE"
            },
            {
              "key": "alertOnMissingData",
              "value": "false"
            },
            {
              "key": "threshold",
              "value": "0"
            }
          ]
        },
        "eventTemplate": {
          "properties": [
            {
              "key": "event.name",
              "value": "Cart Failure increase"
            },
            {
              "key": "event.description",
              "value": "The {metricname} value was {alert_condition} normal behavior."
            },
            {
              "key": "event.type",
              "value": "ERROR_EVENT"
            },
            {
              "key": "dt.event.allow_davis_merge",
              "value": "true"
            }
          ]
        }
      }
    }
  ]
  "totalCount": 89,
  "pageSize": 1,
  "nextPageKey": "XY"
}

The Dynatrace Monaco JSON template only requires the value content:

{
  "enabled": false,
  "title": "Error when adding item to cart",
  "description": "",
  "source": "Davis Anomaly Detection",
  "executionSettings": {
    "queryOffset": 3
  },
  "analyzer": {
    "name": "dt.statistics.ui.anomaly_detection.StaticThresholdAnomalyDetectionAnalyzer",
    "input": [
      {
        "key": "query",
        "value": "timeseries cartFailedToAddItem=sum(log.cartFailedToAddItem)"
      },
      {
        "key": "slidingWindow",
        "value": "3"
      },
      {
        "key": "violatingSamples",
        "value": "1"
      },
      {
        "key": "dealertingSamples",
        "value": "3"
      },
      {
        "key": "alertCondition",
        "value": "ABOVE"
      },
      {
        "key": "alertOnMissingData",
        "value": "false"
      },
      {
        "key": "threshold",
        "value": "0"
      }
    ]
  },
  "eventTemplate": {
    "properties": [
      {
        "key": "event.name",
        "value": "Cart Failure increase"
      },
      {
        "key": "event.description",
        "value": "The {metricname} value was {alert_condition} normal behavior."
      },
      {
        "key": "event.type",
        "value": "ERROR_EVENT"
      },
      {
        "key": "dt.event.allow_davis_merge",
        "value": "true"
      }
    ]
  }
}