Documentation Grafana Cloud Alerts and IRM Alerting Additional configuration Provision Alerting resources Use mimirtool to upload rules

Use mimirtool to upload alert and recording rules

Use mimirtool to create and upload alert and recording rules to your Grafana Cloud Metrics instance using YAML files. After created, you can access them from Grafana Cloud Alerting.

Install and configure access for mimirtool

mimirtool is a command-line tool for interacting with Grafana Mimir, which powers Grafana Cloud Metrics and Alerts. For detailed installation instructions and configuration options, refer to Mimirtool.

To use mimirtool with Grafana Cloud, you need the Mimir address of your Cloud Stack, a Cloud instance ID, and an API token with proper permissions.

Upload Prometheus rules definitions

With your instance ID, URL, and API token you’re now ready to upload your rules to your metrics instance. You can set the configuration options detailed in this guide, either as environment variables or command-line flags. Use the following commands and files as a reference.

Below is an example alert and rule definition YAML file. Take note of the namespace key which replaces the concept of “files” in this context given each instance only supports 1 configuration file.

yaml Copy

namespace: 'first_rules'
groups:
  - name: 'shopping_service_rules_and_alerts'
    rules:
      - alert: 'PromScrapeFailed'
        annotations:
          message: 'Prometheus failed to scrape a target {{ $labels.job }}  / {{ $labels.instance }}'
        expr: 'up != 1'
        for: '1m'
        labels:
          'severity': 'critical'
      - record: 'job:up:sum'
        expr: 'sum by(job) (up)'

Although both recording and alerting rules are defined under the key rules the difference between a rule and an alert is generally (as there are others) whenever the key record or alert is defined.

With this file, you can run the following commands to upload your rules file in your Metrics or Logs instance. Keep in mind that these are example commands for your Metrics instance, and they use placeholders and command line flags. Follow a similar pattern for your Logs instances by switching the address to the correct one. The examples also assume that files are located in the same directory.

bash Copy

mimirtool rules load first_rules.yml \
--address=https://prometheus-us-central1.grafana.net \
--id=<yourID> \
--key=<yourKey>

Next, confirm that the rules were uploaded correctly by running:

bash Copy

mimirtool rules list \
--address=https://prometheus-us-central1.grafana.net \
--id=<yourID> \
--key=<yourKey>

Output is a list that shows you all the namespaces and rule groups for your instance ID:

bash Copy

Namespace   | Rule Group
first_rules | shopping_service_rules_and_alerts

You can also print the rules:

bash Copy

mimirtool rules print \
--address=https://prometheus-us-central1.grafana.net \
--id=<yourID> \
--key=<yourKey>

Output from the print command should look like this:

yaml Copy

first_rules:
  - name: shopping_service_rules_and_alerts
    interval: 0s
    rules:
      - alert: PromScrapeFailed
        expr: up != 1
        for: 1m
        labels:
          severity: critical
        annotations:
          message: Prometheus failed to scrape a target {{ $labels.job }}  / {{ $labels.instance }}
      - record: job:up:sum
        expr: sum by(job) (up)

See also

• Configure Alertmanagers using mimirtool
• Mimirtool
• Alerting and recording rules for Grafana Loki