Special configuration types

The following configuration types have non-standard behavior and constraints to deal with special Dynatrace APIs.

Single configuration endpoint

These configurations are global to a Dynatrace environment and only exist once. Unlike other configurations, there is usually some default configuration that the API—or the Dynatrace Monaco CLI—allows you to update.

Be aware that only one such configuration should be present in your configuration. Having multiple configurations (for example, in several projects deployed in one run) will result in the last applied configuration being active on the Dynatrace environment.

Non-unique name

The Dynatrace Monaco CLI assumes that the name of a configuration is unique, and it uses it as the identifier when deciding to create or update a configuration. This is also the case for most configurations when created in the Dynatrace UI or via API calls.

However, some configurations can have overlapping names, which causes issues for the Dynatrace Monaco CLI. For example, there can be several dashboards named My Dashboard. If more than one configuration of a name 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.

To work around this, special handling is present for these configuration APIs to ensure the following:

Calculated metrics

Calculated metrics generally behave as non-unique name types, but use a definable metricKey as identifiers, so the automated handling described above is not possible.

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

For most calculated metrics types, you just need to manually ensure that they have unique names.

The calculated-metrics-log type that allows configuration of the metrics for the deprecated Logs v1 needs further special handling as in the Calculated log metrics JSON section below.

Settings 2.0 objects

The handling of Settings 2.0 objects differs from regular 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.

Moreover, to ensure the reliable updating of existing Settings 2.0 objects, the Dynatrace Monaco CLI maintains a record of the original Dynatrace object IDs when downloading and includes them in the YAML configuration field originObjectId. Note that updating existing Settings 2.0 objects on the same environment is only available in Dynatrace version 1.262+.

Settings objects also have special requirements for their JSON templates. For 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 in the Dynatrace web UI, 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 API token used to deploy can view them. You can change this in the dashboard settings or by just 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:

Calculated log metrics JSON

There is a known drawback to Dynatrace Monaco CLI's workaround to the slightly off-standard Calculated log metrics API, which requires you to follow specific naming conventions for your configuration: when you create custom log metrics, your configuration's name must be the metricKey of the log metric.

Additionally, a configuration upload might fail when a metric configuration is newly created, and an additional configuration depends on the new log metric. To work around this, set both metricKey and displayName to the same value.

You thus 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

Because there is no name parameter in the Dynatrace Conditional naming API, you should map {{ .name }} to displayName. For example:

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

This also applies to the HOST type:

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

And it applies to the SERVICE type:

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

Settings JSON

Because the payload of the Settings API contains several properties that do not directly relate to the schema and might need to be set by the Dynatrace Monaco CLI, the JSON templates for settings should only include the actual configuration value.

For example, while the API response for auto-tagging (builtin:tags.auto-tagging) is:

{
  "items": [
    {
      "objectId": "vu9U3hXafawfawfawABnRlbmFudAAkZmY0ZTQxZDUtYmM2Yi0zMmFlLThhYmMtNDg3NTFiNWRkMWVhvu9U3hXa3q0",
      "value": {
        "name": "Application Tag",
        "rules": [
          {
            "enabled": true,
            "valueNormalization": "Leave text as-is",
            "type": "ME",
            "attributeRule": {
              "entityType": "APPLICATION",
              "conditions": [
                {
                  "key": "WEB_APPLICATION_NAME",
                  "operator": "CONTAINS",
                  "stringValue": "My App Name",
                  "caseSensitive": true
                }
              ]
            }
          }
        ]
      }
    }
  ],
  "totalCount": 1,
  "pageSize": 100
}

Your Configuration as Code template should be limited to the content of value:

{
  "name": "Application Tag",
  "rules": [
    {
      "enabled": true,
      "valueNormalization": "Leave text as-is",
      "type": "ME",
      "attributeRule": {
        "entityType": "APPLICATION",
        "conditions": [
          {
            "key": "WEB_APPLICATION_NAME",
            "operator": "CONTAINS",
            "stringValue": "My App Name",
            "caseSensitive": true
          }
        ]
      }
    }
  ]
}

Account management resources

You can manage account management resources with the following OAuth credentials:

account-idm-read
account-idm-write
account-env-read
account-env-write
iam-policies-management
iam:policies:write
iam:policies:read
iam:bindings:write
iam:bindings:read