Skip to main content

Use custom tags to identify alerts and incidents

Watch a use case walkthrough: Use Tags to Create Custom Fields ►

The Events API and Metrics API are designed to be flexible and generic. Both schemas include a tags field that you can use to specify custom information, for example:

"tags": {
    "jira-ticket":"RGB-2654",
    "error-code" : "x1F391",
    "default-sprint":"dazzling-wright",
    "scrum-team":"spifftacular-brainiacs"
}

You can use tags to focus on items of interest in the Alerts and Incidents views. See Search, filter, and sort alert and incident data for more information. Tags can also be helpful in providing contextual information for resolving alerts and incidents.

Tags can be useful for outbound integrations to external tools such as Slack, Datadog, and PagerDuty:

  • You can include a tag filter in an outbound integration to specify which alerts or incidents trigger notifications.

  • You can also include individual tag fields, or the entire tag object, in the body of the outbound notification. For example:

    { "message":"Issue # ${id} with severity ${severity} and description ${description}","timestamp":"${created_at}","tags":"${tags}"}

Add tags in the following ways:

Including alert tags in incidents

The Correlate & Automate > Tags page includes a filter to specify the set of alert tags that you want to include in your incidents. It is good practice to identify the alert tags that provide the most context and value for your users, and to then specify a filter to ensure that only these tags are included in your incidents. An incident with a lot of "noisy" tags can be difficult to analyze and troubleshoot.

Tags requirements and good practices

  • Use strings or numbers for values, not lists or maps.

  • Keys and values are case-sensitive.

  • Avoid special characters except the following: + - = . _ : /

  • Do not define more than 50 tags per individual source. Each tag key should be unique and have one value.

  • Keys can be up to 128 Unicode characters (UTF-8). Values can be up to 256 Unicode characters.

  • Keys that start with aws: are reserved for AWS resources.