diff --git a/docs/sources/alerting/fundamentals/labels-and-label-matchers.md b/docs/sources/alerting/fundamentals/labels-and-label-matchers.md new file mode 100644 index 00000000000..ef908b5db70 --- /dev/null +++ b/docs/sources/alerting/fundamentals/labels-and-label-matchers.md @@ -0,0 +1,43 @@ ++++ +title = "Labels and label matchers" +description = "Learn about labels and label matchers in alerting" +keywords = ["grafana", "alerting", "guide", "fundamentals"] +weight = 117 ++++ + +# Labels and label matchers + +To link alert rules to various other alerting concepts like [notification policies]() and [silences]() you make use of labels and label matchers. + +This allows for a very flexible way to manage your alert instances, what policy should handle them and which alerts to silence. + +## How label matching works + +A label matchers consists of 3 distinct parts, the **label**, the **value** and the **operator**. + +- The **Label** field is the name of the label to match. It must exactly match the label name. + +- The **Value** field matches against the corresponding value for the specified **Label** name. How it matches depends on the **Operator** value. + +- The **Operator** field is the operator to match against the label value. The available operators are: + +| Operator | Description | +| -------- | -------------------------------------------------- | +| `=` | Select labels that are exactly equal to the value. | +| `!=` | Select labels that are not equal to the value. | +| `=~` | Select labels that regex-match the value. | +| `!~` | Select labels that do not regex-match the value. | + +## Example + +Imagine we've defined the following set of labels for our alert. + +`{ foo=bar, baz=qux, id=12 }` + +A label matcher defined as `foo=bar` will match this alert rule. + +A label matcher defined as `foo!=bar` will _not_ match this alert rule. + +A label matcher defined as `id=~[0-9]+` will match this alert rule. + +A label matcher defined as `baz!~[0-9]+` will match this alert rule. diff --git a/docs/sources/alerting/notifications/_index.md b/docs/sources/alerting/notifications/_index.md index 831af9833c3..00cafcf4ac8 100644 --- a/docs/sources/alerting/notifications/_index.md +++ b/docs/sources/alerting/notifications/_index.md @@ -48,7 +48,7 @@ You can configure grouping to be `group_by: [alertname]` (take note that the `en 1. Click **Notification policies**. 1. From the **Alertmanager** dropdown, select an Alertmanager. By default, the Grafana Alertmanager is selected. 1. To add a top level specific policy, go to the **Specific routing** section and click **New specific policy**. -1. In **Matching labels** section, add one or more rules for matching alert labels. For more information, see ["How label matching works"](#how-label-matching-works). +1. In **Matching labels** section, add one or more rules for matching alert labels. For more information, see ["Labels and label matchers"]({{< relref "../fundamentals/labels-and-label-matchers.md" >}}). 1. In **Contact point**, add the [contact point]({{< relref "../contact-points/_index.md" >}}) to send notification to if alert matches only this specific policy and not any of the nested policies. 1. Optionally, enable **Continue matching subsequent sibling nodes** to continue matching nested policies even after the alert matched the parent policy. When this option is enabled, you can get more than one notification. Use it to send notification to a catch-all contact point as well as to one of more specific contact points handled by nested policies. 1. Optionally, enable **Override grouping** to specify the same grouping as the root policy. If this option is not enabled, the root policy grouping is used. @@ -68,20 +68,6 @@ You can configure grouping to be `group_by: [alertname]` (take note that the `en 1. Make any changes using instructions in [Add new specific policy](#add-new-specific-policy). 1. Click **Save policy**. -## How label matching works - -A policy will match an alert if the alert's labels match all the "Matching Labels" specified on the policy. - -- The **Label** field is the name of the label to match. It must exactly match the label name. -- The **Operator** field is the operator to match against the label value. The available operators are: - - - `=`: Select labels that are exactly equal to the provided string. - - `!=`: Select labels that are not equal to the provided string. - - `=~`: Select labels that regex-match the provided string. - - `!~`: Select labels that do not regex-match the provided string. - -- The **Value** field matches against the corresponding value for the specified **Label** name. How it matches depends on the **Operator** value. - ## Example An example of an alert configuration.