From f76e4f8fda8b5a988422d5e352acb08dfa0e384c Mon Sep 17 00:00:00 2001 From: Pepe Cano <825430+ppcano@users.noreply.github.com> Date: Tue, 10 Jun 2025 17:22:48 +0200 Subject: [PATCH] docs(alerting): Import to Grafana-managed rules (#106384) * docs(alerting): Import to Grafana-managed rules * apply latest evaluation changes * Add additional conversion details to How it works section * fix ref link * fix Data source input name * more details about the `Target data source` input --- .../alerting-rules/alerting-migration.md | 290 ++++++++++++++++++ .../alerting-migration/_index.md | 97 ------ .../alerting-migration/migration-api.md | 185 ----------- .../alert-rule-evaluation/_index.md | 7 +- .../setup-grafana/configure-grafana/_index.md | 10 + 5 files changed, 301 insertions(+), 288 deletions(-) create mode 100644 docs/sources/alerting/alerting-rules/alerting-migration.md delete mode 100644 docs/sources/alerting/alerting-rules/alerting-migration/_index.md delete mode 100644 docs/sources/alerting/alerting-rules/alerting-migration/migration-api.md diff --git a/docs/sources/alerting/alerting-rules/alerting-migration.md b/docs/sources/alerting/alerting-rules/alerting-migration.md new file mode 100644 index 00000000000..1d06d31f006 --- /dev/null +++ b/docs/sources/alerting/alerting-rules/alerting-migration.md @@ -0,0 +1,290 @@ +--- +aliases: + - ../alerting-rules/alerting-migration/migration-api/ # /docs/grafana//alerting-rules/alerting-migration/migration-api/ +canonical: https://grafana.com/docs/grafana/latest/alerting-rules/alerting-migration/ +description: Convert alert rules from data sources such as Mimir, Loki, and Prometheus into Grafana-managed alert rules. This enables you to operate and manage these rules using Grafana Alerting. +labels: + products: + - cloud + - enterprise + - oss +title: Import data source-managed rules to Grafana-managed rules +menuTitle: Import to Grafana-managed rules +weight: 450 +refs: + configure-grafana-rule_query_offset: + - pattern: /docs/ + destination: /docs/grafana//setup-grafana/configure-grafana/#rule_query_offset + evaluation-strategies: + - pattern: /docs/grafana/ + destination: /docs/grafana//alerting/fundamentals/alert-rule-evaluation/ + - pattern: /docs/grafana-cloud/ + destination: /docs/grafana-cloud/alerting-and-irm/alerting/fundamentals/alert-rule-evaluation/ + missing_series_evaluations_to_resolve: + - pattern: /docs/grafana/ + destination: /docs/grafana//alerting/fundamentals/alert-rule-evaluation/stale-alert-instances/#configure-missing-series-evaluations-to-resolve + - pattern: /docs/grafana-cloud/ + destination: /docs/grafana-cloud/alerting-and-irm/alerting/fundamentals/alert-rule-evaluation/stale-alert-instances/#configure-missing-series-evaluations-to-resolve + configure-recording-rules: + - pattern: /docs/grafana/ + destination: /docs/grafana//alerting/alerting-rules/create-recording-rules/create-grafana-managed-recording-rules/ + - pattern: /docs/grafana-cloud/ + destination: /docs/grafana-cloud/alerting-and-irm/alerting/alerting-rules/create-recording-rules/create-grafana-managed-recording-rules/ +--- + +# Import data source-managed rules to Grafana-managed rules + +You can convert existing alert rules from data sources such as Mimir, Loki, and Prometheus into Grafana-managed alert rules. This enables you to operate and manage these rules using Grafana Alerting. + +This guide explains two methods for importing data source-managed rules: + +- Using the [Grafana Alerting user interface](#import-rules-with-grafana-alerting) to import rules from connected data sources or Prometheus rule YAML files. + +- Using [command-line tools](#import-rules-with-command-line-tools) like `mimirtool` and `cortextool` to import rules from YAML files. + +Importing rules is a safe operation: the original data source–managed rules remain intact in their original location. During import, the rules are converted into Grafana-managed rules while preserving their configuration and behavior. + +Choose the method that best fits your workflow. As a best practice, test and validate your import process before migrating all alert rules. + +## How it works + +When you use any of the import methods, data source–managed rules are copied to another folder as Grafana-managed rules. + +The original data source–managed rules remain intact in their original location. + +The copied rules are converted to Grafana-managed rules, preserving their behavior by using equivalent Grafana-managed features. The following settings are applied during the conversion: + +- **Unique UIDs** + + The newly created rules are assigned unique UIDs. + If you don’t want a UID to be auto-generated, you can specify one using the `__grafana_alert_rule_uid__` label. + +- **Query offset** + + A query offset is applied to each rule. For example, an offset of `1m` adjusts the query's time range to `To: now-1m`. + + The rule query offset is taken from the `query_offset` value in the rule group configuration. If empty, it defaults to the [`rule_query_offset` configuration setting](ref:configure-grafana-rule_query_offset), which is `1m` by default. + +- **Missing series evaluations to resolve** + + The [Missing series evaluations to resolve](ref:missing_series_evaluations_to_resolve) setting is set to `1` to replicate Prometheus’s alert eviction behavior. + +- **Rule group labels** + + Labels defined at the rule group level are added as labels to each imported rule within the group. + +- **Sequential evaluation** + + Imported rules are evaluated sequentially within each rule group, mirroring Prometheus behavior. This differs from native Grafana-managed alert rules, where the evaluation order is not enforced. For more details, refer to [evaluation strategies](ref:evaluation-strategies). + +- **Feature compatibility** + + The rule group `limit` option and the `query` function within alert rule templates are not currently supported in Grafana-managed rules. If the `limit` option is present, the import fails. However, rules with `query` in templates are imported. + +{{< admonition type="note" >}} +Rules with the label `__grafana_origin` are not included in rule imports. These rules are typically created by apps such as **Kubernetes Monitoring**, **Synthetic Monitoring**, and other **Grafana plugins**. +{{< /admonition >}} + +## Import rules with Grafana Alerting + +You can use the Grafana Alerting user interface to import rules from the following sources: + +- Connected Mimir and Loki data sources with the ruler API enabled +- Prometheus YAML rule files + +Imported rules using this method are editable in the user interface. Like regular Grafana-managed rules, you can later export them for provisioning. + +#### Before you begin + +To use Grafana Alerting to migrate rules, you need the following [RBAC permissions](/docs/grafana/latest/administration/roles-and-permissions/access-control/): + +- **Alerting**: `Rules Writer`, `Set provisioning status`. +- **Datasources**: `Reader`. +- **Folders**: `Creator`. + + The Folders permission is optional and only necessary if you want to create new folders for your target namespace. If your account doesn't have permissions to view a namespace, the tool creates a new one. + +To convert data source-managed alert rules to Grafana managed alerts: + +1. Go to **Alerting > Alert rules**. + +2. Navigate to the Data source-managed alert rules section and click **Import to Grafana-managed rules**. + +3. Choose the **Import source** from which you want to import rules: + + - Select **Existing data source-managed rules** to import rules from connected Mimir or Loki data sources with the ruler API enabled. + - Select **Prometheus YAML file** to import rules by uploading a Prometheus YAML rule file. + +4. In the **Data source** dropdown, select the data source that the imported alert rules will query. + +5. (Optional) In Additional settings, select a target folder or designate a new folder to import the rules into. + + If you import the rules into an existing folder, don't choose a folder with existing alert rules, as they could get overwritten. + +6. (Optional) Select a Namespace and/or Group to determine which rules are imported. + +7. (Optional) Turn on **Pause imported alerting rules**. + + Pausing stops alert rule evaluation and doesn’t create any alert instances for the newly created Grafana-managed alert rules. + +8. (Optional) Turn on **Pause imported recording rules**. + + Pausing stops alert rule evaluation behavior for the newly created Grafana-managed alert rules. + +9. (Optional) In the **Target data source** of the **Recording rules** section, you can select the data source that the imported recording rules will query. By default, it is the data source selected in the **Data source** dropdown. + +10. Click **Import**. + + A preview shows the rules that will be imported. If your target folder contains folders with the same name of the imported folders, a warning displays to inform you. You can explore the warning to see a list of folders that might be overwritten. + + Click **Yes, import** to import the rules. + +## Import rules with command-line tools + +You can also use command-line tools to import data source-managed rules as Grafana-managed rules: use `mimirtool` for Mimir and Prometheus rules, and `cortextool` for Loki rules. + +Both tools provide `rules` commands to import rules groups. For example: + +- `rules load` can import rule groups from files. +- `rules sync` can read rule files and applies only the differences compared to existing Grafana-managed rules. This is useful for automation workflows and pipelines. + +By default, rules imported using the API or command-line tools are **Provisioned** and not editable in the user interface. To make them editable, enable the [X-Disable-Provenance](#x-disable-provenance) header. + +#### Before you begin + +You need to have installed [`mimirtool`](/docs/mimir/latest/manage/tools/mimirtool/) or [`cortextool`](https://github.com/grafana/cortex-tools) (version `0.11.3` or later). + +You need a service account with the following [RBAC permissions](/docs/grafana/latest/administration/roles-and-permissions/access-control/): + +- **Alerting**: `Rules Reader`, `Rules Writer`, `Set provisioning status`. +- **Datasources**: `Reader`. +- **Folders**: `Creator`, `Reader`, `Writer`. + +You need to a service account token with your service account. For more details, refer to [service accounts and service account tokens](/docs/grafana/latest/administration/service-accounts/). + +### mimirtool + +To convert and import them into a Grafana instance, you can use the `mimirtool rules load` command: + +```bash +MIMIR_ADDRESS=/api/convert/ \ +MIMIR_AUTH_TOKEN= \ +MIMIR_TENANT_ID=1 \ +mimirtool rules load rule_file.yaml \ + --extra-headers "X-Grafana-Alerting-Datasource-UID=" +``` + +This command imports Prometheus alert rules defined in `rule_file.yaml` as Grafana-managed alert rules. It's important to know that: + +1. When using the `/api/convert/` endpoint, `mimirtool` interacts with Grafana—not with a Mimir instance. In this case, `MIMIR_TENANT_ID` must always be set to `1`. +1. The [`X-Grafana-Alerting-Datasource-UID` header](#x-grafana-alerting-datasource-uid) configures the data source that the imported alert rules will query. Use multiple `--extra-headers` flags to include other [optional headers](#optional-headers). + +Similarly, the `rules sync` command can import and update Grafana-managed alert rules. + +```bash +MIMIR_ADDRESS=/api/convert/ \ +MIMIR_AUTH_TOKEN= \ +MIMIR_TENANT_ID=1 \ +mimirtool rules sync rule_file.yaml \ + --extra-headers "X-Grafana-Alerting-Datasource-UID=" \ + --concurrency 1 +``` + +The `--concurrency` flag must be set to `1`, as the default value of `8` may cause API errors. + +This `sync` command reads rules from the file, compares them with the existing Grafana-managed rules in the instance, and applies only the differences—creating, updating, or deleting rules as needed. + +```output +## Sync Summary: 0 Groups Created, 1 Groups Updated, 0 Groups Deleted +``` + +For more information other Mimirtool commands and options, see the [Mimirtool documentation](/docs/mimir/latest/manage/tools/mimirtool/#rules) and the [Mimir HTTP Rule API documentation](/docs/mimir/latest/references/http-api/#ruler-rules:~:text=config/v1/rules-,Get%20rule%20groups%20by%20namespace,DELETE%20%3Cprometheus%2Dhttp%2Dprefix%3E/config/v1/rules/%7Bnamespace%7D,-Delete%20tenant%20configuration). + +### cortextool + +For Loki alert rules, use [`cortextool`](https://github.com/grafana/cortex-tools) (version `0.11.3` or later) with the `--backend=loki` flag. For example: + +```bash +CORTEX_ADDRESS=/api/convert/ \ +CORTEX_AUTH_TOKEN= \ +CORTEX_TENANT_ID=1 \ +cortextool rules load loki_rules.yaml \ + --extra-headers "X-Grafana-Alerting-Datasource-UID=" \ + --backend=loki +``` + +### Optional Headers + +Additional configuration headers for more granular import control include the following: + +#### `X-Disable-Provenance` + +When this header is set to `true`: + +- The imported rules are not marked as provisioned. +- They can then be edited in the Grafana UI. +- They are excluded from the `GET` and `DELETE` operations on the [`/api/convert` endpoints](#compatible-endpoints). + +Do not enable this header when using the `rules sync` command, as it relies on the `GET` and `DELETE` operations to detect and update existing rules. + +#### `X-Grafana-Alerting-Alert-Rules-Paused` + +Set to `true` to import alert rules in paused state. + +#### `X-Grafana-Alerting-Recording-Rules-Paused` + +Set to `true` to import recording rules in paused state. + +#### `X-Grafana-Alerting-Datasource-UID` + +The UID of the data source to use for alert rule queries. + +#### `X-Grafana-Alerting-Target-Datasource-UID` + +The UID of the target data source for recording rules. If not specified, the value from `X-Grafana-Alerting-Datasource-UID` is used. + +#### `X-Grafana-Alerting-Folder-UID` + +Enter the UID of the target destination folder for imported rules. + +#### `X-Grafana-Alerting-Notification-Settings` + +JSON-encoded [`AlertRuleNotificationSettings` object](#alertrulenotificationsettings-object) that allows setting the contact point for the alert rules. + +{{< collapse title="AlertRuleNotificationSettings object" >}} + +##### AlertRuleNotificationSettings object + +When you set `X-Grafana-Alerting-Notification-Settings`, the header value must be a JSON-encoded object with the following keys: + +| Field | Type | Required | Example | Description | +| ----------------------- | ---------- | -------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------- | +| `receiver` | `string` | Yes | `"grafana-default-email"` | Name of the contact point (receiver) to which alerts are routed. Must exist in Grafana before import. | +| `group_by` | `[]string` | No | `["alertname","grafana_folder","cluster"]` | Label set used by Alertmanager to aggregate alerts into a single notification. | +| `group_wait` | `duration` | No | `"30s"` | How long Alertmanager waits before sending the first notification for a new group. | +| `group_interval` | `duration` | No | `"5m"` | Time to wait before adding new alerts to an existing group's next notification. | +| `repeat_interval` | `duration` | No | `"4h"` | Minimum time before a previously-sent notification is repeated. Must not be less than `group_interval`. | +| `mute_time_intervals` | `[]string` | No | `["maintenance"]` | One or more mute time interval names that silence alerts during those windows. | +| `active_time_intervals` | `[]string` | No | `["maintenance"]` | List of active time interval names. Alerts are suppressed unless the current time matches one of them. | + +{{< /collapse >}} + +### Compatible endpoints + +The API endpoints listed in this section are supported in Grafana and are used by mimirtool and cortextool, as shown earlier. + +The `POST` endpoints can be used to import data source–managed alert rules. + +| Endpoint | Method | Summary | +| -------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| POST | /convert/prometheus/config/v1/rules | Create or update multiple rule groups across multiple namespaces. Requires [`X-Grafana-Alerting-Datasource-UID`](#x-grafana-alerting-datasource-uid). | +| POST | /convert/prometheus/config/v1/rules/:namespaceTitle | Create or update a single rule group in a namespace. Requires [`X-Grafana-Alerting-Datasource-UID`](#x-grafana-alerting-datasource-uid). | + +The `GET` and `DELETE` endpoints work only with provisioned and imported alert rules. + +| Endpoint | Method | Summary | +| -------- | ---------------------------------------------------------- | --------------------------------------------------- | +| GET | /convert/prometheus/config/v1/rules | Get all imported rule groups across all namespaces. | +| GET | /convert/prometheus/config/v1/rules/:namespaceTitle | Get imported rule groups in a specific namespace. | +| DELETE | /convert/prometheus/config/v1/rules/:namespaceTitle | Delete all imported alert rules in a namespace. | +| DELETE | /convert/prometheus/config/v1/rules/:namespaceTitle/:group | Delete a specific imported rule group. | diff --git a/docs/sources/alerting/alerting-rules/alerting-migration/_index.md b/docs/sources/alerting/alerting-rules/alerting-migration/_index.md deleted file mode 100644 index 6aadd3e933e..00000000000 --- a/docs/sources/alerting/alerting-rules/alerting-migration/_index.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -canonical: https://grafana.com/docs/grafana/latest/alerting-rules/alerting-migration/ -description: Use the Grafana Alerting import tool to convert your datasource managed alert rules into Grafana managed alert rules -labels: - products: - - cloud - - enterprise - - oss -title: Import data source-managed alert rules -menuTitle: Import to Grafana-managed alert rules -weight: 600 -refs: - import-ds-rules-api: - - pattern: /docs/grafana/ - destination: /docs/grafana//alerting/alerting-rules/alerting-migration/migration-api/ - - pattern: /docs/grafana-cloud/ - destination: /docs/grafana-cloud/alerting-and-irm/alerting/alerting-rules/alerting-migration/migration-api/ - configure-recording-rules: - - pattern: /docs/grafana/ - destination: /docs/grafana//alerting/alerting-rules/create-recording-rules/create-grafana-managed-recording-rules/ - - pattern: /docs/grafana-cloud/ - destination: /docs/grafana-cloud/alerting-and-irm/alerting/alerting-rules/create-recording-rules/create-grafana-managed-recording-rules/ ---- - -# Import data source-managed alert rules - -Grafana Alerting provides multiple options for importing Mimir, Loki, and Prometheus alert rules as Grafana-managed alert rules. - -This guide shows you how to import data source–managed alert rules from existing data sources configured in Grafana Alerting. - -Alternatively, you can [use the API or command-line tools](ref:import-ds-rules-api) like `mimirtool` to convert and import rules from files. - -## Before you begin - -To use the migration tool, you need the following [RBAC permissions](/docs/grafana/latest/administration/roles-and-permissions/access-control/): - -- Alerting: Rules Writer -- Alerting: Set provisioning status -- Datasources: Reader -- Folders: Creator - {{< admonition type="note" >}} - The Folders permission is optional and only necessary if you want to create new folders for your target namespace. If your account doesn't have permissions to view a namespace, the tool creates a new one. It is a best practice to prepare an import plan before you convert all your alert rules. - {{< /admonition >}} - -## How it works - -When you use the import tool, a folder of data source-managed rules is copied to another folder as Grafana-managed alert rules, preserving the behavior of the rules, and the original alert rules are kept in their original location. - -When data source-managed alert rules are converted to Grafana-managed alert rules, the following are applied to the Grafana-managed alert rules: - -- All rules are given `rule_query_offset` offset value of 1m. -- The `missing_series_evals_to_resolve` is set to 1 for the new rules. -- The newly created rules are given unique UIDs. - -{{< admonition type="note" >}} -Plugin rules that have the label `__grafana_origin` are not included on alert rule imports. -{{< /admonition >}} - -### Evaluation of imported rules - -The imported rules are evaluated sequentially within each rule group, mirroring Prometheus behavior. This behavior is different from native Grafana-managed alert rules, where the evaluation order is not enforced. - -## Import alert rules - -To convert data source-managed alert rules to Grafana managed alerts: - -1. Go to **Alerting > Alert rules**. - -1. Navigate to the Data source-managed alert rules section and click **Import to Grafana-managed rules**. - -1. Select from the input source whether you want to import rules from and existing Loki or Mimir data source or from a Prometheus YAML file. - - If you choose to import a Prometheus data source rule from a YAML file, an, **Upload file** button appears. Click this to upload your YAML file. - -1. In the Data source dropdown, select the data source of the alert rules. - -1. In Additional settings, select a target folder or designate a new folder to import the rules into. - - If you import the rules into an existing folder, don't choose a folder with existing alert rules, as they could get overwritten. - -1. (Optional) Select a Namespace and/or Group to determine which rules are imported. - -1. (Optional) Turn on **Pause imported alerting rules**. - - Pausing stops alert rule evaluation and doesn’t create any alert instances for the newly created Grafana-managed alert rules. - -1. (Optional) Turn on **Pause imported recording rules**. - - Pausing stops alert rule evaluation behavior for the newly created Grafana-managed alert rules. - -1. Select which target data source the new recording rule is written to. - -1. Click **Import**. - - A preview shows the rules that will be imported. If your target folder contains folders with the same name of the imported folders, a warning displays to inform you. You can explore the warning to see a list of folders that might be overwritten. - - Click **Yes, import** to import the rules. diff --git a/docs/sources/alerting/alerting-rules/alerting-migration/migration-api.md b/docs/sources/alerting/alerting-rules/alerting-migration/migration-api.md deleted file mode 100644 index 42a731e9b89..00000000000 --- a/docs/sources/alerting/alerting-rules/alerting-migration/migration-api.md +++ /dev/null @@ -1,185 +0,0 @@ ---- -canonical: https://grafana.com/docs/grafana/latest/alerting-rules/alerting-migration/migration-api/ -description: Use the Grafana Alerting API import tool to convert your datasource managed alert rules into Grafana managed alert rules -labels: - products: - - cloud - - enterprise - - oss -title: Import data source-managed alert rules with Grafana Mimirtool -menuTitle: API alert rules import -weight: 601 -refs: - ui-import-tool: - - pattern: /docs/grafana/ - destination: /docs/grafana//alerting/alerting-rules/alerting-migration/ - - pattern: /docs/grafana-cloud/ - destination: /docs/grafana-cloud/alerting-and-irm/alerting/alerting-rules/alerting-migration/ - configure-recording-rules: - - pattern: /docs/grafana/ - destination: /docs/grafana//alerting/alerting-rules/create-recording-rules/create-grafana-managed-recording-rules/ - - pattern: /docs/grafana-cloud/ - destination: /docs/grafana-cloud/alerting-and-irm/alerting/alerting-rules/create-recording-rules/create-grafana-managed-recording-rules/ ---- - -# Import data source-managed alert rules with Grafana Mimirtool - -You can convert data source–managed alert rules, such as Prometheus alert rules, to Grafana-managed alert rules using [Grafana user interface](ref:ui-import-tool) or command-line tools. This guide shows you how to use the Grafana Mimirtool to import your data source-managed alert rules. - -## Before you begin - -You need to have the [Grafana Mimirtool](/docs/mimir/latest/manage/tools/mimirtool/) command-line tool installed. - -You need a service account with the following [RBAC permissions](/docs/grafana/latest/administration/roles-and-permissions/access-control/): - -- Alerting: Rules Reader -- Alerting: Rules Writer -- Alerting: Set provisioning status -- Datasources: Reader -- Folders: Creator -- Folders: Reader -- Folders: Writer - -You also need to create a service account token with your service account. Refer to the [documentation for more information on service accounts and service account tokens](/docs/grafana/latest/administration/service-accounts/). - -## How it works - -When you use the import tool, data source-managed rules are copied to another folder as Grafana-managed alert rules, preserving the behavior of the rules, and the original alert rules are kept in their original location. - -When data source-managed alert rules are converted to Grafana-managed alert rules, the following are applied to the Grafana-managed alert rules: - -- All rules are given `rule_query_offset` offset value of 1m. - Grafana OSS and Enterprise can configure this value in their conf: - ``` - [unified_alerting.prometheus_conversion] - rule_query_offset = 1m - ``` - If this value is set explicitly in a rule group, that value takes precedence over the configuration setting. -- The `missing_series_evals_to_resolve` is set to 1 for the new rules. -- The newly created rules are given unique UIDs. - If you don't want the UID to be automatically generated, you can specify a specific UID with the `__grafana_alert_rule_uid__` label. - -## Import alert rules with mimirtool or cortextool - -You can use either [`mimirtool`](/docs/mimir/latest/manage/tools/mimirtool/) or [`cortextool`](https://github.com/grafana/cortex-tools) (version `0.11.3` or later) to import data source–managed alert rules into Grafana as Grafana-managed alert rules. - -### mimirtool - -To convert and import them into a Grafana instance, you can use the `mimirtool rules load` command: - -```bash -MIMIR_ADDRESS=/api/convert/ \ -MIMIR_AUTH_TOKEN= \ -MIMIR_TENANT_ID=1 \ -mimirtool rules load rule_file.yaml \ - --extra-headers "X-Grafana-Alerting-Datasource-UID=" -``` - -This command imports Prometheus alert rules defined in `rule_file.yaml` as Grafana-managed alert rules. It's important to know that: - -1. When using the `/api/convert/` endpoint, `mimirtool` interacts with Grafana—not with a Mimir instance. In this case, `MIMIR_TENANT_ID` must always be set to `1`. -1. The [`X-Grafana-Alerting-Datasource-UID` header](#x-grafana-alerting-datasource-uid) configures the data source that the imported alert rules will query. Use multiple `--extra-headers` flags to include other [optional headers](#optional-headers). - -Similarly, the `rules sync` command can import and update Grafana-managed alert rules. - -```bash -MIMIR_ADDRESS=/api/convert/ \ -MIMIR_AUTH_TOKEN= \ -MIMIR_TENANT_ID=1 \ -mimirtool rules sync rule_file.yaml \ - --extra-headers "X-Grafana-Alerting-Datasource-UID=" \ - --concurrency 1 -``` - -The `--concurrency` flag must be set to `1`, as the default value of `8` may cause API errors. - -This `sync` command reads rules from the file, compares them with the existing Grafana-managed rules in the instance, and applies only the differences—creating, updating, or deleting rules as needed. - -```output -## Sync Summary: 0 Groups Created, 1 Groups Updated, 0 Groups Deleted -``` - -For more information other Mimirtool commands and options, see the [Mimirtool documentation](/docs/mimir/latest/manage/tools/mimirtool/#rules) and the [Mimir HTTP Rule API documentation](/docs/mimir/latest/references/http-api/#ruler-rules:~:text=config/v1/rules-,Get%20rule%20groups%20by%20namespace,DELETE%20%3Cprometheus%2Dhttp%2Dprefix%3E/config/v1/rules/%7Bnamespace%7D,-Delete%20tenant%20configuration). - -### cortextool - -For Loki alert rules, use [`cortextool`](https://github.com/grafana/cortex-tools) (version `0.11.3` or later) with the `--backend=loki` flag. For example: - -```bash -CORTEX_ADDRESS=/api/convert/ \ -CORTEX_AUTH_TOKEN= \ -CORTEX_TENANT_ID=1 \ -cortextool rules load loki_rules.yaml \ - --extra-headers "X-Grafana-Alerting-Datasource-UID=" \ - --backend=loki -``` - -### Compatible endpoints - -The API endpoints listed in this section are supported in Grafana and are used by mimirtool and cortextool, as shown earlier. - -The `POST` endpoints can be used to import data source–managed alert rules. - -| Endpoint | Method | Summary | -| -------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -| POST | /convert/prometheus/config/v1/rules | Create or update multiple rule groups across multiple namespaces. Requires [`X-Grafana-Alerting-Datasource-UID`](#x-grafana-alerting-datasource-uid). | -| POST | /convert/prometheus/config/v1/rules/:namespaceTitle | Create or update a single rule group in a namespace. Requires [`X-Grafana-Alerting-Datasource-UID`](#x-grafana-alerting-datasource-uid). | - -The `GET` and `DELETE` endpoints work only with provisioned and imported alert rules. - -| Endpoint | Method | Summary | -| -------- | ---------------------------------------------------------- | --------------------------------------------------- | -| GET | /convert/prometheus/config/v1/rules | Get all imported rule groups across all namespaces. | -| GET | /convert/prometheus/config/v1/rules/:namespaceTitle | Get imported rule groups in a specific namespace. | -| DELETE | /convert/prometheus/config/v1/rules/:namespaceTitle | Delete all imported alert rules in a namespace. | -| DELETE | /convert/prometheus/config/v1/rules/:namespaceTitle/:group | Delete a specific imported rule group. | - -### Optional Headers - -Additional configuration headers for more granular import control include the following: - -#### `X-Disable-Provenance` - -When this header is set to `true`: - -- The imported rules are not marked as provisioned. -- They can then be edited in the Grafana UI. -- They are excluded from the `GET` and `DELETE` operations on the `/api/convert` endpoints. - -#### `X-Grafana-Alerting-Alert-Rules-Paused` - -Set to "true" to import alert rules in paused state. - -#### `X-Grafana-Alerting-Recording-Rules-Paused` - -Set to "true" to import recording rules in paused state. - -#### `X-Grafana-Alerting-Datasource-UID` - -The UID of the data source to use for alert rule queries. - -#### `X-Grafana-Alerting-Target-Datasource-UID` - -The UID of the target data source for recording rules. If not specified, the value from `X-Grafana-Alerting-Datasource-UID` is used. - -#### `X-Grafana-Alerting-Folder-UID` - -Enter the UID of the target destination folder for imported rules. - -#### `X-Grafana-Alerting-Notification-Settings` - -JSON-encoded [`AlertRuleNotificationSettings` object](#alertrulenotificationsettings-object) that allows setting the contact point for the alert rules. - -##### AlertRuleNotificationSettings object - -When you set `X-Grafana-Alerting-Notification-Settings`, the header value must be a JSON-encoded object with the following keys: - -| Field | Type | Required | Example | Description | -| ----------------------- | ---------- | -------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------- | -| `receiver` | `string` | Yes | `"grafana-default-email"` | Name of the contact point (receiver) to which alerts are routed. Must exist in Grafana before import. | -| `group_by` | `[]string` | No | `["alertname","grafana_folder","cluster"]` | Label set used by Alertmanager to aggregate alerts into a single notification. | -| `group_wait` | `duration` | No | `"30s"` | How long Alertmanager waits before sending the first notification for a new group. | -| `group_interval` | `duration` | No | `"5m"` | Time to wait before adding new alerts to an existing group's next notification. | -| `repeat_interval` | `duration` | No | `"4h"` | Minimum time before a previously-sent notification is repeated. Must not be less than `group_interval`. | -| `mute_time_intervals` | `[]string` | No | `["maintenance"]` | One or more mute time interval names that silence alerts during those windows. | -| `active_time_intervals` | `[]string` | No | `["maintenance"]` | List of active time interval names. Alerts are suppressed unless the current time matches one of them. | diff --git a/docs/sources/alerting/fundamentals/alert-rule-evaluation/_index.md b/docs/sources/alerting/fundamentals/alert-rule-evaluation/_index.md index cf2576c1692..af2efc8aa46 100644 --- a/docs/sources/alerting/fundamentals/alert-rule-evaluation/_index.md +++ b/docs/sources/alerting/fundamentals/alert-rule-evaluation/_index.md @@ -25,11 +25,6 @@ refs: destination: /docs/grafana//alerting/alerting-rules/alerting-migration/ - pattern: /docs/grafana-cloud/ destination: /docs/grafana-cloud/alerting-and-irm/alerting/alerting-rules/alerting-migration/ - evaluation-of-imported-ds-rules: - - pattern: /docs/grafana/ - destination: /docs/grafana//alerting/alerting-rules/alerting-migration/#evaluation-of-imported-rules - - pattern: /docs/grafana-cloud/ - destination: /docs/grafana-cloud/alerting-and-irm/alerting/alerting-rules/alerting-migration/#evaluation-of-imported-rules --- # Alert rule evaluation @@ -56,7 +51,7 @@ Rules in different groups can be evaluated simultaneously. - **Data source-managed** rules within the same group are evaluated sequentially, one after the other—this is useful to ensure that recording rules are evaluated before alert rules. -- **Grafana-managed rules [imported from data source-managed rules](ref:import-ds-rules)** can be evaluated sequentially or in parallel, depending on how they are imported. For more information, refer to [Evaluation of imported rules](ref:evaluation-of-imported-ds-rules). +- **Grafana-managed rules [imported from data source-managed rules](ref:import-ds-rules)** are also evaluated sequentially. ## Pending period diff --git a/docs/sources/setup-grafana/configure-grafana/_index.md b/docs/sources/setup-grafana/configure-grafana/_index.md index 6db48dc9054..5442fd9c46a 100644 --- a/docs/sources/setup-grafana/configure-grafana/_index.md +++ b/docs/sources/setup-grafana/configure-grafana/_index.md @@ -1981,6 +1981,16 @@ Configures max number of alert annotations that Grafana stores. Default value is
+### `[unified_alerting.prometheus_conversion]` + +This section applies only to rules imported as Grafana-managed rules. For more information about the import process, refer to [Import data source-managed rules to Grafana-managed rules](/docs/grafana//alerting/alerting-rules/alerting-migration/). + +#### `rule_query_offset` + +Set the query offset to imported Grafana-managed rules when `query_offset` is not defined in the original rule group configuration. The default value is `1m`. + +
+ ### `[annotations]` #### `cleanupjob_batchsize`