Variables in documentation templates

This page describes the variables and channel-specific controls that are available for use in the documentation template associated with an alerting policy.

Using variables

In addition to Markdown, you can use variables of the form ${varname} to tailor the content of your documentation. When the documentation is sent with a notification, the string ${varname} will be replaced with the value of varname. The following screenshot shows the documentation included in an email notification, created from the documentation template described in Creating an alerting policy: Documentation:

Documentation included in email.

The following variables are available for use in documentation fields:

Variable Value
condition.name The REST resource name of the condition, such as
projects/foo/alertPolicies/1234/conditions/5678.
condition.display_name The display name of a condition, such as CPU usage increasing rapidly.
metadata.system_label.KEY The value of the system-supplied resource metadata label KEY.1
metadata.user_label.KEY The value of the user-defined resource metadata label KEY.1,4
metric.type The metric type, such as
compute.googleapis.com/instance/cpu/utilization.
metric.display_name The display name for the metric type, such as CPU utilization.
metric.label.KEY

The value of the metric label KEY.1
To find the labels associated with the metric type, see Metric list.

Values must be prefixed with a digit, a letter, a forward slash (/), or an equals sign (=). All other prefixes are disallowed. If a value contains an unsupported prefix, then the value isn't reported.

policy.name The REST resource name of the policy, such as projects/foo/alertPolicies/1234.
policy.display_name The display name of a policy, such as High CPU rate of change.
policy.user_label.KEY The value of the user label KEY.1,2
project The project ID of the Workspace, such as a-gcp-project.
resource.type The monitored-resource type, such as gce_instance.
resource.project The project ID of the monitored resource of the alerting policy.
resource.label.KEY The value of the resource label KEY.1,3,4
To find the labels associated with the monitored-resource type, see Resource list.

1 For example, ${resource.label.zone} is replaced with the value of the zone label. The values of these variables are subject to grouping; see null values for more information.
2 User labels in a policy can only be set by using the Monitoring API.
3 To retrieve the value of the project_id label on a monitored resource in the alerting policy, use ${resource.project}.
4 You can't access user-defined resource metadata labels by using resource.label.KEY. Use metadata.user_label.KEY instead.

null values

Values for the metric.*, resource.* and metadata.* variables are derived from time series. Their values can be null if no values are returned from the time series query.

  • The resource.label.KEY and metric.label.KEY variables can have null values if your alerting policy uses cross-series aggregation (reduction), for example, calculating the SUM across each of the time-series that match a filter). When using cross-series aggregation, any labels not used in grouping are dropped and will have null values if referenced in variable substitution. These labels are automatically retained if there is no cross-series aggregation.
  • Values for metadata.* variables are available only if the labels are explicitly included in a condition's filter or grouping for cross-series aggregation. That is, you must refer to the metadata label in either filter or grouping for it to have a value for the template.

Other usage notes

  • Only the variables in the table are supported. You cannot combine them into more complex expressions, like ${varname1 + varname2}.
  • To include the literal string ${ in your documentation, escape the $ symbol with a second $ symbol, and $${ will render as ${ in your documentation.
  • These variables are replaced by their values only in notifications sent through notification channels. In the Google Cloud Console, when the documentation is shown, you see the variables, not the values. Examples in the console include the descriptions of incidents and the preview of the documentation when creating an alerting policy.

Using channel controls

The text in the documentation field can also include special characters used by the notification channel itself to control formatting and notifications.

For example, Slack uses @ for mentions. You can use this to link the notification to a specific user. Suppose you include a string like this in the documentation field:

<@backendoncall> policy ${policy.display_name} triggered an incident

When the documentation field is received by the relevant Slack channel as part of the notification, this line triggers an additional message to the user backendoncall that, for example, the policy High CPU rate of change triggered an incident.

These additional options are specific to the channels; for more information on what may be available, consult the documentation provided by the channel vendor.