Menu

This is documentation for the next version of Grafana. For the latest stable release, go to the latest version.

Grafana Cloud Enterprise Open source

Notification policies

Notification policies provide you with a flexible way of designing how to handle notifications and minimize alert noise.

Using label matchers, alert instances are routed to notification policies. The notification policy can then group multiple alert instances into a single notification and deliver it to the contact point.

How Alerting works

Notification policies are not a list, but rather are structured according to a tree structure:

  • The root of the notification policy tree is the Default notification policy.
  • Each policy can have child policies.
  • Each policy can have sibling policies, sharing the same parent and hierarchical level.

Each policy consists of a set of label matchers (0 or more) that specify which alerts they are or aren’t interested in handling. A matching policy refers to a notification policy with label matchers that match the alert instance’s labels.

Example of a notification policy tree
Matching alert instances with notification policies

Routing

To determine which notification policies handle an alert instance, the system looks for matching policies starting from the top of the tree—beginning with the default notification policy.

If a matching policy is found, the system continues to evaluate its child policies in the order they are displayed. If a child policy matches the alert, the system then evaluates its child policies recursively until no more matching child policies are found. In this case, only the deepest matching child policy handles the alert instance.

By default, once a matching policy is found, the system does not continue to look for sibling policies. If you want sibling policies of one matching policy to handle the alert instance as well, then enable Continue matching siblings on the particular matching policy.

Note

The default notification policy matches all alert instances. It always handles alert instances if there are no child policies or if none of the child policies match the alert instance’s labels—this prevents any alerts from being missed.

If alerts use multiple labels, these labels must also be present in a notification policy to match and route notifications to a specific contact point.

This routing and tree structure makes it convenient to organize and handle alerts for dedicated teams, while also narrowing down specific cases within the team by applying additional labels.

Inheritance

In addition to child policies being a useful concept for routing alert instances, they also inherit properties from their parent policy. This also applies to child policies of the default notification policy.

By default, a child policy inherits the following notification properties from its parent:

Then, each policy can overwrite these properties if needed.

The inheritance of notification properties, together with the routing process, is an effective method for grouping related notifications and handling specific cases through child policies.

Inheritance example

Simple example inhering notification settings

This example shows how the notification policy tree from the previous example allows the child policies of the team=operations to inherit its contact point. In this way, you can avoid specifying the same contact point multiple times for each child policy.