How to import Prometheus-style alerts and recording rules to Grafana-managed alerts and recording rules

Grafana Alerting has evolved dramatically since the legacy dashboard-alert days. Today, Grafana-managed alerts power enterprise-scale monitoring in Grafana Cloud and on-prem installations. And over the last two years, we’ve added RBAC, state history, versioning, and much more.

At the same time, our own monitoring at Grafana Labs relies heavily on Prometheus-style alerts—a situation that’s not uncommon for our users, too. Prometheus-compatible systems let you express alerting logic close to your data and in a simple YAML format, and manage those alerts with tools like mimirtool or cortextool.

But during an internal hackathon a few months ago, a few of us wondered: “What if we could easily migrate Prometheus-style alerts into Grafana without rewriting them?” And that question ultimately led to new functionality in Grafana 12 that lets you bulk import your existing Prometheus, Grafana Loki, or Grafana Mimir rule files into Grafana-managed alerts and recording rules, directly through the UI.

Under the hood: how Prometheus rules become native Grafana alerts

When we started this project, our main idea was simple: the existing tooling and CI/CD pipelines should just work. To make this possible, we added APIs to Grafana that are compatible with Mimir and Loki, so if your workflows already use mimirtool or cortextool you can simply point them to your Grafana instance and everything continues to work. Behind the scenes, Grafana takes your rule definitions from the YAML and converts it to Grafana alert rules.

However, converting alerts from Prometheus to Grafana isn’t always as straightforward as it might seem. Prometheus and Grafana have some differences in how they evaluate alert rules, which means that an alert rule simply copied from Prometheus could start firing unexpectedly in Grafana. For example, Prometheus treats empty query results as healthy:

Copy

vector(0)  	  -> value 0 -> alert fires
vector(0) > 0  -> empty   -> alert does not fire

Grafana Alerting, on the other hand, has more alert states, including No Data when the query returns no results, or Error when the rule evaluation fails, etc. Without adjustment and additional threshold conditions, the first query above would be normal in Grafana, and the second query would start firing.

To preserve a Prometheus-like behavior, the importer adds a small math expression after the Prometheus query to the rule pipeline. The query itself remains unchanged, but Grafana Alerting interprets its result in the same way Prometheus does.

These are only a few examples of the differences, but ensuring the evaluation compatibility was one side of the story. We also wanted to give users the ability to use Grafana’s additional alerting features, even when importing via existing tools. To make these available through the API and still keep it compatible, the import APIs accept custom HTTP headers. These headers, supported by mimirtool and cortextool, let you specify things like target folder for the new rules, choose the data source, or import rules in a paused state without touching the YAML. For more details on these headers check our documentation.

Meet the import UI and API

Modern observability stacks often have thousands of alert rules created over years of resource monitoring. Manually recreating data source alert rules as Grafana-managed rules is an arduous, painstaking task with a high probability of errors. 

Starting with Grafana 12, you can import your existing Prometheus, Loki, or Mimir rule files into Grafana-managed rules directly through the UI. Data sources like Mimir or Loki have a ruler API and rules from them can be imported to Grafana right in the UI. And if you are working with Prometheus, you can use the import API.

To get started, go to “Alerting” and then go to the “Alert rules” menu, and under the “Data source-managed” alert rules section, you’ll find a new Import to Grafana-managed rules option. This opens up a page where you can:

• Choose your data source you want to get alerts imported from.
• Select or create a target folder for the new imported rules.
• Define a namespace, group, and pause evaluation of imported rules. This optional step allows you to filter which rules are imported and control whether they start evaluating or remain paused until you’re ready to enable them.
• Preview the import and check for any conflicts or overwrites.

Once you’re happy with the setup, just click Import, and your rules will be imported. And now you can start taking advantage of all the powerful features available with Grafana-managed rules.

Ready to migrate?

At Grafana Labs, we have already adopted this internally: we have CI/CD pipelines that continuously upload thousands of our own data source-managed alerts into Grafana. This has unlocked the ability for our own engineering teams to:

• Receive visualizations on our alerts
• Simplify our routing strategy, routing alerts directly to our Grafana Cloud IRM contact point
• View our alerts on our Service Center page during team stand-ups
• Add granular RBAC to our rules for increased access control
• Manage exceptions in our rules with no data and error states

Give it a try yourself. Check out our documentation to get started today!

Grafana Cloud is the easiest way to get started with metrics, logs, traces, dashboards, and more. We have a generous forever-free tier and plans for every use case. Sign up for free now!