Overview

Monitor tags are intentionally versatile to support a variety of use-cases.

• Data quality reporting and SLAS: report on specific monitors, rather than all monitors for a set of tables on the upcoming Data quality dashboard.
• Critical data elements: report on a set of validations or metric monitors for a critical data element, applying tags like cde:total_revenue.
• Enforcing data contracts: we recommend using a tag with key data-contract in order to be picked up by Atlan data contracts.
• Data quality dimensions: dedicated field on a monitor for storing a data quality dimension; one of Accuracy, Completeness, Consistency, Timeliness, Validity, Uniqueness.
• Team organization: for monitors that are owned by the finance team, applying tags like team:finance.
• Use case organization: for organizing specific use-cases or data products, applying tags like data-product:salesforce_revenue or project:revenue_reliability.

Leveraging monitor tags

Monitor tags can be viewed in the detail page of a monitor as well as the upcoming Data quality dashboard.

Monitor tags are also sent with the alerts that the monitor raises, so you can route and filter on them in your incident tooling:

• FireHydrant — in the incident tags array, as name:value.
• PagerDuty — in custom_details.monitor_tags, as name=value.

If you'd like to use monitor tags in other parts of the product, please let us know.

Applying monitor tags

When creating a new monitor, you can specify one or more tags in the Send notifications section of custom monitor configuration.

• Monitor tags can have have a key / value pair or just a key.
• Monitor tags are stored and can be referenced again by any user. This can help reduce typos and other duplication of tags.
• Monitor tags can only be created or updated by users with the permission to create/edit/delete monitors. See more in the Authorization documentation.
• Freshness and volume monitors cannot be tagged, except explicit thresholds through monitors as code.
• Schema monitors cannot be tagged.

Applying monitor tags via monitors as code

Monitor tags simply uses the tags key in monitors as code. Use the name and value for applying the individual tag. Each name and value is on a new line.

Please note that labels in monitors as code refers to 🧑‍🎓 Audiences, not tags.

tags:
  - name: my_key
    value: my_value
  - name: only_a_key

See more at Monitors as Code, including per-type references for metric, custom SQL, validation, and table monitors.

Applying monitor tags via API

For an existing monitor:

1. Get the existing monitor monitorUuid , monitorType, and existing tags.
2. Add tag (with any existing tags) to monitor
3. Get the existing monitor to see the tag applied.

## Get an existing monitor

  query getAllCustomMonitors($uuids: [String]) {
    getMonitors(
      uuids: $uuids
    ) {
      uuid
      monitorType
      tags {
        name
        value
      }
    }
  }

  ### variables 
  {
    "uuids": ["3b682f48-9233-4b1b-881e-0598c2c8b685"]
  }

## Update the monitor's tags

  mutation updateMonitorTags($monitorUuid: UUID!, $monitorType: String!, $tags: [TagKeyValuePairInput!]!) {
    updateMonitorTags(
      monitorUuid: $monitorUuid
      monitorType: $monitorType
      tags: $tags
    ) {
      success
    }
  }

  ### variables 
  {
    "monitorType": "custom_sql",
    "monitorUuid": "3b682f48-9233-4b1b-881e-0598c2c8b685",
    "tags": [
      {
        "name": "my-tag",
        "value": "my-tag-value"
      }
    ]
  }

Setting required monitor tags

If you rely on monitor tags for governance or reporting, you can require them so no monitor is saved without them.

Set required tags via the updateRequiredMonitorFields API mutation. For which fields can be required and how it works, see Set required metadata fields. Set required metadata fields.

Pick the level of enforcement you need:

1. Require at least one tag: Include TAGS in fields.
2. Require a specific tag key: Pass the key in requiredTags. Any value is accepted.
3. Require a specific tag key with allowed values: Pass the key and its allowedValues in requiredTags. The tag must use one of those values.

Require any tag:

mutation {
  updateRequiredMonitorFields(
    fields: [TAGS] # monitors must have at least one monitor tag
  ) {
    requiredMonitorFields { fields }
  }
}

Require specific keys, with or without allowed values:

mutation {
  updateRequiredMonitorFields(
    fields: [] # full replace: list any other metadata fields you require
    requiredTags: [
      { key: "owner" } # must have an owner tag, any value
      { key: "lifecycle", allowedValues: ["production", "experimental", "deprecated"] } # must have a lifecycle tag, set to one of these values
    ]
  ) {
    requiredMonitorFields { fields requiredTags { key allowedValues } }
  }
}

• Required keys and values are case-sensitive. For example, Owner doesn't satisfy a rule for owner.
• requiredTags applies with or without TAGS in fields. You don't need both to require a specific tag key or value.