From f6bf1c2e74f974dabe306566fac5d9006eba0dae Mon Sep 17 00:00:00 2001
From: "Johnny K." <johnny.kartheiser@grafana.com>
Date: Thu, 24 Apr 2025 18:35:20 -0500
Subject: [PATCH] docs: recorded queries migration documentation

draft
---
 .../administration/recorded-queries/index.md  |  7 ++-
 .../migrate-recorded-queries.md               | 51 +++++++++++++++++++
 2 files changed, 57 insertions(+), 1 deletion(-)
 create mode 100644 docs/sources/alerting/alerting-rules/create-recording-rules/migrate-recorded-queries.md

diff --git a/docs/sources/administration/recorded-queries/index.md b/docs/sources/administration/recorded-queries/index.md
index fdeaa7da656..5beeb000be7 100644
--- a/docs/sources/administration/recorded-queries/index.md
+++ b/docs/sources/administration/recorded-queries/index.md
@@ -15,7 +15,12 @@ title: Recorded queries
 weight: 300
 ---
 
-# Recorded queries
+# DEPRECIATED Recorded queries
+
+{{% admonition type="warning" %}}
+Recorded queries are deprecated. Please use the new [Grafana-managed recording rules](/docs/grafana/latest/alerting/alerting-rules/create-recording-rules/create-grafana-managed-recording-rules) instead.
+To learn how to migrate your recorded queries to Grafana-managed recording rules, refer to the migration documentation [here.](/docs/grafana/latest/alerting/alerting-rules/create-recording-rules/migrate-recorded-queries)
+{{% /admonition %}}
 
 Recorded queries allow you to see trends over time by taking a snapshot of a data point on a set interval. This can give you insight into historic trends.
 
diff --git a/docs/sources/alerting/alerting-rules/create-recording-rules/migrate-recorded-queries.md b/docs/sources/alerting/alerting-rules/create-recording-rules/migrate-recorded-queries.md
new file mode 100644
index 00000000000..3c14361270e
--- /dev/null
+++ b/docs/sources/alerting/alerting-rules/create-recording-rules/migrate-recorded-queries.md
@@ -0,0 +1,51 @@
+---
+canonical: https://grafana.com/docs/grafana/latest/alerting/alerting-rules/create-recording-rules/migrate-recorded-queries/
+description: Learn how to migrate your depreciated recorded queries to Grafana-managed recording rules. 
+keywords:
+  - grafana
+  - alerting
+  - guide
+  - rules
+  - recording rules
+  - recorded queries
+  - configure
+labels:
+  products:
+    - cloud
+    - enterprise
+    - oss
+title: Migrate recorded queries
+weight: 402
+---
+
+# Migrate recorded queries
+
+Users can transpose their [now-depreciated recorded queries](/docs/grafana/latest/administration/recorded-queries/) into Grafana-managed recording rules in a few easy steps. The query promql for each recorded query has been exposed on the recorded queries list along with the existing datasource, time range, and interval values to simplify the migration process. 
+
+## Migrate your recorded queries to Grafana-managed alert rules
+
+1. Navigate to **Administration > Plugins and Data > Recorded queries.**
+
+1. Note the Datasource, Query Promql, Interval, and Time range and copy them somewhere accessible. 
+
+    {{< figure alt="Example of relevant recorded query information"  src="/media/docs/alerting/rec-query-example.png" max-width="800px" >}}
+
+1. Now navigate to **Alerting > Alert rules.**
+
+1. In the Grafana-managed section of the Alert rules page, click **+ New recording**.
+
+    Add a name for your Recording Rule and a name for the new metric that the recording rule generates.
+
+1. Select your datasource and paste your ratio query promql into the query builder.
+
+    Click **Options** and validate that the timerange is the same as your recorded query.
+
+1. Select the Folder you would like the rule to be created in.
+
+1. Add any labels to the rule.
+
+1. Select or create an evaluation group. Set your evaluation group’s evaluation interval to the interval of your recorded query.
+
+1. Review your rule and click Save **rule and exit** when you are finished.
+
+1. Update any areas where the recorded query was referenced to use the new Grafana-managed recording rule.