[v9.5.x] CI: Fix verify-prerelease-assets pipeline (#72231)

CI: Fix verify-prerelease-assets pipeline (#72226)

* Fix verify-prerelease-assets pipeline

* Comment out unused assets

(cherry picked from commit 142cbc2ec6)

.betterer.results

@@ -2523,8 +2523,7 @@ exports[`better eslint`] = {
       [0, 0, 0, "Unexpected any. Specify a different type.", "3"],
       [0, 0, 0, "Unexpected any. Specify a different type.", "4"],
       [0, 0, 0, "Unexpected any. Specify a different type.", "5"],
-      [0, 0, 0, "Unexpected any. Specify a different type.", "6"],
-      [0, 0, 0, "Unexpected any. Specify a different type.", "7"]
+      [0, 0, 0, "Unexpected any. Specify a different type.", "6"]
     ],
     "public/app/features/dashboard/state/DashboardModel.test.ts:5381": [
       [0, 0, 0, "Unexpected any. Specify a different type.", "0"]

.drone.star

@@ -11,22 +11,30 @@ load("scripts/drone/events/pr.star", "pr_pipelines")
 load("scripts/drone/events/main.star", "main_pipelines")
 load(
     "scripts/drone/events/release.star",
-    "artifacts_page_pipeline",
-    "enterprise2_pipelines",
-    "enterprise_pipelines",
     "integration_test_pipelines",
     "oss_pipelines",
     "publish_artifacts_pipelines",
     "publish_npm_pipelines",
     "publish_packages_pipeline",
+    "verify_release_pipeline",
+)
+load(
+    "scripts/drone/rgm.star",
+    "rgm",
 )
 load(
     "scripts/drone/pipelines/publish_images.star",
     "publish_image_pipelines_public",
-    "publish_image_pipelines_security",
 )
-load("scripts/drone/pipelines/github.star", "publish_github_pipeline")
-load("scripts/drone/pipelines/aws_marketplace.star", "publish_aws_marketplace_pipeline")
+load(
+    "scripts/drone/pipelines/ci_images.star",
+    "publish_ci_build_container_image_pipeline",
+    "publish_ci_windows_test_image_pipeline",
+)
+load(
+    "scripts/drone/pipelines/windows.star",
+    "windows_test_backend",
+)
 load("scripts/drone/version.star", "version_branch_pipelines")
 load("scripts/drone/events/cron.star", "cronjobs")
 load("scripts/drone/vault.star", "secrets")
@@ -36,24 +44,20 @@ def main(_ctx):
         pr_pipelines() +
         main_pipelines() +
         oss_pipelines() +
-        enterprise_pipelines() +
-        enterprise2_pipelines() +
-        enterprise2_pipelines(
-            prefix = "custom-",
-            trigger = {"event": ["custom"]},
-        ) +
         publish_image_pipelines_public() +
-        publish_image_pipelines_security() +
-        publish_github_pipeline("public") +
-        publish_github_pipeline("security") +
-        publish_aws_marketplace_pipeline("public") +
-        publish_artifacts_pipelines("security") +
         publish_artifacts_pipelines("public") +
         publish_npm_pipelines() +
         publish_packages_pipeline() +
-        artifacts_page_pipeline() +
+        [verify_release_pipeline()] +
+        [windows_test_backend({
+            "event": ["promote"],
+            "target": ["test-windows"],
+        }, "oss", "testing")] +
+        rgm() +
         version_branch_pipelines() +
         integration_test_pipelines() +
+        publish_ci_windows_test_image_pipeline() +
+        publish_ci_build_container_image_pipeline() +
         cronjobs() +
         secrets()
     )

.github/CODEOWNERS

@@ -228,6 +228,7 @@
 /Dockerfile @grafana/grafana-delivery
 /Makefile @grafana/grafana-delivery
 /scripts/build/ @grafana/grafana-delivery
+/scripts/list-release-artifacts.sh @grafana/grafana-delivery
 
 # OSS Plugin Partnerships backend code
 /pkg/tsdb/cloudwatch/ @grafana/aws-datasources
@@ -428,6 +429,7 @@ lerna.json @grafana/frontend-ops
 /public/gazetteer/ @ryantxu
 /public/img/ @grafana/grafana-frontend-platform
 /public/lib/ @grafana/grafana-frontend-platform
+/public/lib/monaco-languages/kusto.ts @grafana/partner-datasources
 /public/maps/ @ryantxu
 /public/robots.txt @grafana/frontend-ops
 /public/sass/ @grafana/grafana-frontend-platform
@@ -569,6 +571,7 @@ embed.go @grafana/grafana-as-code
 /.github/pr-commands.json @marefr
 /.github/renovate.json5 @grafana/frontend-ops
 /.github/teams.yml @armandgrillet
+/.github/workflows/auto-milestone.yml @grafana/grafana-delivery
 /.github/workflows/backport.yml @grafana/grafana-delivery
 /.github/workflows/bump-version.yml @grafana/grafana-delivery
 /.github/workflows/close-milestone.yml @grafana/grafana-delivery
@@ -591,6 +594,8 @@ embed.go @grafana/grafana-as-code
 /.github/workflows/pr-codeql-analysis-python.yml @DanCech
 /.github/workflows/pr-commands-closed.yml @tolzhabayev
 /.github/workflows/pr-commands.yml @marefr
+/.github/workflows/pr-patch-check.yml @grafana/grafana-delivery
+/.github/workflows/sync-mirror.yml @grafana/grafana-delivery
 /.github/workflows/publish-technical-documentation-next.yml @grafana/docs-grafana
 /.github/workflows/publish-technical-documentation-release.yml @grafana/docs-grafana
 /.github/workflows/remove-milestone.yml @grafana/grafana-frontend-platform

.github/pr-checks.json

@@ -46,4 +46,4 @@
     },
     "targetUrl": "https://github.com/grafana/grafana/blob/main/contribute/merge-pull-request.md#include-in-changelog-and-release-notes"
   }
-]
+]

.github/workflows/auto-milestone.yml

@@ -0,0 +1,22 @@
+name: Auto-milestone
+on:
+  pull_request:
+    types:
+      - closed
+
+jobs:
+  main:
+    runs-on: ubuntu-latest
+    steps:
+      - name: "Generate token"
+        id: generate_token
+        uses: tibdex/github-app-token@b62528385c34dbc9f38e5f4225ac829252d1ea92
+        with:
+          app_id: ${{ secrets.GRAFANA_DELIVERY_BOT_APP_ID }}
+          private_key: ${{ secrets.GRAFANA_DELIVERY_BOT_APP_PEM }}
+
+      - name: Run auto-milestone
+        uses: grafana/grafana-github-actions-go/auto-milestone@main
+        with:
+          pr: ${{ github.event.pull_request.number }}
+          token: ${{ steps.generate_token.outputs.token }}

.github/workflows/backport.yml

@@ -17,10 +17,16 @@ jobs:
           ref: main
       - name: Install Actions
         run: npm install --production --prefix ./actions
+      - name: "Generate token"
+        id: generate_token
+        uses: tibdex/github-app-token@b62528385c34dbc9f38e5f4225ac829252d1ea92
+        with:
+          app_id: ${{ secrets.GRAFANA_DELIVERY_BOT_APP_ID }}
+          private_key: ${{ secrets.GRAFANA_DELIVERY_BOT_APP_PEM }}
       - name: Run backport
         uses: ./actions/backport
         with:
           metricsWriteAPIKey: ${{secrets.GRAFANA_MISC_STATS_API_KEY}}
-          token: ${{secrets.GH_BOT_ACCESS_TOKEN}}
+          token: ${{ steps.generate_token.outputs.token }}
           labelsToAdd: "backport,no-changelog"
           title: "[{{base}}] {{originalTitle}}"

.github/workflows/bump-version.yml

@@ -6,12 +6,12 @@ on:
         description: 'Needs to match, exactly, the name of a milestone. The version to be released please respect: major.minor.patch or major.minor.patch-beta<number> format. example: 7.4.3 or 7.4.3-beta1'
         required: true
 env:
-    YARN_ENABLE_IMMUTABLE_INSTALLS: false
+  YARN_ENABLE_IMMUTABLE_INSTALLS: false
 jobs:
   main:
     runs-on: ubuntu-latest
     steps:
-    # This is a basic workflow to help you get started with Actions
+      # This is a basic workflow to help you get started with Actions
       - uses: actions-ecosystem/action-regex-match@v2.0.2
         if: ${{ github.event.inputs.version != '' }}
         id: regex-match
@@ -68,8 +68,14 @@ jobs:
           node-version: '16'
       - name: Install Actions
         run: npm install --production --prefix ./actions
-      - name: Run bump version (manually invoked)        
+      - name: "Generate token"
+        id: generate_token
+        uses: tibdex/github-app-token@b62528385c34dbc9f38e5f4225ac829252d1ea92
+        with:
+          app_id: ${{ secrets.GRAFANA_DELIVERY_BOT_APP_ID }}
+          private_key: ${{ secrets.GRAFANA_DELIVERY_BOT_APP_PEM }}
+      - name: Run bump version (manually invoked)
         uses: ./actions/bump-version
         with:
-          token: ${{ secrets.GH_BOT_ACCESS_TOKEN }}
+          token: ${{ steps.generate_token.outputs.token }}
           metricsWriteAPIKey: ${{ secrets.GRAFANA_MISC_STATS_API_KEY }}

.github/workflows/close-milestone.yml

@@ -11,9 +11,7 @@ on:
         description: Needs to match, exactly, the name of a milestone
         required: true
         type: string
-    secrets:
-      token:
-        required: true
+
 jobs:
   main:
     runs-on: ubuntu-latest
@@ -26,14 +24,20 @@ jobs:
           ref: main
       - name: Install Actions
         run: npm install --production --prefix ./actions
+      - name: "Generate token"
+        id: generate_token
+        uses: tibdex/github-app-token@b62528385c34dbc9f38e5f4225ac829252d1ea92
+        with:
+          app_id: ${{ secrets.GRAFANA_DELIVERY_BOT_APP_ID }}
+          private_key: ${{ secrets.GRAFANA_DELIVERY_BOT_APP_PEM }}
       - name: Close milestone (manually invoked)
         if: ${{ github.event.inputs.version != '' }}
         uses: ./actions/close-milestone
         with:
-          token: ${{ secrets.GH_BOT_ACCESS_TOKEN }}
+          token: ${{ steps.generate_token.outputs.token }}
       - name: Close milestone (workflow invoked)
         if: ${{ inputs.version_call != '' }}
         uses: ./actions/close-milestone
         with:
           version_call: ${{ inputs.version_call }}
-          token: ${{ secrets.token }}
+          token: ${{ steps.generate_token.outputs.token }}

.github/workflows/codeql-analysis.yml

@@ -44,7 +44,7 @@ jobs:
       name: Set go version
       uses: actions/setup-go@v3
       with:
-        go-version: '1.19.2'
+        go-version: '1.20.6'
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL

.github/workflows/github-release.yml

@@ -3,7 +3,7 @@ on:
   workflow_dispatch:
     inputs:
       version:
-        required: true        
+        required: true
         description: Needs to match, exactly, the name of a milestone (NO v prefix)
 jobs:
   main:
@@ -14,11 +14,17 @@ jobs:
         with:
           repository: "grafana/grafana-github-actions"
           path: ./actions
-          ref: main    
+          ref: main
       - name: Install Actions
         run: npm install --production --prefix ./actions
+      - name: "Generate token"
+        id: generate_token
+        uses: tibdex/github-app-token@b62528385c34dbc9f38e5f4225ac829252d1ea92
+        with:
+          app_id: ${{ secrets.GRAFANA_DELIVERY_BOT_APP_ID }}
+          private_key: ${{ secrets.GRAFANA_DELIVERY_BOT_APP_PEM }}
       - name: Run github release action
         uses: ./actions/github-release
         with:
-          token: ${{secrets.GH_BOT_ACCESS_TOKEN}}
+          token: ${{ steps.generate_token.outputs.token }}
           metricsWriteAPIKey: ${{secrets.GRAFANA_MISC_STATS_API_KEY}}

.github/workflows/milestone.yml

@@ -10,12 +10,10 @@ jobs:
     uses: grafana/grafana/.github/workflows/remove-milestone.yml@main
     with:
       version_call: ${{ github.event.inputs.version_input }}
-    secrets:
-      token: ${{ secrets.GH_BOT_ACCESS_TOKEN }}
+    secrets: inherit
   call-close-milestone:
     uses: grafana/grafana/.github/workflows/close-milestone.yml@main
     with:
       version_call: ${{ github.event.inputs.version_input }}
-    secrets:
-      token: ${{ secrets.GH_BOT_ACCESS_TOKEN }}
-    needs: call-remove-milestone
+    secrets: inherit
+    needs: call-remove-milestone

.github/workflows/pr-codeql-analysis-go.yml

@@ -23,7 +23,7 @@ jobs:
     - name: Set go version
       uses: actions/setup-go@v3
       with:
-        go-version: '1.19.2'
+        go-version: '1.20.6'
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL

.github/workflows/pr-patch-check.yml

@@ -0,0 +1,24 @@
+# Owned by grafana-delivery-squad
+# Intended to be dropped into the base repo Ex: grafana/grafana
+name: Check for patch conflicts
+run-name: check-patch-conflicts-${{ github.base_ref }}-${{ github.head_ref }}
+on:
+  pull_request_target:
+    types:
+      - opened
+    branches:
+      - "main"
+      - "v*.*.*"
+      - "release-*"
+
+# Since this is run on a pull request, we want to apply the patches intended for the
+# target branch onto the source branch, to verify compatibility before merging.
+jobs:
+  trigger_downstream_patch_check:
+    uses: grafana/security-patch-actions/.github/workflows/test-patches.yml@main
+    with:
+      src_repo: "${{ github.repository }}"
+      src_ref: "${{ github.head_ref }}" # this is the source branch name, Ex: "feature/newthing"
+      patch_repo: "${{ github.repository }}-security-patches"
+      patch_ref: "${{ github.base_ref }}" # this is the target branch name, Ex: "main"
+    secrets: inherit

.github/workflows/remove-milestone.yml

@@ -11,9 +11,7 @@ on:
         description: Needs to match, exactly, the name of a milestone
         required: true
         type: string
-    secrets:
-      token:
-        required: true
+
 jobs:
   main:
     runs-on: ubuntu-latest
@@ -26,14 +24,20 @@ jobs:
           ref: main
       - name: Install Actions
         run: npm install --production --prefix ./actions
+      - name: "Generate token"
+        id: generate_token
+        uses: tibdex/github-app-token@b62528385c34dbc9f38e5f4225ac829252d1ea92
+        with:
+          app_id: ${{ secrets.GRAFANA_DELIVERY_BOT_APP_ID }}
+          private_key: ${{ secrets.GRAFANA_DELIVERY_BOT_APP_PEM }}
       - name: Remove milestone from open issues (manually invoked)
         if: ${{ github.event.inputs.version != '' }}
         uses: ./actions/remove-milestone
         with:
-          token: ${{ secrets.GH_BOT_ACCESS_TOKEN }}
+          token: ${{ steps.generate_token.outputs.token }}
       - name: Remove milestone from open issues (workflow invoked)
         if: ${{ inputs.version_call != '' }}
         uses: ./actions/remove-milestone
         with:
           version_call: ${{ inputs.version_call }}
-          token: ${{ secrets.token }}
+          token: ${{ steps.generate_token.outputs.token }}

.github/workflows/sync-mirror.yml

@@ -0,0 +1,25 @@
+# Owned by grafana-delivery-squad
+# Intended to be dropped into the base repo, Ex: grafana/grafana
+name: Sync to mirror
+run-name: sync-to-mirror-${{ github.base_ref }}-${{ github.head_ref }}
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - "main"
+      - "v*.*.*"
+      - "release-*"
+
+# This is run after the pull request has been merged, so we'll run against the target branch
+jobs:
+  trigger_downstream_patch_mirror:
+    concurrency: patch-mirror-${{ github.ref }}
+    uses: grafana/security-patch-actions/.github/workflows/mirror-branch-and-apply-patches.yml@main
+    if: github.repository == 'grafana/grafana'
+    with:
+      ref: "${{ github.ref_name }}" # this is the target branch name, Ex: "main"
+      src_repo: "${{ github.repository }}"
+      dest_repo: "${{ github.repository }}-security-mirror"
+      patch_repo: "${{ github.repository }}-security-patches"
+    secrets: inherit
+

.github/workflows/update-changelog.yml

@@ -17,9 +17,15 @@ jobs:
           ref: main
       - name: Install Actions
         run: npm install --production --prefix ./actions
-      - name: Run update changelog (manually invoked)        
-        uses: ./actions/update-changelog
+      - name: "Generate token"
+        id: generate_token
+        uses: tibdex/github-app-token@b62528385c34dbc9f38e5f4225ac829252d1ea92
         with:
-          token: ${{ secrets.GH_BOT_ACCESS_TOKEN }}
+          app_id: ${{ secrets.GRAFANA_DELIVERY_BOT_APP_ID }}
+          private_key: ${{ secrets.GRAFANA_DELIVERY_BOT_APP_PEM }}
+      - name: Run update changelog (manually invoked)
+        uses: grafana/grafana-github-actions-go/update-changelog@main
+        with:
+          token: ${{ steps.generate_token.outputs.token }}
           metricsWriteAPIKey: ${{ secrets.GRAFANA_MISC_STATS_API_KEY }}
           grafanabotForumKey: ${{ secrets.GRAFANABOT_FORUM_KEY }}

.gitignore

@@ -191,3 +191,6 @@ public/api-spec.json
 deployment_tools_config.json
 
 .betterer.cache
+
+# Temporary file for backporting PRs
+.pr-body.txt

CHANGELOG.md

@@ -1,3 +1,63 @@
+<!-- 9.5.6 START -->
+
+# 9.5.6 (2023-07-11)
+
+### Bug fixes
+
+- **Dashboard:** Fix library panels in collapsed rows not getting updated. [#66640](https://github.com/grafana/grafana/issues/66640), [@VictorColomb](https://github.com/VictorColomb)
+- **Auth:** Add and document option for enabling email lookup. [@vtorosyan](https://github.com/vtorosyan)
+
+<!-- 9.5.6 END -->
+<!-- 9.5.5 START -->
+
+# 9.5.5 (2023-06-22)
+
+### Bug fixes
+
+- **Auth:** Fixed CVE-2023-3128. [#70580](https://github.com/grafana/grafana/issues/70580), [@zerok](https://github.com/zerok)
+- **Auth:** Show invite button if disable login form is set to false. [#70154](https://github.com/grafana/grafana/issues/70154), [@IevaVasiljeva](https://github.com/IevaVasiljeva)
+- **Azure:** Fix Kusto auto-completion for Azure datasources (#69685). [#69694](https://github.com/grafana/grafana/issues/69694), [@aangelisc](https://github.com/aangelisc)
+- **RBAC:** Remove legacy AC editor and admin role on new dashboard route. [#68776](https://github.com/grafana/grafana/issues/68776), [@eleijonmarck](https://github.com/eleijonmarck)
+- **Revert:** Allow editors to access GET /datasources. [#68654](https://github.com/grafana/grafana/issues/68654), [@eleijonmarck](https://github.com/eleijonmarck)
+- **Settings:** Add ability to override `skip_org_role_sync` with Env variables. [#68375](https://github.com/grafana/grafana/issues/68375), [@eleijonmarck](https://github.com/eleijonmarck)
+
+<!-- 9.5.5 END -->
+<!-- 9.5.3 START -->
+
+# 9.5.3 (2023-06-06)
+
+### Bug fixes
+
+- **Query:** Prevent crash while executing concurrent mixed queries
+- **Alerting:** Require alert.notifications:write permissions to test receivers and templates
+
+<!-- 9.5.3 END -->
+<!-- 9.5.2 START -->
+
+# 9.5.2 (2023-05-03)
+
+### Features and enhancements
+
+- **Chore:** Upgrade Go to 1.20.4. [#67757](https://github.com/grafana/grafana/issues/67757), [@papagian](https://github.com/papagian)
+- **Alerting:** Scheduler use rule fingerprint instead of version. [#67516](https://github.com/grafana/grafana/issues/67516), [@grafanabot](https://github.com/grafanabot)
+
+### Bug fixes
+
+- **TimeSeries:** Fix leading null-fill for missing intervals. [#67571](https://github.com/grafana/grafana/issues/67571), [@leeoniya](https://github.com/leeoniya)
+- **Dashboard:** Revert fixed header shown on mobile devices in the new panel header. [#67514](https://github.com/grafana/grafana/issues/67514), [@grafanabot](https://github.com/grafanabot)
+- **PostgreSQL:** Fix tls certificate issue by downgrading lib/pq. [#67393](https://github.com/grafana/grafana/issues/67393), [@grafanabot](https://github.com/grafanabot)
+- **Provisioning:** Fix provisioning issues with legacy alerting and data source permissions. [#67377](https://github.com/grafana/grafana/issues/67377), [@grafanabot](https://github.com/grafanabot)
+- **Alerting:** Fix misleading status code in provisioning API. [#67358](https://github.com/grafana/grafana/issues/67358), [@grafanabot](https://github.com/grafanabot)
+- **Explore:** Update table min height (#67321). [#67332](https://github.com/grafana/grafana/issues/67332), [@adrapereira](https://github.com/adrapereira)
+- **DataLinks:** Encoded URL fixed. [#67291](https://github.com/grafana/grafana/issues/67291), [@juanicabanas](https://github.com/juanicabanas)
+- **Loki:** Fix log samples using `instant` queries (#67271). [#67275](https://github.com/grafana/grafana/issues/67275), [@svennergr](https://github.com/svennergr)
+- **Panel Header Fix:** Implement new Panel Header on Angular Panels . [#67228](https://github.com/grafana/grafana/issues/67228), [@grafanabot](https://github.com/grafanabot)
+- **Azure Monitor:** Fix bug that was not showing resources for certain locations. [#67216](https://github.com/grafana/grafana/issues/67216), [@grafanabot](https://github.com/grafanabot)
+- **Alerting:** Fix panic when reparenting receivers to groups following an attempted rename via Provisioning. [#67175](https://github.com/grafana/grafana/issues/67175), [@grafanabot](https://github.com/grafanabot)
+- **Cloudwatch Logs:** Clarify Cloudwatch Logs Limits. [#67101](https://github.com/grafana/grafana/issues/67101), [@grafanabot](https://github.com/grafanabot)
+- **SAML:** Fix IdP metadata caching so that invalid metadata doesn't get cached. (Enterprise)
+
+<!-- 9.5.2 END -->
 <!-- 9.5.1 START -->
 
 # 9.5.1 (2023-04-26)

Dockerfile

@@ -3,7 +3,7 @@
 ARG BASE_IMAGE=alpine:3.17
 ARG JS_IMAGE=node:18-alpine3.17
 ARG JS_PLATFORM=linux/amd64
-ARG GO_IMAGE=golang:1.20.3-alpine3.17
+ARG GO_IMAGE=golang:1.20.6-alpine3.17
 
 ARG GO_SRC=go-builder
 ARG JS_SRC=js-builder

Makefile

@@ -192,7 +192,7 @@ build-docker-full-ubuntu: ## Build Docker image based on Ubuntu for development.
 	--build-arg COMMIT_SHA=$$(git rev-parse --short HEAD) \
 	--build-arg BUILD_BRANCH=$$(git rev-parse --abbrev-ref HEAD) \
 	--build-arg BASE_IMAGE=ubuntu:20.04 \
-	--build-arg GO_IMAGE=golang:1.20.3 \
+	--build-arg GO_IMAGE=golang:1.20.6 \
 	--tag grafana/grafana$(TAG_SUFFIX):dev-ubuntu \
 	$(DOCKER_BUILD_ARGS)
 

conf/defaults.ini

@@ -531,6 +531,9 @@ sigv4_verbose_logging = false
 # Set to true to enable Azure authentication option for HTTP-based datasources
 azure_auth_enabled = false
 
+# Use email lookup in addition to the unique ID provided by the IdP
+oauth_allow_insecure_email_lookup = false
+
 #################################### Anonymous Auth ######################
 [auth.anonymous]
 # enable anonymous access
@@ -564,6 +567,7 @@ allowed_organizations =
 role_attribute_path =
 role_attribute_strict = false
 allow_assign_grafana_admin = false
+skip_org_role_sync = false
 tls_skip_verify_insecure = false
 
 #################################### GitLab Auth #########################

conf/sample.ini

@@ -520,6 +520,9 @@
 # Set to skip the organization role from JWT login and use system's role assignment instead.
 ; skip_org_role_sync = false
 
+# Use email lookup in addition to the unique ID provided by the IdP
+;oauth_allow_insecure_email_lookup = false
+
 #################################### Anonymous Auth ######################
 [auth.anonymous]
 # enable anonymous access
@@ -553,6 +556,7 @@
 ;role_attribute_path =
 ;role_attribute_strict = false
 ;allow_assign_grafana_admin = false
+;skip_org_role_sync = false
 
 #################################### GitLab Auth #########################
 [auth.gitlab]

contribute/merge-pull-request.md

@@ -13,7 +13,6 @@ The following checklist/summary should give you a quick overview of what to ask/
 - Reviewed and approved?
 - All checks passed?
 - Proper pull request title?
-- Milestone assigned?
 - Add to changelog/release notes?
 - Needs backporting?
 
@@ -40,10 +39,18 @@ See [formatting guidelines](create-pull-request.md#formatting-guidelines) for mo
 
 ### Assign a milestone
 
-A milestone **should** be added to every pull request. Several things in the Grafana release process requires at least pull requests to be in a milestone, for example [generating changelog/release notes](#include-in-changelog-and-release-notes).
+Several things in the Grafana release process requires at least pull requests to be in a milestone, for example [generating changelog/release notes](#include-in-changelog-and-release-notes).
 
 This makes it easier to track what changes go into a certain release. Without this information, release managers have to go through git commits which is not an efficient process.
 
+That being said, _you don't have to assign a milestone manually_ to a pull request.
+Instead, when it is merged & closed then a bot will look for the most appropriate miletone and assign it to the pull request.
+
+That milestone should always reflect the branch that the pull request is merged into.
+For every major and minor release there is a milestone ending with `.x` (e.g. `10.0.x` for the 10.0.x releases).
+Pull requests targetting `main` should use the `.x` milestone of the next minor (or major) version (you can find that version number inside the `package.json` file).
+Backport pull requestss should use the version of the target branch (e.g. `9.4.x` for the `v9.4.x` branch).
+
 ### Include in changelog and release notes?
 
 At Grafana we generate the [changelog](https://github.com/grafana/grafana/blob/main/CHANGELOG.md) and [release notes](https://grafana.com/docs/grafana/latest/release-notes/) based on merged pull requests. Including changes in the changelog/release notes is very important to provide a somewhat complete picture of what changes a Grafana release actually includes.
@@ -78,15 +85,15 @@ The changelog/release notes are divided into sections and here's a description o
 
 **Features and enhancements:**
 
-Milestone assigned and labeled with `add to changelog` and any of the other section rules don't apply.
+Labeled with `add to changelog` and any of the other section rules don't apply.
 
 **Bug fixes:**
 
-Milestone assigned and labeled with `add to changelog` and either labeled with `type/bug` or the pull request title contains `fix` or `fixes`.
+Labeled with `add to changelog` and either labeled with `type/bug` or the pull request title contains `fix` or `fixes`.
 
 **Plugin development fixes & changes:**
 
-Milestone assigned and labeled with `area/grafana/toolkit`, `area/grafana/ui` or `area/grafana/runtime`.
+Labeled with `area/grafana/toolkit`, `area/grafana/ui` or `area/grafana/runtime`.
 
 **Deprecations:**
 

docs/Makefile

@@ -1,33 +1,8 @@
-.PHONY: pull docs docs-quick docs-no-pull docs-test docs-local-static
+.ONESHELL:
+.DELETE_ON_ERROR:
+export SHELL     := bash
+export SHELLOPTS := pipefail:errexit
+MAKEFLAGS += --warn-undefined-variables
+MAKEFLAGS += --no-builtin-rule
 
-PODMAN = $(shell if command -v podman >/dev/null 2>&1; then echo podman; else echo docker; fi)
-IMAGE = grafana/docs-base:latest
-CONTENT_PATH = /hugo/content/docs/grafana/latest
-LOCAL_STATIC_PATH = ../../website/static
-PORT = 3002:3002
-
-pull:
-	$(PODMAN) pull $(IMAGE)
-
-docs: pull
-	$(PODMAN) run --init -v $(shell pwd)/sources:$(CONTENT_PATH):Z -p $(PORT) --rm -it $(IMAGE) make server
-
-docs-preview: pull
-	$(PODMAN) run --init -v $(shell pwd)/sources:$(CONTENT_PATH):Z -p $(PORT) --rm -it $(IMAGE) make server BUILD_DRAFTS=true
-
-docs-no-pull:
-	$(PODMAN) run --init -v $(shell pwd)/sources:$(CONTENT_PATH):Z -p $(PORT) --rm -it $(IMAGE) make server
-
-docs-test: pull
-	$(PODMAN) run --init -v $(shell pwd)/sources:$(CONTENT_PATH):Z --rm -it $(IMAGE) make prod
-
-# expects that you have grafana/website checked out in same path as the grafana repo.
-docs-local-static: pull
-	if [ ! -d "$(LOCAL_STATIC_PATH)" ]; then echo "local path (website project) $(LOCAL_STATIC_PATH) not found"]; exit 1; fi
-	$(PODMAN) run --init -v $(shell pwd)/sources:$(CONTENT_PATH):Z \
-		-v $(shell pwd)/$(LOCAL_STATIC_PATH):/hugo/static:Z -p $(PORT) --rm -it $(IMAGE)
-
-.PHONY: doc-validator/%
-doc-validator/%: ## Run doc-validator on a specific path. To lint the path /docs/sources/administration, run 'make doc-validator/administration'.
-doc-validator/%:
-	$(PODMAN) run --init -v "$(shell pwd)/sources:/sources" grafana/doc-validator:latest --skip-image-validation --include=$(subst doc-validator/,,$@) ./sources /docs/grafana/latest
+include docs.mk

docs/README.md

@@ -1,14 +1,19 @@
 # Building the docs locally
 
-When you contribute to documentation, it is a good practice to build the docs on your local machine to make sure your changes appear as you expect. This README explains the process for doing that.
+When you contribute to documentation, it's a good practice to build the docs on your local machine to make sure your changes appear as you expect. This README explains the process for doing that.
+
+To build a local version, you need to run a process in a Docker container.
+Grafana periodically updates the Docker image, [`docs-base`](https://hub.docker.com/r/grafana/docs-base), to update the styling of the Docs.
 
 ## Requirements
 
-Docker >= 2.1.0.3
-Yarn >= 1.22.4
+- Docker >= 2.1.0.3
+- Yarn >= 1.22.4
 
 ## Build the doc site
 
+First, make sure the Docker daemon is running on your machine. Then, follow these steps:
+
 1. On the command line, first change to the docs folder: `cd docs`.
 1. Run `make docs`. This launches a preview of the website with the current grafana docs at `http://localhost:3002/docs/grafana/latest/` which will refresh automatically when changes are made to content in the `sources` directory.
 

docs/docs.mk

@@ -0,0 +1,117 @@
+# The source of this file is https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/docs.mk.
+# 4.0.0 (2023-06-06)
+include variables.mk
+-include variables.mk.local
+
+.ONESHELL:
+.DELETE_ON_ERROR:
+export SHELL     := bash
+export SHELLOPTS := pipefail:errexit
+MAKEFLAGS += --warn-undefined-variables
+MAKEFLAGS += --no-builtin-rule
+
+.DEFAULT_GOAL: help
+
+# Adapted from https://www.thapaliya.com/en/writings/well-documented-makefiles/
+.PHONY: help
+help: ## Display this help.
+help:
+	@awk 'BEGIN { \
+		FS = ": ##"; \
+		printf "Usage:\n  make <target>\n\nTargets:\n" \
+	} \
+	/^[a-zA-Z0-9_\.\-\/%]+: ##/ { printf "  %-15s %s\n", $$1, $$2 }' \
+	$(MAKEFILE_LIST)
+
+GIT_ROOT := $(shell git rev-parse --show-toplevel)
+
+PODMAN := $(shell if command -v podman >/dev/null 2>&1; then echo podman; else echo docker; fi)
+
+ifeq ($(PROJECTS),)
+$(error "PROJECTS variable must be defined in variables.mk")
+endif
+
+# First project is considered the primary one used for doc-validator.
+PRIMARY_PROJECT := $(subst /,-,$(firstword $(subst :, ,$(firstword $(PROJECTS)))))
+
+# Name for the container.
+ifeq ($(origin DOCS_CONTAINER), undefined)
+export DOCS_CONTAINER := $(PRIMARY_PROJECT)-docs
+endif
+
+# Host port to publish container port to.
+ifeq ($(origin DOCS_HOST_PORT), undefined)
+export DOCS_HOST_PORT := 3002
+endif
+
+# Container image used to perform Hugo build.
+ifeq ($(origin DOCS_IMAGE), undefined)
+export DOCS_IMAGE := grafana/docs-base:latest
+endif
+
+# Container image used for doc-validator linting.
+ifeq ($(origin DOC_VALIDATOR_IMAGE), undefined)
+export DOC_VALIDATOR_IMAGE := grafana/doc-validator:latest
+endif
+
+# Container image used for vale linting.
+ifeq ($(origin VALE_IMAGE), undefined)
+export VALE_IMAGE := grafana/vale:latest
+endif
+
+# PATH-like list of directories within which to find projects.
+# If all projects are checked out into the same directory, ~/repos/ for example, then the default should work.
+ifeq ($(origin REPOS_PATH), undefined)
+export REPOS_PATH := $(realpath $(GIT_ROOT)/..)
+endif
+
+# How to treat Hugo relref errors.
+ifeq ($(origin HUGO_REFLINKSERRORLEVEL), undefined)
+export HUGO_REFLINKSERRORLEVEL := WARNING
+endif
+
+.PHONY: docs-rm
+docs-rm: ## Remove the docs container.
+	$(PODMAN) rm -f $(DOCS_CONTAINER)
+
+.PHONY: docs-pull
+docs-pull: ## Pull documentation base image.
+	$(PODMAN) pull $(DOCS_IMAGE)
+
+make-docs: ## Fetch the latest make-docs script.
+make-docs:
+	if [[ ! -f "$(PWD)/make-docs" ]]; then
+		echo 'WARN: No make-docs script found in the working directory. Run `make update` to download it.' >&2
+		exit 1
+	fi
+
+.PHONY: docs
+docs: ## Serve documentation locally, which includes pulling the latest `DOCS_IMAGE` (default: `grafana/docs-base:latest`) container image. See also `docs-no-pull`.
+docs: docs-pull make-docs
+	$(PWD)/make-docs $(PROJECTS)
+
+.PHONY: docs-no-pull
+docs-no-pull: ## Serve documentation locally without pulling the `DOCS_IMAGE` (default: `grafana/docs-base:latest`) container image.
+docs-no-pull: make-docs
+	$(PWD)/make-docs $(PROJECTS)
+
+.PHONY: docs-debug
+docs-debug: ## Run Hugo web server with debugging enabled. TODO: support all SERVER_FLAGS defined in website Makefile.
+docs-debug: make-docs
+	WEBSITE_EXEC='hugo server --bind 0.0.0.0 --port 3002 --debug' $(PWD)/make-docs $(PROJECTS)
+
+.PHONY: doc-validator
+doc-validator: ## Run doc-validator on the entire docs folder.
+doc-validator: make-docs
+	DOCS_IMAGE=$(DOC_VALIDATOR_IMAGE) $(PWD)/make-docs $(PROJECTS)
+
+.PHONY: vale
+vale: ## Run vale on the entire docs folder.
+vale: make-docs
+	DOCS_IMAGE=$(VALE_IMAGE) $(PWD)/make-docs $(PROJECTS)
+
+.PHONY: update
+update: ## Fetch the latest version of this Makefile and the `make-docs` script from Writers' Toolkit.
+	curl -s -LO https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/docs.mk
+	curl -s -LO https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/make-docs
+	chmod +x make-docs

docs/make-docs

@@ -0,0 +1,449 @@
+#!/bin/sh
+# The source of this file is https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/make-docs.
+# 4.1.0 (2023-06-16)
+
+set -ef
+
+readonly DOCS_CONTAINER="${DOCS_CONTAINER:-make-docs}"
+readonly DOCS_HOST_PORT="${DOCS_HOST_PORT:-3002}"
+readonly DOCS_IMAGE="${DOCS_IMAGE:-grafana/docs-base:latest}"
+
+readonly DOC_VALIDATOR_INCLUDE="${DOC_VALIDATOR_INCLUDE:-.+\.md$}"
+readonly DOC_VALIDATOR_SKIP_CHECKS="${DOC_VALIDATOR_SKIP_CHECKS:-^image-}"
+
+readonly HUGO_REFLINKSERRORLEVEL="${HUGO_REFLINKSERRORLEVEL:-WARNING}"
+readonly VALE_MINALERTLEVEL="${VALE_MINALERTLEVEL:-error}"
+readonly WEBSITE_EXEC="${WEBSITE_EXEC:-make server-docs}"
+# If set, the docs-base image will run a prebuild script that sets up Hugo mounts.
+readonly WEBSITE_MOUNTS="${WEBSITE_MOUNTS:-}"
+
+PODMAN="$(if command -v podman >/dev/null 2>&1; then echo podman; else echo docker; fi)"
+
+about() {
+  cat <<EOF
+Test documentation locally with multiple source repositories.
+
+The REPOS_PATH environment variable is a colon (:) separated list of paths in which to look for project repositories.
+EOF
+}
+
+usage() {
+  cat <<EOF
+Usage:
+  REPOS_PATH=<PATH[:<PATH>...]> $0 [<PROJECT>[:<VERSION>[:<REPO>[:<DIR>]]]...]
+
+Examples:
+  REPOS_PATH=~/ext/grafana/ $0 writers-toolkit tempo:latest helm-charts/mimir-distributed:latest:mimir:docs/sources/mimir-distributed
+EOF
+}
+
+if [ $# -lt 1 ]; then
+  cat <<EOF >&2
+ERRR: arguments required but not supplied.
+
+$(about)
+
+$(usage)
+EOF
+  exit 1
+fi
+
+readonly REPOS_PATH="${REPOS_PATH:-$(realpath "$(git rev-parse --show-toplevel)/..")}"
+
+if [ -z "${REPOS_PATH}" ]; then
+  cat <<EOF >&2
+ERRR: REPOS_PATH environment variable is required but has not been provided.
+
+$(usage)
+EOF
+  exit 1
+fi
+
+SOURCES_as_code='as-code-docs'
+SOURCES_enterprise_metrics='backend-enterprise'
+SOURCES_enterprise_metrics_='backend-enterprise'
+SOURCES_grafana_cloud='website'
+SOURCES_grafana_cloud_k6='k6-docs'
+SOURCES_grafana_cloud_data_configuration_integrations='cloud-onboarding'
+SOURCES_grafana_cloud_frontend_observability_faro_web_sdk='faro-web-sdk'
+SOURCES_grafana_cloud_machine_learning='machine-learning'
+SOURCES_helm_charts_mimir_distributed='mimir'
+SOURCES_helm_charts_tempo_distributed='tempo'
+SOURCES_opentelemetry='opentelemetry-docs'
+
+VERSIONS_as_code='UNVERSIONED'
+VERSIONS_grafana_cloud='UNVERSIONED'
+VERSIONS_grafana_cloud_k6='UNVERSIONED'
+VERSIONS_grafana_cloud_data_configuration_integrations='UNVERSIONED'
+VERSIONS_grafana_cloud_frontend_observability_faro_web_sdk='UNVERSIONED'
+VERSIONS_grafana_cloud_machine_learning='UNVERSIONED'
+VERSIONS_opentelemetry='UNVERSIONED'
+VERSIONS_technical_documentation='UNVERSIONED'
+VERSIONS_website='UNVERSIONED'
+VERSIONS_writers_toolkit='UNVERSIONED'
+
+PATHS_grafana_cloud='content/docs/grafana-cloud'
+PATHS_helm_charts_mimir_distributed='docs/sources/helm-charts/mimir-distributed'
+PATHS_helm_charts_tempo_distributed='docs/sources/helm-charts/tempo-distributed'
+PATHS_mimir='docs/sources/mimir'
+PATHS_tempo='docs/sources/tempo'
+PATHS_website='content/docs'
+
+# identifier STR
+# Replace characters that are not valid in an identifier with underscores.
+identifier() {
+  echo "$1" | tr -C '[:alnum:]_\n' '_'
+}
+
+# aget ARRAY KEY
+# Get the value of KEY from associative array ARRAY.
+# Characters that are not valid in an identifier are replaced with underscores.
+aget() {
+  eval echo '$'"$(identifier "$1")_$(identifier "$2")"
+}
+
+# new_proj populates a new project structure.
+new_proj() {
+  _project="$1"
+  _version="$2"
+  _repo="$3"
+  _path="$4"
+
+  # If version is not set, use the script mapping of project to default versions if it exists.
+  # Fallback to 'latest'.
+  if [ -z "${_version}" ]; then
+    if [ -z "$(aget VERSIONS "${_project}")" ]; then
+      _version=latest
+    else
+      _version="$(aget VERSIONS "${_project}")"
+    fi
+  fi
+
+  # If repo is not set, use the script mapping of project to repo name if it exists.
+  # Fallback to using the project name.
+  if [ -z "${_repo}" ]; then
+    if [ -z "$(aget SOURCES "${_project}")" ]; then
+      _repo="${_project}"
+    else
+      _repo="$(aget SOURCES "${_project}")"
+    fi
+  fi
+
+  # If path is not set, use the script mapping of project to docs sources path if it exists.
+  # Fallback to using 'docs/sources'.
+  if [ -z "${_path}" ]; then
+    if [ -z "$(aget PATHS "${_project}")" ]; then
+      _path="docs/sources"
+    else
+      _path="$(aget PATHS "${_project}")"
+    fi
+  fi
+
+  echo "${_project}:${_version}:${_repo}:${_path}"
+  unset _project _version _repo _path
+}
+
+# proj_url returns the webserver URL for a project.
+# It expects a complete project structure as input.
+proj_url() {
+  IFS=: read -r _project _version _ _ <<POSIX_HERESTRING
+$1
+POSIX_HERESTRING
+
+  if [ "${_project}" = 'website' ]; then
+    echo "http://localhost:${DOCS_HOST_PORT}/docs/"
+
+    unset _project _version
+    return
+  fi
+
+  if [ -z "${_version}" ] || [ "${_version}" = 'UNVERSIONED' ]; then
+    echo "http://localhost:${DOCS_HOST_PORT}/docs/${_project}/"
+  else
+    echo "http://localhost:${DOCS_HOST_PORT}/docs/${_project}/${_version}/"
+  fi
+
+  unset _project _version
+}
+
+# proj_ver returns the version for a project.
+# It expects a complete project structure as input.
+proj_ver() {
+  IFS=: read -r _ _ver _ _ <<POSIX_HERESTRING
+$1
+POSIX_HERESTRING
+
+  echo "${_ver}"
+  unset _ver
+}
+
+# proj_dst returns the container path to content source for a project.
+# It expects a complete project structure as input.
+proj_dst() {
+  IFS=: read -r _project _version _ _ <<POSIX_HERESTRING
+$1
+POSIX_HERESTRING
+
+  if [ "${_project}" = 'website' ]; then
+    echo '/hugo/content/docs'
+
+    unset _project _version
+    return
+  fi
+
+  if [ -z "${_version}" ] || [ "${_version}" = 'UNVERSIONED' ]; then
+    echo "/hugo/content/docs/${_project}"
+  else
+    echo "/hugo/content/docs/${_project}/${_version}"
+  fi
+
+  unset _project _version
+}
+
+# repo_path returns the host path to the project repository.
+# It looks for the provided repository name in each of the paths specified in the REPOS_PATH environment variable.
+repo_path() {
+  _repo="$1"
+  IFS=:
+  for lookup in ${REPOS_PATH}; do
+    if [ -d "${lookup}/${_repo}" ]; then
+      echo "${lookup}/${_repo}"
+      unset _path _repo
+      return
+    fi
+  done
+  unset IFS
+
+  echo "ERRR: could not find project '${_repo}' in any of the paths in REPOS_PATH '${REPOS_PATH}'." >&2
+  echo "NOTE: you must have a checkout of the project '${_repo}' at '${REPOS_PATH##:*}/${_repo}'." >&2
+  echo "NOTE: if you have cloned the repository into a directory with a different name, consider changing it to ${_repo}." >&2
+  unset _repo
+  exit 1
+}
+
+# proj_src returns the host path to content source for a project.
+# It expects a complete project structure as input.
+# It looks for the provided repository name in each of the paths specified in the REPOS_PATH environment variable.
+proj_src() {
+  IFS=: read -r _ _ _repo _path <<POSIX_HERESTRING
+$1
+POSIX_HERESTRING
+
+  _repo="$(repo_path "${_repo}")"
+  echo "${_repo}/${_path}"
+
+  unset _path _repo
+}
+
+# proj_canonical returns the canonical absolute path partial URI for a project.
+# It expects a complete project structure as input.
+proj_canonical() {
+  IFS=: read -r _project _version _ _ <<POSIX_HERESTRING
+$1
+POSIX_HERESTRING
+
+  if [ "${_project}" = 'website' ]; then
+    echo '/docs'
+
+    unset _project _version
+    return
+  fi
+
+  if [ -z "${_version}" ] || [ "${_version}" = 'UNVERSIONED' ]; then
+    echo "/docs/${_project}"
+  else
+    echo "/docs/${_project}/${_version}"
+  fi
+
+  unset _project _version
+}
+
+proj_to_url_src_dst_ver() {
+  _url="$(proj_url "$1")"
+  _src="$(proj_src "$1")"
+  _dst="$(proj_dst "$1")"
+  _ver="$(proj_ver "$1")"
+
+  echo "${_url}^${_src}^${_dst}^${_ver}"
+  unset _url _src _dst _ver
+}
+
+url_src_dst_vers() {
+  for arg in "$@"; do
+    IFS=: read -r _project _version _repo _path <<POSIX_HERESTRING
+$arg
+POSIX_HERESTRING
+
+    case "${_project}" in
+      # Workaround for arbitrary mounts where the version field is expected to be the local directory
+      # and the repo field is expected to be the container directory.
+      arbitrary)
+        echo "${_project}^${_version}^${_repo}^" # TODO
+        ;;
+      logs)
+        proj_to_url_src_dst_ver "$(new_proj loki "${_version}")"
+        proj_to_url_src_dst_ver "$(new_proj enterprise-logs "${_version}")"
+        ;;
+      metrics)
+        proj_to_url_src_dst_ver "$(new_proj mimir "${_version}")"
+        proj_to_url_src_dst_ver "$(new_proj helm-charts/mimir-distributed "${_version}")"
+        proj_to_url_src_dst_ver "$(new_proj enterprise-metrics "${_version}")"
+        ;;
+      traces)
+        proj_to_url_src_dst_ver "$(new_proj tempo "${_version}")"
+        proj_to_url_src_dst_ver "$(new_proj enterprise-traces "${_version}")"
+        ;;
+      *)
+        proj_to_url_src_dst_ver "$(new_proj "${_project}" "${_version}" "${_repo}" "${_path}")"
+        ;;
+    esac
+  done
+
+  unset _project _version _repo _path
+}
+
+url_src_dst_vers="$(url_src_dst_vers "$@")"
+
+volumes=""
+redirects=""
+
+for arg in "$@"; do
+  IFS=: read -r _project _ _repo _ <<POSIX_HERESTRING
+${arg}
+POSIX_HERESTRING
+  if [ "${_project}" = website ]; then
+    _repo="$(repo_path website)"
+    volumes="--volume=${_repo}/config:/hugo/config"
+    volumes="${volumes} --volume=${_repo}/layouts/partials:/hugo/layouts/partials"
+    volumes="${volumes} --volume=${_repo}/layouts/shortcodes:/hugo/layouts/shortcodes"
+  fi
+  unset _project _repo
+done
+
+for x in ${url_src_dst_vers}; do
+  IFS='^' read -r _url _src _dst _ver <<POSIX_HERESTRING
+$x
+POSIX_HERESTRING
+
+  if [ "${_url}" != "arbitrary" ]; then
+    if [ ! -f "${_src}/_index.md" ]; then
+      echo "ERRR: Index file '${_src}/_index.md' does not exist." >&2
+      echo "Is '${_src}' the correct source directory?" >&2
+      exit 1
+    fi
+  fi
+
+  echo "DEBG: Mounting '${_src}' at container path '${_dst}'" >&2
+  if [ -z "${volumes}" ]; then
+    volumes="--volume=${_src}:${_dst}"
+  else
+    volumes="${volumes} --volume=${_src}:${_dst}"
+  fi
+
+  if [ -n "${_ver}" ] && [ "${_ver}" != 'UNVERSIONED' ]; then
+    if [ -z "${redirects}" ]; then
+      redirects="${_dst}^${_ver}"
+    else
+      redirects="${redirects} ${_dst}^${_ver}"
+    fi
+  fi
+  unset _url _src _dst _ver
+done
+
+IFS=':' read -r image _ <<POSIX_HERESTRING
+${DOCS_IMAGE}
+POSIX_HERESTRING
+
+case "${image}" in
+  'grafana/doc-validator')
+    proj="$(new_proj "$1")"
+    echo
+    "${PODMAN}" run \
+      --init \
+      --interactive \
+      --name "${DOCS_CONTAINER}" \
+      --platform linux/amd64 \
+      --rm \
+      --tty \
+      ${volumes} \
+      "${DOCS_IMAGE}" \
+      "--include=${DOC_VALIDATOR_INCLUDE}" \
+      "--skip-checks=${DOC_VALIDATOR_SKIP_CHECKS}" \
+      /hugo/content/docs \
+      "$(proj_canonical "${proj}")" | sed "s#$(proj_dst "${proj}")#sources#"
+    ;;
+  'grafana/vale')
+    proj="$(new_proj "$1")"
+    echo
+    "${PODMAN}" run \
+      --init \
+      --interactive \
+      --name "${DOCS_CONTAINER}" \
+      --platform linux/amd64 \
+      --rm \
+      --tty \
+      ${volumes} \
+      "${DOCS_IMAGE}" \
+      "--minAlertLevel=${VALE_MINALERTLEVEL}" \
+      --config=/etc/vale/.vale.ini \
+      --output=line \
+      /hugo/content/docs | sed "s#$(proj_dst "${proj}")#sources#"
+    ;;
+  *)
+    tempfile="$(mktemp -t make-docs.XXX)"
+    cat <<EOF >"${tempfile}"
+#!/usr/bin/env bash
+for redirect in ${redirects}; do
+  IFS='^' read -r path ver <<<"\${redirect}"
+  echo -e "---\\nredirectURL: \"\${path/\/hugo\/content/}\"\\ntype: redirect\\nversioned: true\\n---\\n" > "\${path/\${ver}/_index.md}"
+done
+
+for x in "${url_src_dst_vers}"; do
+  IFS='^' read -r _ _ dst _ <<<"\${x}"
+
+  while [[ -n "\${dst}" ]]; do
+    touch "\${dst}/_index.md"
+    dst="\${dst%/*}"
+  done
+done
+
+if [[ -n "${WEBSITE_MOUNTS}" ]]; then
+  unset WEBSITE_SKIP_MOUNTS
+fi
+
+${WEBSITE_EXEC}
+EOF
+    chmod +x "${tempfile}"
+    volumes="${volumes} --volume=$(realpath "${tempfile}"):/entrypoint"
+    readonly volumes
+
+    echo
+    echo "Documentation will be served at the following URLs:"
+    for x in ${url_src_dst_vers}; do
+      IFS='^' read -r url _ _ <<POSIX_HERESTRING
+$x
+POSIX_HERESTRING
+
+      if [ -n "${url}" ]; then
+        if [ "${_url}" != "arbitrary" ]; then
+          echo "  ${url}"
+        fi
+      fi
+    done
+
+    echo
+    "${PODMAN}" run \
+      --env "HUGO_REFLINKSERRORLEVEL=${HUGO_REFLINKSERRORLEVEL}" \
+      --init \
+      --interactive \
+      --name "${DOCS_CONTAINER}" \
+      --platform linux/amd64 \
+      --publish "${DOCS_HOST_PORT}:3002" \
+      --publish "3003:3003" \
+      --rm \
+      --tty \
+      ${volumes} \
+      "${DOCS_IMAGE}" \
+      /entrypoint
+    ;;
+esac

docs/sources/_index.md

@@ -3,6 +3,192 @@ aliases:
   - /docs/grafana/v1.1/
   - /docs/grafana/v3.1/
   - guides/reference/admin/
+cascade:
+  # Until a better mechanism for arrangement is thought of, the following sequence should be ordered alphabetically by the `_target.path` value.
+  - _target: { path: /docs/grafana/** } # Default to every page having "Enterprise" and "Open source" labels.
+    labels:
+      products:
+        - enterprise
+        - oss
+
+  - _target: { path: /docs/grafana/** }
+    labels:
+      products:
+        - enterprise
+        - oss
+
+  - _target: { path: /docs/grafana/*/administration/** }
+    labels:
+      products:
+        - cloud
+        - enterprise
+        - oss
+
+  - _target: { path: /docs/grafana/*/administration/enterprise-licensing/** }
+    labels:
+      products:
+        - enterprise
+
+  - _target: { path: /docs/grafana/*/administration/organization-management/** }
+    labels:
+      products:
+        - enterprise
+        - oss
+
+  - _target: { path: /docs/grafana/*/administration/provisioning/** }
+    labels:
+      products:
+        - enterprise
+        - oss
+
+  - _target: { path: /docs/grafana/*/administration/recorded-queries/** }
+    labels:
+      products:
+        - cloud
+        - enterprise
+
+  - _target: { path: /docs/grafana/*/administration/roles-and-permissions/access-control/** }
+    labels:
+      products:
+        - cloud
+        - enterprise
+
+  - _target: { path: /docs/grafana/*/administration/stats-and-license/** }
+    labels:
+      products:
+        - enterprise
+        - oss
+
+  - _target: { path: /docs/grafana/*/alerting/** }
+    labels:
+      products:
+        - cloud
+        - enterprise
+        - oss
+
+  - _target: { path: /docs/grafana/*/dashboards/** }
+    labels:
+      products:
+        - cloud
+        - enterprise
+        - oss
+
+  - _target: { path: /docs/grafana/*/datasources/** }
+    labels:
+      products:
+        - cloud
+        - enterprise
+        - oss
+
+  - _target: { path: /docs/grafana/*/explore/** }
+    labels:
+      products:
+        - cloud
+        - enterprise
+        - oss
+
+  - _target: { path: /docs/grafana/*/fundamentals/** }
+    labels:
+      products:
+        - cloud
+        - enterprise
+        - oss
+
+  - _target: { path: /docs/grafana/*/introduction/grafana-cloud/** }
+    labels:
+      products:
+        - cloud
+
+  - _target: { path: /docs/grafana/*/introduction/grafana-enterprise/** }
+    labels:
+      products:
+        - enterprise
+
+  - _target: { path: /docs/grafana/*/panels-visualizations/** }
+    labels:
+      products:
+        - cloud
+        - enterprise
+        - oss
+
+  - _target: { path: /docs/grafana/*/release-notes/** }
+    labels:
+      products:
+        - cloud
+        - enterprise
+        - oss
+
+  - _target: { path: /docs/grafana/*/search/** }
+    labels:
+      products:
+        - cloud
+        - enterprise
+        - oss
+
+  - _target: { path: /docs/grafana/*/setup-grafana/configure-security/audit-grafana/** }
+    labels:
+      products:
+        - cloud
+        - enterprise
+
+  - _target: { path: /docs/grafana/*/setup-grafana/configure-security/configure-authentication/** }
+    labels:
+      products:
+        - cloud
+        - enterprise
+        - oss
+
+  - _target: { path: /docs/grafana/*/setup-grafana/configure-security/configure-authentication/enhanced-ldap/** }
+    labels:
+      products:
+        - cloud
+        - enterprise
+
+  - _target: { path: /docs/grafana/*/setup-grafana/configure-security/configure-authentication/saml/** }
+    labels:
+      products:
+        - cloud
+        - enterprise
+
+  - _target:
+      path: /docs/grafana/*/setup-grafana/configure-security/configure-database-encryption/encrypt-secrets-using-hashicorp-key-vault/**
+    labels:
+      products:
+        - cloud
+        - enterprise
+
+  - _target: { path: /docs/grafana/*/setup-grafana/configure-security/configure-request-security/** }
+    labels:
+      products:
+        - cloud
+        - enterprise
+        - oss
+
+  - _target: { path: /docs/grafana/*/setup-grafana/configure-security/configure-team-sync/** }
+    labels:
+      products:
+        - cloud
+        - enterprise
+
+  - _target: { path: /docs/grafana/*/setup-grafana/configure-security/export-logs/** }
+    labels:
+      products:
+        - cloud
+        - oss
+
+  - _target: { path: /docs/grafana/*/troubleshooting/** }
+    labels:
+      products:
+        - cloud
+        - enterprise
+        - oss
+
+  - _target: { path: /docs/grafana/*/whatsnew/** }
+    labels:
+      products:
+        - cloud
+        - enterprise
+        - oss
 description: Guides, installation, and feature documentation
 keywords:
   - grafana

docs/sources/administration/_index.md

@@ -1,10 +1,4 @@
 ---
-cascade:
-  labels:
-    products:
-      - cloud
-      - enterprise
-      - oss
 description: Administration
 title: Administration
 weight: 40

docs/sources/administration/enterprise-licensing/_index.md

@@ -8,10 +8,6 @@ aliases:
   - ../enterprise/license/license-expiration/
   - ../enterprise/license/license-restrictions/
   - license-restrictions/
-cascade:
-  labels:
-    products:
-      - enterprise
 description: Activate and manage a Grafana Enterprise license
 keywords:
   - grafana

docs/sources/administration/organization-management/index.md

@@ -8,10 +8,6 @@ description: Describes how to use organizations to isolate dashboard to users an
 keywords:
   - organizations
   - dashboards
-labels:
-  products:
-    - enterprise
-    - oss
 menuTitle: Manage organizations
 title: Manage organizations
 weight: 200

docs/sources/administration/provisioning/index.md

@@ -5,10 +5,6 @@ description: Describes provisioning settings for Grafana using configuration fil
 keywords:
   - grafana
   - provisioning
-labels:
-  products:
-    - enterprise
-    - oss
 title: Provision Grafana
 weight: 600
 ---
@@ -61,7 +57,7 @@ Currently we do not provide any scripts/manifests for configuring Grafana. Rathe
 | --------- | -------------------------------------------------------------------------------------------------------------- |
 | Puppet    | [https://forge.puppet.com/puppet/grafana](https://forge.puppet.com/puppet/grafana)                             |
 | Ansible   | [https://github.com/cloudalchemy/ansible-grafana](https://github.com/cloudalchemy/ansible-grafana)             |
-| Chef      | [https://github.com/JonathanTron/chef-grafana](https://github.com/JonathanTron/chef-grafana)                   |
+| Chef      | [https://github.com/sous-chefs/chef-grafana](https://github.com/sous-chefs/chef-grafana)                       |
 | Saltstack | [https://github.com/salt-formulas/salt-formula-grafana](https://github.com/salt-formulas/salt-formula-grafana) |
 | Jsonnet   | [https://github.com/grafana/grafonnet-lib/](https://github.com/grafana/grafonnet-lib/)                         |
 

docs/sources/administration/recorded-queries/index.md

@@ -7,10 +7,6 @@ keywords:
   - query
   - queries
   - recorded
-labels:
-  products:
-    - cloud
-    - enterprise
 title: Recorded queries
 weight: 300
 ---

docs/sources/administration/roles-and-permissions/access-control/_index.md

@@ -3,11 +3,6 @@ aliases:
   - ../../enterprise/access-control/
   - ../../enterprise/access-control/about-rbac/
   - ../../enterprise/access-control/roles/
-cascade:
-  labels:
-    products:
-      - cloud
-      - enterprise
 description: Role-based access control (RBAC) provides a standardized way of granting,
   changing, and revoking access so that users can view and modify Grafana resources,
   such as users and reports.

docs/sources/administration/roles-and-permissions/access-control/custom-role-actions-scopes/index.md

@@ -10,7 +10,9 @@ weight: 80
 
 # RBAC permissions, actions, and scopes
 
-> **Note:** Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Advanced](/docs/grafana-cloud).
+{{% admonition type="note" %}}
+Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Advanced](/docs/grafana-cloud).
+{{% /admonition %}}
 
 A permission is comprised of an action and a scope. When creating a custom role, consider the actions the user can perform and the resource(s) on which they can perform those actions.
 
@@ -23,128 +25,129 @@ To learn more about the Grafana resources to which you can apply RBAC, refer to
 
 The following list contains role-based access control actions.
 
-| Action                               | Applicable scope                                                                        | Description                                                                                                                                                                                      |
-| ------------------------------------ | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `alert.instances.external:read`      | `datasources:*`<br>`datasources:uid:*`                                                  | Read alerts and silences in data sources that support alerting.                                                                                                                                  |
-| `alert.instances.external:write`     | `datasources:*`<br>`datasources:uid:*`                                                  | Manage alerts and silences in data sources that support alerting.                                                                                                                                |
-| `alert.instances:create`             | n/a                                                                                     | Create silences in the current organization.                                                                                                                                                     |
-| `alert.instances:read`               | n/a                                                                                     | Read alerts and silences in the current organization.                                                                                                                                            |
-| `alert.instances:write`              | n/a                                                                                     | Update and expire silences in the current organization.                                                                                                                                          |
-| `alert.notifications.external:read`  | `datasources:*`<br>`datasources:uid:*`                                                  | Read templates, contact points, notification policies, and mute timings in data sources that support alerting.                                                                                   |
-| `alert.notifications.external:write` | `datasources:*`<br>`datasources:uid:*`                                                  | Manage templates, contact points, notification policies, and mute timings in data sources that support alerting.                                                                                 |
-| `alert.notifications:write`          | n/a                                                                                     | Manage templates, contact points, notification policies, and mute timings in the current organization.                                                                                           |
-| `alert.notifications:read`           | n/a                                                                                     | Read all templates, contact points, notification policies, and mute timings in the current organization.                                                                                         |
-| `alert.rules.external:read`          | `datasources:*`<br>`datasources:uid:*`                                                  | Read alert rules in data sources that support alerting (Prometheus, Mimir, and Loki)                                                                                                             |
-| `alert.rules.external:write`         | `datasources:*`<br>`datasources:uid:*`                                                  | Create, update, and delete alert rules in data sources that support alerting (Mimir and Loki).                                                                                                   |
-| `alert.rules:create`                 | `folders:*`<br>`folders:uid:*`                                                          | Create Grafana alert rules in a folder. Combine this permission with `folders:read` in a scope that includes the folder and `datasources:query` in the scope of data sources the user can query. |
-| `alert.rules:delete`                 | `folders:*`<br>`folders:uid:*`                                                          | Delete Grafana alert rules in a folder. Combine this permission with `folders:read` in a scope that includes the folder and `datasources:query` in the scope of data sources the user can query. |
-| `alert.rules:read`                   | `folders:*`<br>`folders:uid:*`                                                          | Read Grafana alert rules in a folder. Combine this permission with `folders:read` in a scope that includes the folder and `datasources:query` in the scope of data sources the user can query.   |
-| `alert.rules:write`                  | `folders:*`<br>`folders:uid:*`                                                          | Update Grafana alert rules in a folder. Combine this permission with `folders:read` in a scope that includes the folder and `datasources:query` in the scope of data sources the user can query. |
-| `alert.provisioning:read`            | n/a                                                                                     | Read all Grafana alert rules, notification policies, etc via provisioning API. Permissions to folders and datasource are not required.                                                           |
-| `alert.provisioning:write`           | n/a                                                                                     | Update all Grafana alert rules, notification policies, etc via provisioning API. Permissions to folders and datasource are not required.                                                         |
-| `annotations:create`                 | `annotations:*`<br>`annotations:type:*`                                                 | Create annotations.                                                                                                                                                                              |
-| `annotations:delete`                 | `annotations:*`<br>`annotations:type:*`                                                 | Delete annotations.                                                                                                                                                                              |
-| `annotations:read`                   | `annotations:*`<br>`annotations:type:*`                                                 | Read annotations and annotation tags.                                                                                                                                                            |
-| `annotations:write`                  | `annotations:*`<br>`annotations:type:*`                                                 | Update annotations.                                                                                                                                                                              |
-| `apikeys:create`                     | n/a                                                                                     | Create API keys.                                                                                                                                                                                 |
-| `apikeys:read`                       | `apikeys:*`<br>`apikeys:id:*`                                                           | Read API keys.                                                                                                                                                                                   |
-| `apikeys:delete`                     | `apikeys:*`<br>`apikeys:id:*`                                                           | Delete API keys.                                                                                                                                                                                 |
-| `dashboards:create`                  | `folders:*`<br>`folders:uid:*`                                                          | Create dashboards in one or more folders.                                                                                                                                                        |
-| `dashboards:delete`                  | `dashboards:*`<br>`dashboards:uid:*`<br>`folders:*`<br>`folders:uid:*`                  | Delete one or more dashboards.                                                                                                                                                                   |
-| `dashboards.insights:read`           | n/a                                                                                     | Read dashboard insights data and see presence indicators.                                                                                                                                        |
-| `dashboards.permissions:read`        | `dashboards:*`<br>`dashboards:uid:*`<br>`folders:*`<br>`folders:uid:*`                  | Read permissions for one or more dashboards.                                                                                                                                                     |
-| `dashboards.permissions:write`       | `dashboards:*`<br>`dashboards:uid:*`<br>`folders:*`<br>`folders:uid:*`                  | Update permissions for one or more dashboards.                                                                                                                                                   |
-| `dashboards:read`                    | `dashboards:*`<br>`dashboards:uid:*`<br>`folders:*`<br>`folders:uid:*`                  | Read one or more dashboards.                                                                                                                                                                     |
-| `dashboards:write`                   | `dashboards:*`<br>`dashboards:uid:*`<br>`folders:*`<br>`folders:uid:*`                  | Update one or more dashboards.                                                                                                                                                                   |
-| `datasources.caching:read`           | `datasources:*`<br>`datasources:uid:*`                                                  | Read data source query caching settings.                                                                                                                                                         |
-| `datasources.caching:write`          | `datasources:*`<br>`datasources:uid:*`                                                  | Update data source query caching settings.                                                                                                                                                       |
-| `datasources:create`                 | n/a                                                                                     | Create data sources.                                                                                                                                                                             |
-| `datasources:delete`                 | `datasources:*`<br>`datasources:uid:*`                                                  | Delete data sources.                                                                                                                                                                             |
-| `datasources:explore`                | n/a                                                                                     | Enable access to the **Explore** tab.                                                                                                                                                            |
-| `datasources.id:read`                | `datasources:*`<br>`datasources:uid:*`                                                  | Read data source IDs.                                                                                                                                                                            |
-| `datasources.insights:read`          | n/a                                                                                     | Read data sources insights data.                                                                                                                                                                 |
-| `datasources.permissions:read`       | `datasources:*`<br>`datasources:uid:*`                                                  | List data source permissions.                                                                                                                                                                    |
-| `datasources.permissions:write`      | `datasources:*`<br>`datasources:uid:*`                                                  | Update data source permissions.                                                                                                                                                                  |
-| `datasources:query`                  | `datasources:*`<br>`datasources:uid:*`                                                  | Query data sources.                                                                                                                                                                              |
-| `datasources:read`                   | `datasources:*`<br>`datasources:uid:*`                                                  | List data sources.                                                                                                                                                                               |
-| `datasources:write`                  | `datasources:*`<br>`datasources:uid:*`                                                  | Update data sources.                                                                                                                                                                             |
-| `folders.permissions:read`           | `folders:*`<br>`folders:uid:*`                                                          | Read permissions for one or more folders.                                                                                                                                                        |
-| `folders.permissions:write`          | `folders:*`<br>`folders:uid:*`                                                          | Update permissions for one or more folders.                                                                                                                                                      |
-| `folders:create`                     | n/a                                                                                     | Create folders.                                                                                                                                                                                  |
-| `folders:delete`                     | `folders:*`<br>`folders:uid:*`                                                          | Delete one or more folders.                                                                                                                                                                      |
-| `folders:read`                       | `folders:*`<br>`folders:uid:*`                                                          | Read one or more folders.                                                                                                                                                                        |
-| `folders:write`                      | `folders:*`<br>`folders:uid:*`                                                          | Update one or more folders.                                                                                                                                                                      |
-| `ldap.config:reload`                 | n/a                                                                                     | Reload the LDAP configuration.                                                                                                                                                                   |
-| `ldap.status:read`                   | n/a                                                                                     | Verify the availability of the LDAP server or servers.                                                                                                                                           |
-| `ldap.user:read`                     | n/a                                                                                     | Read users via LDAP.                                                                                                                                                                             |
-| `ldap.user:sync`                     | n/a                                                                                     | Sync users via LDAP.                                                                                                                                                                             |
-| `licensing.reports:read`             | n/a                                                                                     | Get custom permission reports.                                                                                                                                                                   |
-| `licensing:delete`                   | n/a                                                                                     | Delete the license token.                                                                                                                                                                        |
-| `licensing:read`                     | n/a                                                                                     | Read licensing information.                                                                                                                                                                      |
-| `licensing:write`                    | n/a                                                                                     | Update the license token.                                                                                                                                                                        |
-| `org.users:write`                    | `users:*` <br> `users:id:*`                                                             | Update the organization role (`Viewer`, `Editor`, or `Admin`) of a user.                                                                                                                         |
-| `org.users:add`                      | `users:*`                                                                               | Add a user to an organization or invite a new user to an organization.                                                                                                                           |
-| `org.users:read`                     | `users:*` <br> `users:id:*`                                                             | Get user profiles within an organization.                                                                                                                                                        |
-| `org.users:remove`                   | `users:*` <br> `users:id:*`                                                             | Remove a user from an organization.                                                                                                                                                              |
-| `org:create`                         | n/a                                                                                     | Create an organization.                                                                                                                                                                          |
-| `orgs.preferences:read`              | `orgs:*` <br> `orgs:id:*`                                                               | Read organization preferences.                                                                                                                                                                   |
-| `orgs.preferences:write`             | `orgs:*` <br> `orgs:id:*`                                                               | Update organization preferences.                                                                                                                                                                 |
-| `orgs.quotas:read`                   | `orgs:*` <br> `orgs:id:*`                                                               | Read organization quotas.                                                                                                                                                                        |
-| `orgs.quotas:write`                  | `orgs:*` <br> `orgs:id:*`                                                               | Update organization quotas.                                                                                                                                                                      |
-| `orgs:delete`                        | `orgs:*` <br> `orgs:id:*`                                                               | Delete one or more organizations.                                                                                                                                                                |
-| `orgs:read`                          | `orgs:*` <br> `orgs:id:*`                                                               | Read one or more organizations.                                                                                                                                                                  |
-| `orgs:write`                         | `orgs:*` <br> `orgs:id:*`                                                               | Update one or more organizations.                                                                                                                                                                |
-| `plugins.app:access`                 | `plugins:*` <br> `plugins:id:*`                                                         | Access one or more application plugins (still enforcing the organization role)                                                                                                                   |
-| `plugins:install`                    | n/a                                                                                     | Install and uninstall plugins.                                                                                                                                                                   |
-| `plugins:write`                      | `plugins:*` <br> `plugins:id:*`                                                         | Edit settings for one or more plugins.                                                                                                                                                           |
-| `provisioning:reload`                | `provisioners:*`                                                                        | Reload provisioning files. To find the exact scope for specific provisioner, see [Scope definitions]({{< relref "#scope-definitions" >}}).                                                       |
-| `reports:create`                     | n/a                                                                                     | Create reports.                                                                                                                                                                                  |
-| `reports:write`                      | `reports:*` <br> `reports:id:*`                                                         | Update reports.                                                                                                                                                                                  |
-| `reports.settings:read`              | n/a                                                                                     | Read report settings.                                                                                                                                                                            |
-| `reports.settings:write`             | n/a                                                                                     | Update report settings.                                                                                                                                                                          |
-| `reports:delete`                     | `reports:*` <br> `reports:id:*`                                                         | Delete reports.                                                                                                                                                                                  |
-| `reports:read`                       | `reports:*`                                                                             | List all available reports or get a specific report.                                                                                                                                             |
-| `reports:send`                       | `reports:*`                                                                             | Send a report email.                                                                                                                                                                             |
-| `roles:delete`                       | `permissions:type:delegate`                                                             | Delete a custom role.                                                                                                                                                                            |
-| `roles:read`                         | `roles:*` <br> `roles:uid:*`                                                            | List roles and read a specific with its permissions.                                                                                                                                             |
-| `roles:write`                        | `permissions:type:delegate`                                                             | Create or update a custom role.                                                                                                                                                                  |
-| `roles:write`                        | `permissions:type:escalate`                                                             | Reset basic roles to their default permissions.                                                                                                                                                  |
-| `server.stats:read`                  | n/a                                                                                     | Read Grafana instance statistics.                                                                                                                                                                |
-| `serviceaccounts:write`              | `serviceaccounts:*`                                                                     | Create Grafana service accounts.                                                                                                                                                                 |
-| `serviceaccounts:create`             | n/a                                                                                     | Update Grafana service accounts.                                                                                                                                                                 |
-| `serviceaccounts:delete`             | `serviceaccounts:*`                                                                     | Delete Grafana service accounts.                                                                                                                                                                 |
-| `serviceaccounts:read`               | `serviceaccounts:*`                                                                     | Read Grafana service accounts.                                                                                                                                                                   |
-| `serviceaccounts.permissions:write`  | `serviceaccounts:*`                                                                     | Update Grafana service account permissions to control who can do what with the service account.                                                                                                  |
-| `serviceaccounts.permissions:read`   | `serviceaccounts:*`                                                                     | Read Grafana service account permissions to see who can do what with the service account.                                                                                                        |
-| `settings:read`                      | `settings:*`<br>`settings:auth.saml:*`<br>`settings:auth.saml:enabled` (property level) | Read the [Grafana configuration settings]({{< relref "../../../../setup-grafana/configure-grafana/" >}})                                                                                         |
-| `settings:write`                     | `settings:*`<br>`settings:auth.saml:*`<br>`settings:auth.saml:enabled` (property level) | Update any Grafana configuration settings that can be [updated at runtime]({{< relref "../../../../setup-grafana/configure-grafana/settings-updates-at-runtime" >}}).                            |
-| `status:accesscontrol`               | `services:accesscontrol`                                                                | Get access-control enabled status.                                                                                                                                                               |
-| `teams.permissions:read`             | `teams:*`<br>`teams:id:*`                                                               | Read members and External Group Synchronization setup for teams.                                                                                                                                 |
-| `teams.permissions:write`            | `teams:*`<br>`teams:id:*`                                                               | Add, remove and update members and manage External Group Synchronization setup for teams.                                                                                                        |
-| `teams.roles:add`                    | `permissions:type:delegate`                                                             | Assign a role to a team.                                                                                                                                                                         |
-| `teams.roles:read`                   | `teams:*`                                                                               | List roles assigned directly to a team.                                                                                                                                                          |
-| `teams.roles:remove`                 | `permissions:type:delegate`                                                             | Unassign a role from a team.                                                                                                                                                                     |
-| `teams:create`                       | n/a                                                                                     | Create teams.                                                                                                                                                                                    |
-| `teams:delete`                       | `teams:*`<br>`teams:id:*`                                                               | Delete one or more teams.                                                                                                                                                                        |
-| `teams:read`                         | `teams:*`<br>`teams:id:*`                                                               | Read one or more teams and team preferences.                                                                                                                                                     |
-| `teams:write`                        | `teams:*`<br>`teams:id:*`                                                               | Update one or more teams and team preferences.                                                                                                                                                   |
-| `users.authtoken:read`               | `global.users:*` <br> `global.users:id:*`                                               | List authentication tokens that are assigned to a user.                                                                                                                                          |
-| `users.authtoken:write`              | `global.users:*` <br> `global.users:id:*`                                               | Update authentication tokens that are assigned to a user.                                                                                                                                        |
-| `users.password:write`               | `global.users:*` <br> `global.users:id:*`                                               | Update a user’s password.                                                                                                                                                                        |
-| `users.permissions:read`             | `users:*`                                                                               | List permissions of a user.                                                                                                                                                                      |
-| `users.permissions:write`            | `global.users:*` <br> `global.users:id:*`                                               | Update a user’s organization-level permissions.                                                                                                                                                  |
-| `users.quotas:read`                  | `global.users:*` <br> `global.users:id:*`                                               | List a user’s quotas.                                                                                                                                                                            |
-| `users.quotas:write`                 | `global.users:*` <br> `global.users:id:*`                                               | Update a user’s quotas.                                                                                                                                                                          |
-| `users.roles:add`                    | `permissions:type:delegate`                                                             | Assign a role to a user or a service account.                                                                                                                                                    |
-| `users.roles:read`                   | `users:*`                                                                               | List roles assigned directly to a user or a service account.                                                                                                                                     |
-| `users.roles:remove`                 | `permissions:type:delegate`                                                             | Unassign a role from a user or a service account.                                                                                                                                                |
-| `users:create`                       | n/a                                                                                     | Create a user.                                                                                                                                                                                   |
-| `users:delete`                       | `global.users:*` <br> `global.users:id:*`                                               | Delete a user.                                                                                                                                                                                   |
-| `users:disable`                      | `global.users:*` <br> `global.users:id:*`                                               | Disable a user.                                                                                                                                                                                  |
-| `users:enable`                       | `global.users:*` <br> `global.users:id:*`                                               | Enable a user.                                                                                                                                                                                   |
-| `users:logout`                       | `global.users:*` <br> `global.users:id:*`                                               | Sign out a user.                                                                                                                                                                                 |
-| `users:read`                         | `global.users:*`                                                                        | Read or search user profiles.                                                                                                                                                                    |
-| `users:write`                        | `global.users:*` <br> `global.users:id:*`                                               | Update a user’s profile.                                                                                                                                                                         |
+| Action                               | Applicable scope                                                                        | Description                                                                                                                                                                                                         |
+| ------------------------------------ | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `alert.instances.external:read`      | `datasources:*`<br>`datasources:uid:*`                                                  | Read alerts and silences in data sources that support alerting.                                                                                                                                                     |
+| `alert.instances.external:write`     | `datasources:*`<br>`datasources:uid:*`                                                  | Manage alerts and silences in data sources that support alerting.                                                                                                                                                   |
+| `alert.instances:create`             | n/a                                                                                     | Create silences in the current organization.                                                                                                                                                                        |
+| `alert.instances:read`               | n/a                                                                                     | Read alerts and silences in the current organization.                                                                                                                                                               |
+| `alert.instances:write`              | n/a                                                                                     | Update and expire silences in the current organization.                                                                                                                                                             |
+| `alert.notifications.external:read`  | `datasources:*`<br>`datasources:uid:*`                                                  | Read templates, contact points, notification policies, and mute timings in data sources that support alerting.                                                                                                      |
+| `alert.notifications.external:write` | `datasources:*`<br>`datasources:uid:*`                                                  | Manage templates, contact points, notification policies, and mute timings in data sources that support alerting.                                                                                                    |
+| `alert.notifications:write`          | n/a                                                                                     | Manage templates, contact points, notification policies, and mute timings in the current organization.                                                                                                              |
+| `alert.notifications:read`           | n/a                                                                                     | Read all templates, contact points, notification policies, and mute timings in the current organization.                                                                                                            |
+| `alert.rules.external:read`          | `datasources:*`<br>`datasources:uid:*`                                                  | Read alert rules in data sources that support alerting (Prometheus, Mimir, and Loki)                                                                                                                                |
+| `alert.rules.external:write`         | `datasources:*`<br>`datasources:uid:*`                                                  | Create, update, and delete alert rules in data sources that support alerting (Mimir and Loki).                                                                                                                      |
+| `alert.rules:create`                 | `folders:*`<br>`folders:uid:*`                                                          | Create Grafana alert rules in a folder and its subfolders. Combine this permission with `folders:read` in a scope that includes the folder and `datasources:query` in the scope of data sources the user can query. |
+| `alert.rules:delete`                 | `folders:*`<br>`folders:uid:*`                                                          | Delete Grafana alert rules in a folder and its subfolders. Combine this permission with `folders:read` in a scope that includes the folder and `datasources:query` in the scope of data sources the user can query. |
+| `alert.rules:read`                   | `folders:*`<br>`folders:uid:*`                                                          | Read Grafana alert rules in a folder and its subfolders. Combine this permission with `folders:read` in a scope that includes the folder and `datasources:query` in the scope of data sources the user can query.   |
+| `alert.rules:write`                  | `folders:*`<br>`folders:uid:*`                                                          | Update Grafana alert rules in a folder and its subfolders. Combine this permission with `folders:read` in a scope that includes the folder and `datasources:query` in the scope of data sources the user can query. |
+| `alert.provisioning:read`            | n/a                                                                                     | Read all Grafana alert rules, notification policies, etc via provisioning API. Permissions to folders and datasource are not required.                                                                              |
+| `alert.provisioning:write`           | n/a                                                                                     | Update all Grafana alert rules, notification policies, etc via provisioning API. Permissions to folders and datasource are not required.                                                                            |
+| `annotations:create`                 | `annotations:*`<br>`annotations:type:*`                                                 | Create annotations.                                                                                                                                                                                                 |
+| `annotations:delete`                 | `annotations:*`<br>`annotations:type:*`                                                 | Delete annotations.                                                                                                                                                                                                 |
+| `annotations:read`                   | `annotations:*`<br>`annotations:type:*`                                                 | Read annotations and annotation tags.                                                                                                                                                                               |
+| `annotations:write`                  | `annotations:*`<br>`annotations:type:*`                                                 | Update annotations.                                                                                                                                                                                                 |
+| `apikeys:create`                     | n/a                                                                                     | Create API keys.                                                                                                                                                                                                    |
+| `apikeys:read`                       | `apikeys:*`<br>`apikeys:id:*`                                                           | Read API keys.                                                                                                                                                                                                      |
+| `apikeys:delete`                     | `apikeys:*`<br>`apikeys:id:*`                                                           | Delete API keys.                                                                                                                                                                                                    |
+| `dashboards:create`                  | `folders:*`<br>`folders:uid:*`                                                          | Create dashboards in one or more folders and their subfolders.                                                                                                                                                      |
+| `dashboards:delete`                  | `dashboards:*`<br>`dashboards:uid:*`<br>`folders:*`<br>`folders:uid:*`                  | Delete one or more dashboards.                                                                                                                                                                                      |
+| `dashboards.insights:read`           | n/a                                                                                     | Read dashboard insights data and see presence indicators.                                                                                                                                                           |
+| `dashboards.permissions:read`        | `dashboards:*`<br>`dashboards:uid:*`<br>`folders:*`<br>`folders:uid:*`                  | Read permissions for one or more dashboards.                                                                                                                                                                        |
+| `dashboards.permissions:write`       | `dashboards:*`<br>`dashboards:uid:*`<br>`folders:*`<br>`folders:uid:*`                  | Update permissions for one or more dashboards.                                                                                                                                                                      |
+| `dashboards:read`                    | `dashboards:*`<br>`dashboards:uid:*`<br>`folders:*`<br>`folders:uid:*`                  | Read one or more dashboards.                                                                                                                                                                                        |
+| `dashboards:write`                   | `dashboards:*`<br>`dashboards:uid:*`<br>`folders:*`<br>`folders:uid:*`                  | Update one or more dashboards.                                                                                                                                                                                      |
+| `dashboards.public:write`            | `dashboards:*`<br>`dashboards:uid:*`                                                    | Write public dashboard configuration.                                                                                                                                                                               |
+| `datasources.caching:read`           | `datasources:*`<br>`datasources:uid:*`                                                  | Read data source query caching settings.                                                                                                                                                                            |
+| `datasources.caching:write`          | `datasources:*`<br>`datasources:uid:*`                                                  | Update data source query caching settings.                                                                                                                                                                          |
+| `datasources:create`                 | n/a                                                                                     | Create data sources.                                                                                                                                                                                                |
+| `datasources:delete`                 | `datasources:*`<br>`datasources:uid:*`                                                  | Delete data sources.                                                                                                                                                                                                |
+| `datasources:explore`                | n/a                                                                                     | Enable access to the **Explore** tab.                                                                                                                                                                               |
+| `datasources.id:read`                | `datasources:*`<br>`datasources:uid:*`                                                  | Read data source IDs.                                                                                                                                                                                               |
+| `datasources.insights:read`          | n/a                                                                                     | Read data sources insights data.                                                                                                                                                                                    |
+| `datasources.permissions:read`       | `datasources:*`<br>`datasources:uid:*`                                                  | List data source permissions.                                                                                                                                                                                       |
+| `datasources.permissions:write`      | `datasources:*`<br>`datasources:uid:*`                                                  | Update data source permissions.                                                                                                                                                                                     |
+| `datasources:query`                  | `datasources:*`<br>`datasources:uid:*`                                                  | Query data sources.                                                                                                                                                                                                 |
+| `datasources:read`                   | `datasources:*`<br>`datasources:uid:*`                                                  | List data sources.                                                                                                                                                                                                  |
+| `datasources:write`                  | `datasources:*`<br>`datasources:uid:*`                                                  | Update data sources.                                                                                                                                                                                                |
+| `folders.permissions:read`           | `folders:*`<br>`folders:uid:*`                                                          | Read permissions for one or more folders and their subfolders.                                                                                                                                                      |
+| `folders.permissions:write`          | `folders:*`<br>`folders:uid:*`                                                          | Update permissions for one or more folders and their subfolders.                                                                                                                                                    |
+| `folders:create`                     | n/a                                                                                     | Create folders in the root level. If granted together with `folders:write`, also allows creating subfolders under all folders that the user can update.                                                             |
+| `folders:delete`                     | `folders:*`<br>`folders:uid:*`                                                          | Delete one or more folders and their subfolders.                                                                                                                                                                    |
+| `folders:read`                       | `folders:*`<br>`folders:uid:*`                                                          | Read one or more folders and their subfolders.                                                                                                                                                                      |
+| `folders:write`                      | `folders:*`<br>`folders:uid:*`                                                          | Update one or more folders and their subfolders. If granted together with `folders:create` permission, also allows creating subfolders under these folders.                                                         |
+| `ldap.config:reload`                 | n/a                                                                                     | Reload the LDAP configuration.                                                                                                                                                                                      |
+| `ldap.status:read`                   | n/a                                                                                     | Verify the availability of the LDAP server or servers.                                                                                                                                                              |
+| `ldap.user:read`                     | n/a                                                                                     | Read users via LDAP.                                                                                                                                                                                                |
+| `ldap.user:sync`                     | n/a                                                                                     | Sync users via LDAP.                                                                                                                                                                                                |
+| `licensing.reports:read`             | n/a                                                                                     | Get custom permission reports.                                                                                                                                                                                      |
+| `licensing:delete`                   | n/a                                                                                     | Delete the license token.                                                                                                                                                                                           |
+| `licensing:read`                     | n/a                                                                                     | Read licensing information.                                                                                                                                                                                         |
+| `licensing:write`                    | n/a                                                                                     | Update the license token.                                                                                                                                                                                           |
+| `org.users:write`                    | `users:*` <br> `users:id:*`                                                             | Update the organization role (`Viewer`, `Editor`, or `Admin`) of a user.                                                                                                                                            |
+| `org.users:add`                      | `users:*`                                                                               | Add a user to an organization or invite a new user to an organization.                                                                                                                                              |
+| `org.users:read`                     | `users:*` <br> `users:id:*`                                                             | Get user profiles within an organization.                                                                                                                                                                           |
+| `org.users:remove`                   | `users:*` <br> `users:id:*`                                                             | Remove a user from an organization.                                                                                                                                                                                 |
+| `org:create`                         | n/a                                                                                     | Create an organization.                                                                                                                                                                                             |
+| `orgs.preferences:read`              | `orgs:*` <br> `orgs:id:*`                                                               | Read organization preferences.                                                                                                                                                                                      |
+| `orgs.preferences:write`             | `orgs:*` <br> `orgs:id:*`                                                               | Update organization preferences.                                                                                                                                                                                    |
+| `orgs.quotas:read`                   | `orgs:*` <br> `orgs:id:*`                                                               | Read organization quotas.                                                                                                                                                                                           |
+| `orgs.quotas:write`                  | `orgs:*` <br> `orgs:id:*`                                                               | Update organization quotas.                                                                                                                                                                                         |
+| `orgs:delete`                        | `orgs:*` <br> `orgs:id:*`                                                               | Delete one or more organizations.                                                                                                                                                                                   |
+| `orgs:read`                          | `orgs:*` <br> `orgs:id:*`                                                               | Read one or more organizations.                                                                                                                                                                                     |
+| `orgs:write`                         | `orgs:*` <br> `orgs:id:*`                                                               | Update one or more organizations.                                                                                                                                                                                   |
+| `plugins.app:access`                 | `plugins:*` <br> `plugins:id:*`                                                         | Access one or more application plugins (still enforcing the organization role)                                                                                                                                      |
+| `plugins:install`                    | n/a                                                                                     | Install and uninstall plugins.                                                                                                                                                                                      |
+| `plugins:write`                      | `plugins:*` <br> `plugins:id:*`                                                         | Edit settings for one or more plugins.                                                                                                                                                                              |
+| `provisioning:reload`                | `provisioners:*`                                                                        | Reload provisioning files. To find the exact scope for specific provisioner, see [Scope definitions]({{< relref "#scope-definitions" >}}).                                                                          |
+| `reports:create`                     | n/a                                                                                     | Create reports.                                                                                                                                                                                                     |
+| `reports:write`                      | `reports:*` <br> `reports:id:*`                                                         | Update reports.                                                                                                                                                                                                     |
+| `reports.settings:read`              | n/a                                                                                     | Read report settings.                                                                                                                                                                                               |
+| `reports.settings:write`             | n/a                                                                                     | Update report settings.                                                                                                                                                                                             |
+| `reports:delete`                     | `reports:*` <br> `reports:id:*`                                                         | Delete reports.                                                                                                                                                                                                     |
+| `reports:read`                       | `reports:*`                                                                             | List all available reports or get a specific report.                                                                                                                                                                |
+| `reports:send`                       | `reports:*`                                                                             | Send a report email.                                                                                                                                                                                                |
+| `roles:delete`                       | `permissions:type:delegate`                                                             | Delete a custom role.                                                                                                                                                                                               |
+| `roles:read`                         | `roles:*` <br> `roles:uid:*`                                                            | List roles and read a specific with its permissions.                                                                                                                                                                |
+| `roles:write`                        | `permissions:type:delegate`                                                             | Create or update a custom role.                                                                                                                                                                                     |
+| `roles:write`                        | `permissions:type:escalate`                                                             | Reset basic roles to their default permissions.                                                                                                                                                                     |
+| `server.stats:read`                  | n/a                                                                                     | Read Grafana instance statistics.                                                                                                                                                                                   |
+| `serviceaccounts:write`              | `serviceaccounts:*`                                                                     | Create Grafana service accounts.                                                                                                                                                                                    |
+| `serviceaccounts:create`             | n/a                                                                                     | Update Grafana service accounts.                                                                                                                                                                                    |
+| `serviceaccounts:delete`             | `serviceaccounts:*`                                                                     | Delete Grafana service accounts.                                                                                                                                                                                    |
+| `serviceaccounts:read`               | `serviceaccounts:*`                                                                     | Read Grafana service accounts.                                                                                                                                                                                      |
+| `serviceaccounts.permissions:write`  | `serviceaccounts:*`                                                                     | Update Grafana service account permissions to control who can do what with the service account.                                                                                                                     |
+| `serviceaccounts.permissions:read`   | `serviceaccounts:*`                                                                     | Read Grafana service account permissions to see who can do what with the service account.                                                                                                                           |
+| `settings:read`                      | `settings:*`<br>`settings:auth.saml:*`<br>`settings:auth.saml:enabled` (property level) | Read the [Grafana configuration settings]({{< relref "../../../../setup-grafana/configure-grafana/" >}})                                                                                                            |
+| `settings:write`                     | `settings:*`<br>`settings:auth.saml:*`<br>`settings:auth.saml:enabled` (property level) | Update any Grafana configuration settings that can be [updated at runtime]({{< relref "../../../../setup-grafana/configure-grafana/settings-updates-at-runtime" >}}).                                               |
+| `status:accesscontrol`               | `services:accesscontrol`                                                                | Get access-control enabled status.                                                                                                                                                                                  |
+| `teams.permissions:read`             | `teams:*`<br>`teams:id:*`                                                               | Read members and Team Sync setup for teams.                                                                                                                                                                         |
+| `teams.permissions:write`            | `teams:*`<br>`teams:id:*`                                                               | Add, remove and update members and manage Team Sync setup for teams.                                                                                                                                                |
+| `teams.roles:add`                    | `permissions:type:delegate`                                                             | Assign a role to a team.                                                                                                                                                                                            |
+| `teams.roles:read`                   | `teams:*`                                                                               | List roles assigned directly to a team.                                                                                                                                                                             |
+| `teams.roles:remove`                 | `permissions:type:delegate`                                                             | Unassign a role from a team.                                                                                                                                                                                        |
+| `teams:create`                       | n/a                                                                                     | Create teams.                                                                                                                                                                                                       |
+| `teams:delete`                       | `teams:*`<br>`teams:id:*`                                                               | Delete one or more teams.                                                                                                                                                                                           |
+| `teams:read`                         | `teams:*`<br>`teams:id:*`                                                               | Read one or more teams and team preferences.                                                                                                                                                                        |
+| `teams:write`                        | `teams:*`<br>`teams:id:*`                                                               | Update one or more teams and team preferences.                                                                                                                                                                      |
+| `users.authtoken:read`               | `global.users:*` <br> `global.users:id:*`                                               | List authentication tokens that are assigned to a user.                                                                                                                                                             |
+| `users.authtoken:write`              | `global.users:*` <br> `global.users:id:*`                                               | Update authentication tokens that are assigned to a user.                                                                                                                                                           |
+| `users.password:write`               | `global.users:*` <br> `global.users:id:*`                                               | Update a user’s password.                                                                                                                                                                                           |
+| `users.permissions:read`             | `users:*`                                                                               | List permissions of a user.                                                                                                                                                                                         |
+| `users.permissions:write`            | `global.users:*` <br> `global.users:id:*`                                               | Update a user’s organization-level permissions.                                                                                                                                                                     |
+| `users.quotas:read`                  | `global.users:*` <br> `global.users:id:*`                                               | List a user’s quotas.                                                                                                                                                                                               |
+| `users.quotas:write`                 | `global.users:*` <br> `global.users:id:*`                                               | Update a user’s quotas.                                                                                                                                                                                             |
+| `users.roles:add`                    | `permissions:type:delegate`                                                             | Assign a role to a user or a service account.                                                                                                                                                                       |
+| `users.roles:read`                   | `users:*`                                                                               | List roles assigned directly to a user or a service account.                                                                                                                                                        |
+| `users.roles:remove`                 | `permissions:type:delegate`                                                             | Unassign a role from a user or a service account.                                                                                                                                                                   |
+| `users:create`                       | n/a                                                                                     | Create a user.                                                                                                                                                                                                      |
+| `users:delete`                       | `global.users:*` <br> `global.users:id:*`                                               | Delete a user.                                                                                                                                                                                                      |
+| `users:disable`                      | `global.users:*` <br> `global.users:id:*`                                               | Disable a user.                                                                                                                                                                                                     |
+| `users:enable`                       | `global.users:*` <br> `global.users:id:*`                                               | Enable a user.                                                                                                                                                                                                      |
+| `users:logout`                       | `global.users:*` <br> `global.users:id:*`                                               | Sign out a user.                                                                                                                                                                                                    |
+| `users:read`                         | `global.users:*`                                                                        | Read or search user profiles.                                                                                                                                                                                       |
+| `users:write`                        | `global.users:*` <br> `global.users:id:*`                                               | Update a user’s profile.                                                                                                                                                                                            |
 
 ### Grafana OnCall action definitions (beta)
 
@@ -193,7 +196,7 @@ The following list contains role-based access control scopes.
 | `apikeys:*`<br>`apikeys:id:*`                   | Restrict an action to a set of API keys. For example, `apikeys:*` matches any API key, `apikey:id:1` matches the API key whose id is `1`.                                                                                                          |
 | `dashboards:*`<br>`dashboards:uid:*`            | Restrict an action to a set of dashboards. For example, `dashboards:*` matches any dashboard, and `dashboards:uid:1` matches the dashboard whose UID is `1`.                                                                                       |
 | `datasources:*`<br>`datasources:uid:*`          | Restrict an action to a set of data sources. For example, `datasources:*` matches any data source, and `datasources:uid:1` matches the data source whose UID is `1`.                                                                               |
-| `folders:*`<br>`folders:uid:*`                  | Restrict an action to a set of folders. For example, `folders:*` matches any folder, and `folders:uid:1` matches the folder whose UID is `1`.                                                                                                      |
+| `folders:*`<br>`folders:uid:*`                  | Restrict an action to a set of folders. For example, `folders:*` matches any folder, and `folders:uid:1` matches the folder whose UID is `1`. Note that permissions granted to a folder cascade down to subfolders located under it                |
 | `global.users:*` <br> `global.users:id:*`       | Restrict an action to a set of global users. For example, `global.users:*` matches any user and `global.users:id:1` matches the user whose ID is `1`.                                                                                              |
 | `orgs:*` <br> `orgs:id:*`                       | Restrict an action to a set of organizations. For example, `orgs:*` matches any organization and `orgs:id:1` matches the organization whose ID is `1`.                                                                                             |
 | `permissions:type:delegate`                     | The scope is only applicable for roles associated with the Access Control itself and indicates that you can delegate your permissions only, or a subset of it, by creating a new role or making an assignment.                                     |
@@ -207,3 +210,4 @@ The following list contains role-based access control scopes.
 | `settings:*`                                    | Restrict an action to a subset of settings. For example, `settings:*` matches all settings, `settings:auth.saml:*` matches all SAML settings, and `settings:auth.saml:enabled` matches the enable property on the SAML settings.                   |
 | `teams:*` <br> `teams:id:*`                     | Restrict an action to a set of teams from an organization. For example, `teams:*` matches any team and `teams:id:1` matches the team whose ID is `1`.                                                                                              |
 | `users:*` <br> `users:id:*`                     | Restrict an action to a set of users from an organization. For example, `users:*` matches any user and `users:id:1` matches the user whose ID is `1`.                                                                                              |
+| `n/a`                                           | `n/a` means not applicable. If an action has `n/a` specified for the scope, then the action does not require a scope. For example, the `teams:create` action does not require a scope and allows users to create teams.                            |

docs/sources/administration/stats-and-license/index.md

@@ -11,11 +11,7 @@ keywords:
   - configuration
   - server
   - settings
-labels:
-  products:
-    - enterprise
-    - oss
-title: Stats and license
+title: View server statistics and license
 weight: 400
 ---
 
@@ -25,11 +21,11 @@ This setting contains information about tools that Grafana Server Admins can use
 
 ## View Grafana server settings
 
-> Refer to [Role-based access control]({{< relref "../roles-and-permissions/access-control/" >}}) in Grafana Enterprise to understand how you can control access with RBAC permissions.
+> Refer to [Role-based access control]({{< relref "../roles-and-permissions/access-control" >}}) in Grafana Enterprise to understand how you can control access with RBAC permissions.
 
-If you are a Grafana server administrator, use the Settings tab to view the settings that are applied to your Grafana server via the [Configuration]({{< relref "../../setup-grafana/configure-grafana/#config-file-locations" >}}) file and any environmental variables.
+If you are a Grafana server administrator, use the Settings tab to view the settings that are applied to your Grafana server via the [Configuration]({{< relref "../../setup-grafana/configure-grafana#configuration-file-location" >}}) file and any environmental variables.
 
-> **Note:** Only Grafana server administrators can access the **Server Admin** menu. For more information about about administrative permissions, refer to [Roles and permissions]({{< relref "../roles-and-permissions/#grafana-server-administrators" >}}).
+> **Note:** Only Grafana server administrators can access the **Server Admin** menu. For more information about about administrative permissions, refer to [Roles and permissions]({{< relref "../roles-and-permissions#grafana-server-administrators" >}}).
 
 ### View server settings
 
@@ -38,15 +34,15 @@ If you are a Grafana server administrator, use the Settings tab to view the sett
 
 ### Available settings
 
-For a full list of server settings, refer to [Configuration]({{< relref "../../setup-grafana/configure-grafana/" >}}).
+For a full list of server settings, refer to [Configuration]({{< relref "../../setup-grafana/configure-grafana#server" >}}).
 
 ## View Grafana server stats
 
-> Refer to [Role-based access control]({{< relref "../roles-and-permissions/access-control/" >}}) in Grafana Enterprise to understand how you can control access with RBAC permissions.
+> Refer to [Role-based access control]({{< relref "../roles-and-permissions/access-control" >}}) in Grafana Enterprise to understand how you can control access with RBAC permissions.
 
 If you are a Grafana server admin, then you can view useful statistics about your Grafana server in the Stats & Licensing tab.
 
-> **Note:** Only Grafana server administrators can access the **Server Admin** menu. For more information about about administrative permissions, refer to [Roles and permissions]({{< relref "../roles-and-permissions/#grafana-server-administrators" >}}).
+> **Note:** Only Grafana server administrators can access the **Server Admin** menu. For more information about about administrative permissions, refer to [Roles and permissions]({{< relref "../roles-and-permissions#grafana-server-administrators" >}}).
 
 ### View server stats
 

docs/sources/administration/user-management/manage-org-users/index.md

@@ -81,6 +81,7 @@ When you invite users to join an organization, you assign the **Admin**, **Edito
    > **Note**: It might be that you are currently in the proper organization and don't need to switch organizations.
 
 1. Navigate to **Administration > Users**.
+1. Click **Organization users**.
 1. Click **Invite**.
 1. Enter the following information:
 

docs/sources/alerting/_index.md

@@ -2,11 +2,6 @@
 aliases:
   - about-alerting/
   - unified-alerting/alerting/
-cascade:
-  labels:
-    products:
-      - cloud
-      - oss
 title: Alerting
 weight: 114
 ---

docs/sources/alerting/legacy-alerting-deprecation.md

@@ -0,0 +1,46 @@
+---
+title: Legacy alerting deprecation
+description: Legacy alerting deprecation notice
+weight: 999
+keywords:
+  - grafana
+  - alerting
+---
+
+# Legacy alerting deprecation
+
+Starting with Grafana v9.0.0, legacy alerting is deprecated, meaning that it is no longer actively maintained or supported by Grafana. As of Grafana v10.0.0, we do not contribute or accept external contributions to the codebase apart from CVE fixes.
+
+Legacy alerting refers to the old alerting system that was used prior to the introduction of Grafana Alerting; the new alerting system in Grafana.
+
+The decision to deprecate legacy alerting was made to encourage users to migrate to the new alerting system, which offers a more powerful and flexible alerting experience based on Prometheus Alertmanager.
+
+Users who are still using legacy alerting are encouraged to migrate their alerts to the new system as soon as possible to ensure that they continue to receive new features, bug fixes, and support.
+
+However, we will still patch CVEs until legacy alerting is completely removed in Grafana 11; honoring our commitment to building and distributing secure software.
+
+We have provided [instructions](https://grafana.com/docs/grafana/latest/alerting/migrating-alerts/) on how to migrate to the new alerting system, making the process as easy as possible for users.
+
+## Why are we deprecating legacy alerting?
+
+The new Grafana alerting system is more powerful and flexible than the legacy alerting feature.
+
+The new system is based on Prometheus Alertmanager, which offers a more comprehensive set of features for defining and managing alerts. With the new alerting system, users can create alerts based on complex queries, configure alert notifications via various integrations, and set up sophisticated alerting rules with support for conditional expressions, aggregation, and grouping.
+
+Overall, the new alerting system in Grafana is a major improvement over the legacy alerting feature, providing users with a more powerful and flexible alerting experience.
+
+Additionally, legacy alerting still requires Angular to function and we are [planning to remove support for it](https://grafana.com/docs/grafana/latest/developers/angular_deprecation/) in Grafana 11.
+
+## When will we remove legacy alerting completely?
+
+Legacy alerting will be removed from the code-base in Grafana 11, following the same timeline as the [Angular deprecation](https://grafana.com/docs/grafana/latest/developers/angular_deprecation/).
+
+## How do I migrate to the new Grafana alerting?
+
+Refer to our [migration instructions](https://grafana.com/docs/grafana/latest/alerting/migrating-alerts/opt-in/).
+
+### Links
+
+- [Upgrade Alerting](https://grafana.com/docs/grafana/latest/alerting/migrating-alerts/)
+- [Legacy alerting differences and limitations](https://grafana.com/docs/grafana/latest/alerting/migrating-alerts/migrating-legacy-alerts/)
+- [Angular support deprecation](https://grafana.com/docs/grafana/latest/developers/angular_deprecation/)

docs/sources/alerting/migrating-alerts/legacy-alerting/_index.md

@@ -0,0 +1,95 @@
+---
+aliases:
+  - /docs/grafana-cloud/alerts/
+  - /docs/grafana-cloud/how-do-i/alerts/
+  - /docs/grafana-cloud/legacy-alerting/
+description: Legacy alerting
+title: Legacy alerting
+weight: 110
+---
+
+# Legacy alerting
+
+**Note:**
+
+Starting with Grafana v9.0.0, legacy alerting is deprecated. It is no longer actively maintained or supported by Grafana and will be removed in Grafana v11.0.0.
+
+You have two options to configure alerts within the Grafana Cloud GUI and a third option that enables you to set Grafana Cloud Alerts using the command line.
+
+- **Grafana alerts** are the same as in an on-prem instance of Grafana.
+  These alerts are created from a graph panel within a Grafana dashboard.
+  This is useful when you want to create a simple alert based on one metric from within a panel.
+  It also has a much simpler learning curve when you are getting started.
+- **Grafana Cloud alerts - GUI** are an implementation of Prometheus-style rules that enable you to query your Grafana Cloud Metrics and then set up Prometheus Alertmanager-style alerts based on those rules.
+  This is useful when you want to create precise, PromQL-based rules or create alerts from across many metrics and logs being collected into your Grafana Cloud Metrics.
+  This form of alerting is much more powerful and configurable, but that comes with some complexity.
+- **Grafana Cloud alerts - CLI** use mimirtool to create and upload the same types of Prometheus-style recording and alerting rules definitions to your Grafana Cloud Metrics instance.
+  Once created, you will also be able to view these rules from within the Grafana Cloud Alerting page in the GUI.
+- **Synthetic Monitoring alerts** are built on Prometheus alerts, just like in Grafana Cloud alerting.
+  You can configure synthetic monitoring alerts separately using the UI in synthetic monitoring.
+  Another option to create alerts for synthetic monitoring checks is to simply use Grafana Cloud alerting.
+
+## Using Grafana alerts in Grafana Cloud
+
+Grafana alerts are dashboard panel-driven and can only be created using the Graph panel.
+This style of alerting builds on top of the query defined for the graph visualization, so alerts and notifications are sent based on breaking some threshold in the associated panel.
+
+This also means that there is a one-to-one relationship between a Grafana alert and a graph panel.
+So although Grafana alerts can be viewed centrally, they can only be managed directly from the panel that they’re tied to.
+As a result, Grafana alerting is best suited for smaller setups, where there are only a few individuals or teams responsible for a small set of dashboards and where there are few dependencies between the dashboards.
+
+{{% admonition type="note" %}}
+Most curated dashboards, such as those provided with an integration or with Synthetic Monitoring do not allow you to alert from panels.
+This is to preserve the ability to upgrade these dashboards automatically when the integration or Synthetic Monitoring abilities are updated.
+To create an editable copy that you can edit and alert from, click settings (the gear logo) within any dashboard and then click **Make Editable**.
+The copy will not be upgraded when/if the curated dashboard receives an update.
+This is one reason why Grafana Cloud Alerts may be considered a better option.
+{{% /admonition %}}
+
+### What makes Grafana alerts unique?
+
+With Grafana alerts, alerts are limited to only graph panels within dashboards.
+In addition:
+
+- Alerts can be edited by both Editor and Admin roles
+- Alerts are visual, with an associated alerting threshold line
+- Alerts work with many non-Prometheus data sources, including Graphite
+- Alert notifications can be routed to many external notifier systems, directly from Grafana
+- Alerts are directly associated with a dashboard
+- Alerts can be tested
+
+## Using Grafana Cloud Alerts
+
+Because the metrics you collect and send to Grafana Cloud are centrally stored in one large time-series database, Grafana Cloud Metrics, you can query across these metrics using [PromQL](https://prometheus.io/docs/prometheus/latest/querying/basics/) and build alerts directly around those metrics rather than around a panel.
+You can also query across any logs you have sent using Loki.
+
+Grafana Cloud Alerts are directly tied to metrics and log data.
+They can be configured either through the UI or by uploading files containing Prometheus and Loki alert rules with mimirtool.
+
+Grafana Cloud Alerting's Prometheus-style alerts are built by querying directly from the data source itself.
+Because these alerts are based on the data, they are not tied to a single panel.
+This makes it possible to evaluate and centrally manage alerts across several different Prometheus and Loki data source instances.
+
+### What makes Grafana Cloud Alerts unique?
+
+With Grafana Cloud Alerts, alerts are not limited to coming from a graph panel.
+In addition, you can:
+
+- Prevent alerts from being edited, except by users with accounts that are assigned Admin roles.
+- Centrally manage and create alerts across many systems, teams, and dashboards.
+  Alerts are not bound to just one system, team, or dashboard.
+- Create alerts for both metric _and_ log data, based on Prometheus and Loki, respectively.
+- Silence and mute alerts in bulk, even using a schedule, using the Alertmanager.
+- Route alert notifications to [many external notifier systems](https://prometheus.io/docs/operating/integrations/#alertmanager-webhook-receiver) using Alertmanager configurations
+- Dedupe alert notifications automatically.
+
+### Grafana Cloud Alert configuration methods
+
+In a traditional on-prem environment, Prometheus-style alert configuration is done through the combination of defining a [Prometheus configuration file](https://prometheus.io/docs/prometheus/latest/configuration/configuration/) and an [Alertmanager configuration file](https://prometheus.io/docs/alerting/latest/configuration/), which live close to the Prometheus server.
+With Grafana Cloud, you can still use this setup as well as more flexible architectures.
+
+- You can use `mimirtool` to upload your configuration files to be hosted and evaluated entirely in Grafana Cloud.
+- You can manage both alerting rules and Alertmanager configurations directly through the UI.
+  Configuration files are unnecessary with this setup.
+- You can use both methods concurrently to manage the alerts.
+  For example, updates made using the `mimirtool` are automatically updated and visible within the Grafana Cloud Alerting interface in minutes.

docs/sources/alerting/migrating-alerts/legacy-alerting/alerts-rules.md

@@ -0,0 +1,200 @@
+---
+aliases:
+  - /docs/grafana-cloud/alerts/alerts-rules/
+  - /docs/grafana-cloud/how-do-i/alerts/alerts-rules/
+  - /docs/grafana-cloud/legacy-alerting/alerts-rules/
+  - /docs/grafana-cloud/metrics/prometheus/alerts_rules/
+  - /docs/hosted-metrics/prometheus/alerts_rules/
+description: Prometheus rules with mimirtool
+title: Prometheus rules with mimirtool
+weight: 100
+---
+
+# Prometheus rules with mimirtool
+
+This page outlines the steps to use mimirtool and Prometheus-style rules with Grafana Cloud Alerting. You can load Prometheus alerting and recording rules that are evaluated entirely in Grafana Cloud. This allows for global rule evaluation over all of the metrics and logs stored in your Grafana Cloud stack.
+
+{{% admonition type="note" %}}
+`mimirtool` does _not_ support Loki.
+{{% /admonition %}}
+
+Prometheus-style alerting is driven by your Grafana Cloud Metrics, Grafana Cloud Logs, and Grafana Cloud Alerts instances. The Metrics and Logs instance holds the rules definition, while the Alerts instance is in charge of routing and managing the alerts that fire from the Metrics and Logs instance. These are separate systems that must be individually configured in order for alerting to work correctly.
+
+The following sections cover all of these concepts:
+
+- How to upload alerting and recording rules definition to your Grafana Cloud Metrics instance
+- How to upload alerting rules definition to your Grafana Cloud Logs instance
+- How to configure an Alertmanager for your Grafana Cloud Alerts instance, giving you access to the Alertmanager UI.
+
+**Note:** You need an API key with proper permissions. You can use the same API key for your Metric, Log, and Alerting instances.
+
+## Download and install mimirtool
+
+mimirtool is a powerful command-line tool for interacting with Mimir, which powers Grafana Cloud Metrics and Alerts. You'll use mimirtool to upload your metric and log rules definition and the Alertmanager configuration using YAML files.
+
+For more information, including installation instructions, see [Grafana Mimirtool](/docs/mimir/latest/operators-guide/tools/mimirtool).
+
+{{% admonition type="note" %}}
+For mimirtool to interact with Grafana Cloud, you must set the correct configuration variables. Set them using either environment variables or a command line flags.
+{{% /admonition %}}
+
+## Upload rules definition to your Grafana Cloud Metrics and Logs instance
+
+First, you'll need to upload your alerting and recording rules to your Metrics and Logs instance. You'll need the instance ID and the URL. These should be part of /orgs/`<yourOrgName>`/.
+
+### Metrics instance
+
+Your Metrics instance is likely to be in the `us-central1` region. Its address would be in the form of [https://prometheus-us-central1.grafana.net](https://prometheus-us-central1.grafana.net).
+
+### Logs instance
+
+Your Logs instance is likely to be in the `us-central1` region. Its address would be in the form of [https://logs-prod-us-central1.grafana.net](https://logs-prod-us-central1.grafana.net).
+
+### Using mimirtool
+
+With your instance ID, URL, and API key you're now ready to upload your rules to your metrics instance. 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
+# first_rules.yml
+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 and 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
+$ 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
+$ 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
+Namespace   | Rule Group
+first_rules | shopping_service_rules_and_alerts
+```
+
+You can also print the rules:
+
+```bash
+$ mimirtool rules print \
+--address=https://prometheus-us-central1.grafana.net \
+--id=<yourID> \
+--key=<yourKey>
+```
+
+Output from the print command should look like this:
+
+```yaml
+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)
+```
+
+## Upload Alertmanager configuration to your Grafana Cloud Alerts instance
+
+To receive alerts you'll need to upload your Alertmanager configuration to your Grafana Cloud Alerts instance. Similar to the previous step, you'll need the corresponding instance ID, URL and API key. These should be part of /orgs/​`<yourOrgName>`/.
+
+Your Alerts instance is likely to be in the `us-central1` region. Its address would be in the form of [https://alertmanager-us-central1.grafana.net](https://alertmanager-us-central1.grafana.net).
+
+### Using mimirtool
+
+With your instance ID, URL, and API key you're now ready to upload your Alertmanager configuration to your Alerts instance. Use the following commands and files as a reference.
+
+Ultimately, you'll need to [write your own](https://prometheus.io/docs/alerting/latest/configuration/) or adapt an [example config file](https://github.com/prometheus/alertmanager/blob/master/doc/examples/simple.yml) for alerts to be delivered.
+
+Below is an example Alertmanager configuration. Please take that this not a working configuration, your alerts won't be delivered with the following configuration but your Alertmanager UI will be accessible.
+
+```yaml
+# alertmanager.yml
+global:
+  smtp_smarthost: 'localhost:25'
+  smtp_from: 'youraddress@example.org'
+route:
+  receiver: example-email
+receivers:
+  - name: example-email
+    email_configs:
+      - to: 'youraddress@example.org'
+```
+
+With this file, you can run the following commands to upload your Alertmanager configuration in your Alerts instance.
+
+```bash
+$ mimirtool alertmanager load alertmanager.yml \
+--address=https://alertmanager-us-central1.grafana.net \
+--id=<yourID> \
+--key=<yourKey>
+```
+
+Then, confirm that the rules were uploaded correctly by running:
+
+```bash
+$ mimirtool alertmanager get \
+--address=https://alertmanager-us-central1.grafana.net \
+--id=<yourID> \
+--key=<yourKey>
+```
+
+You should see output similar to the following:
+
+```bash
+global:
+  smtp_smarthost: 'localhost:25'
+  smtp_from: 'youraddress@example.org'
+route:
+  receiver: example-email
+receivers:
+ - name: example-email
+   email_configs:
+    - to: 'youraddress@example.org'
+```
+
+Finally, you can delete the configuration with:
+
+```bash
+$ mimirtool alertmanager delete \
+--address=https://alertmanager-us-central1.grafana.net \
+--id=<yourID> \
+--key=<yourKey>
+```
+
+### UI access
+
+After you upload a working Alertmanager configuration file, you can access the Alertmanager UI at: https://alertmanager-us-central1.grafana.net/alertmanager.

docs/sources/alerting/migrating-alerts/legacy-alerting/grafana-cloud-alerting/_index.md

@@ -0,0 +1,76 @@
+---
+aliases:
+  - /docs/grafana-cloud/alerts/grafana-cloud-alerting/
+  - /docs/grafana-cloud/how-do-i/grafana-cloud-alerting/
+  - /docs/grafana-cloud/legacy-alerting/grafana-cloud-alerting/
+description: Grafana Cloud Alerting
+title: Grafana Cloud Alerting
+weight: 100
+---
+
+# Grafana Cloud Alerting
+
+Grafana Cloud Alerting allows you to create and manage all of your Prometheus-style alerting rules, for both Prometheus metrics and Loki log data. With this feature, you don't need to leave Grafana, upload or edit configuration files, or install additional tools.
+
+![Grafana Cloud Alerting](/static/img/docs/grafana-cloud/grafana-cloud-alerting.png)
+
+## Permissions
+
+All members of an organization that have alerts set up can view alerts in Grafana Cloud Alerting. This includes everyone with a Viewer, Editor, or Admin role.
+
+Users with the organization Admin role can also create, edit, or delete alerts.
+
+## Data sources
+
+Grafana Cloud Alerting supports rule management across multiple data sources, for both metrics and logs, across all of the stacks in your org. If you have more than one Prometheus or Loki data source, there will be a dropdown at the top for you to select the data source to configure rules.
+
+{{% admonition type="note" %}}
+Pay attention to which data source you select. Cloud alerts are tied to a specific data source. For example, if you have a Loki data source selected you will not be able to create an alert based on a Prometheus data source.
+![Cloud Alerting Data Source](/static/img/docs/grafana-cloud/grafana-cloud-alerting-data-source.png)
+{{% /admonition %}}
+
+## Alerts and recording rules
+
+Prometheus supports two types of rules:
+
+- [Recording rules](https://prometheus.io/docs/prometheus/latest/configuration/recording_rules/) - Recording rules allow you to execute expressions or queries, by saving them off as a stored rule instead.
+- [Alerting rules](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/) - Alerting rules allow you to define alert conditions and to route those notifications to an external service. An alert fires if metrics meet criteria defined in the alerting rule.
+
+Both of these rules are configurable from the Grafana Cloud Alerting interface and configured in the same way.
+
+## Alert states
+
+Alert states are identical to the standard format found in Prometheus rule configurations. In Grafana Cloud Alerting, each individual alert is highlighted by its state to more clearly distinguish between alerts.
+
+- **Firing -** Alerts that have been active for longer than the configured threshold. Alerts are highlighted in red and tagged with a red `firing` label.
+- **Pending -** Alerts that have been active for less than the configured threshold. Alerts are highlighted in orange.
+- **Inactive -** Alerts that are neither firing nor pending. Alerts are highlighted in green.
+
+## Notifications
+
+The **Notifications** tab is where you can view all current notifications and sort them by various states, receivers, and labels.
+
+![Grafana Cloud Alerting Notifications](/static/img/docs/grafana-cloud/grafana-cloud-alerting-notifications.png)
+
+## Limits
+
+There is a limit on how many rules can be created in a rule group. There is also a limit on how many rule groups can be created.
+
+You can create:
+
+- 20 rules per rule group
+- 35 rule groups
+
+> It is possible to increase these limits. Please contact customer support for further information.
+
+If you exceed the limits, you will encounter an error similar to this:
+
+```bash
+ERROR[0000] requests failed fields.msg="request failed with response body
+per-user rules per rule group limit (limit: 20 actual: 22) exceeded\n"
+status="400 Bad Request"
+ERROR[0000] unable to load rule group  error="failed request to the cortex api"
+group=limit_rules_per_group namespace=test
+```
+
+To increase the number of rules or rule groups you can configure, contact support to upgrade your account.

docs/sources/alerting/migrating-alerts/legacy-alerting/grafana-cloud-alerting/alertmanager.md

@@ -0,0 +1,55 @@
+---
+aliases:
+  - /docs/grafana-cloud/alerts/grafana-cloud-alerting/alertmanager/
+  - /docs/grafana-cloud/how-do-i/grafana-cloud-alerting/alertmanager/
+  - /docs/grafana-cloud/legacy-alerting/grafana-cloud-alerting/alertmanager/
+description: Alertmanager
+title: Alertmanager
+weight: 500
+---
+
+# Alertmanager
+
+Grafana Cloud Alerting allows you to edit and view configuration for your Alertmanager directly inside of Grafana. See the official [Alertmanager documentation](https://prometheus.io/docs/alerting/latest/configuration/) to learn how to configure.
+
+{{% admonition type="note" %}}
+Only organization Admins can view or update Alertmanger configurations.
+{{% /admonition %}}
+
+## Edit a config for Grafana Cloud Alerting
+
+1. In Grafana, hover your cursor over the **Grafana Cloud Alerting** icon and then click **Alertmanager**.
+1. If you have more than one Alertmanager source, there will be a dropdown at the top for you to select the data source to edit configurations.
+1. Currently active configuration for the Alertmanager will be displayed. Click the **Edit** button to enter edit mode and start making changes. Click "Save and finish editing" once done to persist your changes.
+1. Alternatively, updates to the Alertmanager configurations made using the mimirtool will also sync and appear here.
+
+## Use the Grafana Labs-supplied SMTP option to configure email notifications
+
+Grafana Cloud users who do not have an SMTP server available for sending alert emails may use Grafana-Labs supplied SMTP relay (available at `smtprelay:2525`).
+
+1. In Grafana, hover your cursor over the **Grafana Cloud Alerting** icon and then click **Alertmanager**.
+1. If you have more than one Alertmanager source, there will be a dropdown at the top for you to select the data source to edit configurations.
+1. Find info box with heading **Send alert email notifications from Grafana Cloud** at the top
+1. Enter desired email address into the **email address** field
+1. Click **Update configuration** button. Alertmanager config will be updated with grafana SMTP relay settings and an "email" receiver that will send to the specified email address.
+
+{{% admonition type="note" %}}
+Following these steps will overwrite any custom global SMTP settings that you might have. Default route configuration will send all notifications to the "email" receiver. If you have already customized routes, they will not be updated and you will have to configure "email" receiver on the appropriate route.
+{{% /admonition %}}
+
+Use these settings in your Grafana Cloud Alerting YAML, if you do not find them already set. Most important is the `smtp_require_tls: false` line. If this is not set properly, alert emails will not be received. If you use mimirtool to configure alertmanager, by default this will be set to `true`, which will cause problems.
+
+```yaml
+global:
+  smtp_from: noreply@grafana.net
+  smtp_smarthost: smtprelay:2525
+  smtp_require_tls: false
+```
+
+## Troubleshooting Alertmanager failures
+
+Configuration errors can cause Alertmanager notification failures, e.g. a typo in an email address recipient or an expired token for a webhook. Grafana Cloud provisions a Loki datasource `grafanacloud-<stack_slug>-usage-insights` which can be used to display select notification errors with a query similar to the example below. The `instance_type` label of `alerts` is what selects the Grafana Cloud Alertmanager logs.
+
+```sql
+{instance_type="alerts"} | logfmt | level="warn"
+```

docs/sources/alerting/migrating-alerts/legacy-alerting/grafana-cloud-alerting/create-edit-rules.md

@@ -0,0 +1,59 @@
+---
+aliases:
+  - /docs/grafana-cloud/alerts/grafana-cloud-alerting/create-edit-rules/
+  - /docs/grafana-cloud/how-do-i/grafana-cloud-alerting/create-edit-rules/
+  - /docs/grafana-cloud/legacy-alerting/grafana-cloud-alerting/create-edit-rules/
+description: Create and edit alert rules
+title: Create and edit alert rules
+weight: 200
+---
+
+# Create and edit alert rules
+
+Creating alerts in Grafana Cloud differs from creating alerts directly with Prometheus or Loki. While the rule format is the same, everything is done in the Grafana Cloud Alerting interface, rather than with configuration files.
+
+{{% admonition type="note" %}}
+Only organization Admins can create or edit alert rules.
+{{% /admonition %}}
+
+## Create an alert rule
+
+1. In Grafana, hover your cursor over the **Grafana Cloud Alerting** icon and then click **Alerts and rules**.
+1. If you have more than one Prometheus or Loki data source, there will be a dropdown at the top for you to select the data source to create or edit rules.
+1. Click **Edit rules**.
+1. Click **Add rule**.
+
+Grafana creates a new rule with placeholders.
+
+```
+alert: ""
+expr: ""
+```
+
+Enter text according to regular Prometheus rule configuration guidelines:
+
+- [Recording rules](https://prometheus.io/docs/prometheus/latest/configuration/recording_rules/)
+- [Alerting rules](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/)
+
+{{% admonition type="note" %}}
+Grafana Cloud Alerting does not support comments.
+{{% /admonition %}}
+
+When you are finished, click **Save**. You can then repeat the process to create more rules or click **Finish editing** to return to the rules list.
+
+## Edit an alert rule
+
+1. In Grafana, hover your cursor over the **Grafana Cloud Alerting** icon and then click **Alerts and rules**.
+1. If you have more than one Prometheus or Loki data source, there will be a dropdown at the top for you to select the data source to create or edit rules.
+1. Click **Edit rules**.
+1. Scroll down to the rule that you want to edit and then click **Edit**.
+1. Make any necessary changes to the rule text and then click **Save**.
+1. Click **Finish editing** to return to the rules list.
+
+## Delete an alert rule
+
+1. In Grafana, hover your cursor over the **Grafana Cloud Alerting** icon and then click **Alerts and rules**.
+1. If you have more than one Prometheus or Loki data source, there will be a dropdown at the top for you to select the data source to create or edit rules.
+1. Click **Edit rules**.
+1. Scroll down to the rule that you want to edit and then click **Delete**.
+1. Click **Finish editing** to return to the rules list.

docs/sources/alerting/migrating-alerts/legacy-alerting/grafana-cloud-alerting/namespaces-and-groups.md

@@ -0,0 +1,50 @@
+---
+aliases:
+  - /docs/grafana-cloud/alerts/grafana-cloud-alerting/namespaces-and-groups/
+  - /docs/grafana-cloud/how-do-i/grafana-cloud-alerting/namespaces-and-groups/
+  - /docs/grafana-cloud/legacy-alerting/grafana-cloud-alerting/namespaces-and-groups/
+description: Namespaces and rule groups
+title: Namespaces and rule groups
+weight: 400
+---
+
+# Namespaces and rule groups
+
+By default, all alerting and recording rules created in Grafana Cloud Alerting will default to a single namespace and a single rule group.
+
+## Managing namespaces
+
+While Grafana Cloud Alerting does support viewing multiple namespaces that have been added through the mimirtool, it is currently not possible to add new namespaces or to rename the existing ones.
+
+## Managing rule groups
+
+Rule groups can be managed directly within the Grafana Cloud Alerting interface or through the mimirtool, similar to managing namespaces.
+
+{{% admonition type="note" %}}
+By default, Grafana Cloud limits the number of rule groups to 20, with a limit of up to 15 rules per group. If you wish to increase the default limits, please [open a support ticket](/profile/org#support) or reach out to your account manager.
+{{% /admonition %}}
+
+### Create a new rule group:
+
+1. In Grafana, hover your cursor over the **Grafana Cloud Alerting** icon and then click **Alerts and rules**.
+2. If you have more than one Prometheus or Loki data source, there will be a dropdown at the top for you to select the data source to create or edit rules.
+3. Click **Create new rule group**.
+4. Enter text to name your new rule group.
+5. Enter text for the new rule in your new rule group, according to regular Prometheus rule configuration guidelines:
+
+- [Recording rules](https://prometheus.io/docs/prometheus/latest/configuration/recording_rules/)
+- [Alerting rules](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/)
+
+6. When you are finished naming your new rule group and adding new rule details, click **Save**.
+
+{{% admonition type="note" %}}
+In order to create a new rule group, you must also create a new rule for it.
+{{% /admonition %}}
+
+### Update a rule group
+
+Existing rule groups can be renamed by selecting the **pencil** icon next to the rule group name.
+
+### Delete a rule group
+
+Rule groups will be automatically deleted once the all rules within a group are deleted.

docs/sources/alerting/migrating-alerts/legacy-alerting/grafana-cloud-alerting/silences.md

@@ -0,0 +1,31 @@
+---
+aliases:
+  - /docs/grafana-cloud/alerts/grafana-cloud-alerting/silences/
+  - /docs/grafana-cloud/how-do-i/grafana-cloud-alerting/silences/
+  - /docs/grafana-cloud/legacy-alerting/grafana-cloud-alerting/silences/
+description: Silences
+title: Silences
+weight: 600
+---
+
+# Silences
+
+Grafana Cloud Alerting allows you to manage silences for your alertmanager notifications directly inside of Grafana. This applies to alerting rules created for both Prometheus metrics and Loki logs.
+
+## Create a silence
+
+1. In Grafana, hover your cursor over the **Grafana Cloud Alerting** icon and then click **Silences**.
+2. Click **New silence**.
+3. Enter a date in **Start of silence** to indicate when the silence should go into effect.
+4. Enter a date in **End of silence** to indicate when the silence should expire.
+5. Enter one or more matchers by filling out the **Name** and **Value** fields. Matchers determine which rules the silence will apply to.
+6. Enter the name of the owner in **Creator**.
+7. Enter a **Comment**.
+8. To view which rules will be affected by your silence, click **Preview alerts**.
+9. Otherwise, when you are finished, click **Create**
+
+## Update an existing silence
+
+You can always update an existing silence by clicking the **Edit silence** button under the silence.
+
+It is also possible to expire a silence, on-demand, by clicking the **Expire silence** button under the silence. This will override the original scheduled expiration date of the silence.

docs/sources/alerting/migrating-alerts/legacy-alerting/grafana-cloud-alerting/view-filter-rules.md

@@ -0,0 +1,42 @@
+---
+aliases:
+  - /docs/grafana-cloud/alerts/grafana-cloud-alerting/view-filter-rules/
+  - /docs/grafana-cloud/how-do-i/grafana-cloud-alerting/view-filter-alerts/
+  - /docs/grafana-cloud/legacy-alerting/grafana-cloud-alerting/view-filter-rules/
+description: View and filter alert rules
+title: View and filter alert rules
+weight: 300
+---
+
+# View and filter alert rules
+
+Grafana Cloud Alerting displays a list of all recording and alerting rules assigned to a selected data source in the Alerts and rules tab.
+
+All members of an organization that have access to a particular data source can view the list of rules and filter or reorder their view.
+
+## View alert rules
+
+1. Hover your cursor over the **Grafana Cloud Alerting** icon (alarm bell with Prometheus logo) and then click **Alerts and rules**.
+1. In the list at the top of the tab, select the data source for which you want to view rules.
+
+Grafana displays rules according to rule groups. If your instance has added namespaces and alert groups, then they will be ordered alphabetically. Otherwise, you will have one namespace called `default` and an alert group called `rules`.
+
+If an alert is firing, then click the down carrot arrow to see additional information. The Label and annotations section appears.
+
+## Filter your alert rule view
+
+You can control which alerts you see and in what order they appear several ways. Combine different filters to personalize your view so that you can quickly find the information that you need.
+
+- **Filter by alert state -** Click the toggles to show or hide alerts in different states. Turn off the toggle to hide alerts matching the state.
+- **Filter by rule type -** Click the toggles to show or hide alerting rules or recording rules.
+- **View options -** Click the toggle to show or hide the Prometheus annotations shown in the Labels and annotations section.
+- **Rule sorting -** Click an option to sort alert rules within each rule group.
+  - **None -** No special sort is applied and sorts as if in a file, ordered according to the editing list order.
+  - **A-Z -** Sorts rules alphabetically according to the rule name.
+  - **Alert state -** Sorts rules according to the alert state (Firing, Pending, or Inactive).
+
+## View alert in Explore
+
+Click **View in Explore** or click the `expr` link to open the `expr` in [Explore](/docs/grafana/latest/explore/).
+
+> **Note:** Only users with Admin or Editor roles in an organization can use the Explore feature unless the viewers can edit.

docs/sources/alerting/migrating-alerts/migrating-legacy-alerts.md

@@ -20,18 +20,24 @@ longer supported. We refer to these as [Differences]({{< relref "#differences" >
 
 2. Read and write access to legacy dashboard alerts and Grafana alerts are governed by the permissions of the folders storing them. During migration, legacy dashboard alert permissions are matched to the new rules permissions as follows:
 
-- If alert's dashboard has permissions, it will create a folder named like `Migrated {"dashboardUid": "UID", "panelId": 1, "alertId": 1}` to match permissions of the dashboard (including the inherited permissions from the folder).
-- If there are no dashboard permissions and the dashboard is under a folder, then the rule is linked to this folder and inherits its permissions.
-- If there are no dashboard permissions and the dashboard is under the General folder, then the rule is linked to the `General Alerting` folder, and the rule inherits the default permissions.
+   - If there are dashboard permissions, a folder named `Migrated {"dashboardUid": "UID", "panelId": 1, "alertId": 1}` is created to match the permissions of the dashboard (including the inherited permissions from the folder).
+   - If there are no dashboard permissions and the dashboard is in a folder, then the rule is linked to this folder and inherits its permissions.
+   - If there are no dashboard permissions and the dashboard is in the General folder, then the rule is linked to the `General Alerting` folder and the rule inherits the default permissions.
 
-3. Since there is no `Keep Last State` option for [`No Data`]({{< relref "../alerting-rules/create-grafana-managed-rule/#no-data--error-handling" >}}) in Grafana Alerting, this option becomes `NoData` during the legacy rules migration. Option "Keep Last State" for [`Error handling`]({{< relref "../alerting-rules/create-grafana-managed-rule/#no-data--error-handling" >}}) is migrated to a new option `Error`. To match the behavior of the `Keep Last State`, in both cases, during the migration Grafana automatically creates a silence for each alert rule with a duration of 1 year.
+3. `NoData` and `Error` settings are migrated as is to the corresponding settings in Grafana Alerting, except in two situations:
+
+   3.1. As there is no `Keep Last State` option for `No Data` in Grafana Alerting, this option becomes `NoData`. The `Keep Last State` option for `Error` is migrated to a new option `Error`. To match the behavior of the `Keep Last State`, in both cases, during the migration Grafana automatically creates a silence for each alert rule with a duration of 1 year.
+
+   3.2. Due to lack of validation, legacy alert rules imported via JSON or provisioned along with dashboards can contain arbitrary values for `NoData` and [`Error`](/docs/sources/alerting/alerting-rules/create-grafana-managed-rule.md#configure-no-data-and-error-handling). In this situation, Grafana will use the default setting: `NoData` for No data, and `Error` for Error.
 
 4. Notification channels are migrated to an Alertmanager configuration with the appropriate routes and receivers. Default notification channels are added as contact points to the default route. Notification channels not associated with any Dashboard alert go to the `autogen-unlinked-channel-recv` route.
 
-5. Unlike legacy dashboard alerts where images in notifications are enabled per contact point, images in notifications for Grafana Alerting must be enabled in the Grafana configuration, either in the configuration file or environment variables, and are enabled for either all or no contact points. Refer to [images in notifications](https://grafana.com/docs/grafana/latest/alerting/manage-notifications/images-in-notifications/).
-6. Grafana Alerting does not support pausing the evaluation of alert rules. After migration, all paused alert rules will become active, which may cause unexpected notifications to be sent.
+5. Unlike legacy dashboard alerts where images in notifications are enabled per contact point, images in notifications for Grafana Alerting must be enabled in the Grafana configuration, either in the configuration file or environment variables, and are enabled for either all or no contact points. Refer to [images in notifications]({{< relref "../manage-notifications/images-in-notifications" >}}).
+
+6. The JSON format for webhook notifications has changed in Grafana Alerting and uses the format from [Prometheus Alertmanager](https://prometheus.io/docs/alerting/latest/configuration/#webhook_config).
+
+7. Alerting on Prometheus `Both` type queries is not supported in Grafana Alerting. Existing legacy alerts with `Both` type queries are migrated to Grafana Alerting as alerts with `Range` type queries.
 
 ## Limitations
 
 1. Since `Hipchat` and `Sensu` notification channels are no longer supported, legacy alerts associated with these channels are not automatically migrated to Grafana Alerting. Assign the legacy alerts to a supported notification channel so that you continue to receive notifications for those alerts.
-   Silences (expiring after one year) are created for all paused dashboard alerts.

docs/sources/copyright/_index.md

@@ -1,7 +0,0 @@
----
-title: Copyright notice
----
-
-# Copyright notice
-
-Copyright © 2021 Raintank, Inc. dba Grafana Labs. All Rights Reserved.

docs/sources/dashboards/_index.md

@@ -1,12 +1,6 @@
 ---
 aliases:
   - features/dashboard/dashboards/
-cascade:
-  labels:
-    products:
-      - cloud
-      - enterprise
-      - oss
 title: Dashboards
 weight: 70
 ---

docs/sources/dashboards/build-dashboards/annotate-visualizations/index.md

@@ -14,85 +14,124 @@ weight: 600
 
 # Annotate visualizations
 
-Annotations provide a way to mark points on the graph with rich events. When you hover over an annotation
-you can get event description and event tags. The text field can include links to other systems with more detail.
+Annotations provide a way to mark points on a visualization with rich events. They are visualized as vertical lines and icons on all graph panels. When you hover over an annotation, you can get event description and event tags. The text field can include links to other systems with more detail.
 
 {{< figure src="/static/img/docs/v46/annotations.png" max-width="800px" >}}
 
-## Native annotations
+You can annotate visualizations in three ways:
 
-Grafana comes with a native annotation store and the ability to add annotation events directly from the graph panel or via the [HTTP API]({{< relref "../../../developers/http_api/annotations/" >}}).
+- Directly in the panel, using the [built-in annotations query](#built-in-query)
+- Using the HTTP API
+- Configuring annotation queries in the dashboard settings
 
-### Add annotation
+In the first two cases, you're creating new annotations, while in the last you're querying existing annotations from data sources. The built-in annotation query also supports this.
 
-1. In the dashboard click on the Time series panel. A context menu will appear.
-1. In the context menu click on **Add annotation**.
+This page explains the first and third options; for information about using the HTTP API, refer to [Annotations API]({{< relref "../../../developers/http_api/annotations/" >}}).
+
+Annotations are supported for the following visualization types:
+
+- Time series
+- State timeline
+- Candlestick
+
+## Create annotations in panels
+
+Grafana comes with the ability to add annotation events directly from a panel using the [built-in annotation query](#built-in-query) that exists on all dashboards. Annotations that you create this way are stored in Grafana.
+
+To add annotations directly in the panel, the built-in query must be enabled. Learn more in [Built-in query](#built-in-query)
+
+### Add an annotation
+
+To add an annotation, complete the following steps:
+
+1. In the dashboard click the panel to which you're adding the annotation. A context menu will appear.
+1. In the context menu, click **Add annotation**.
    ![Add annotation context menu](/static/img/docs/time-series-panel/time-series-annotations-context-menu.png)
-1. Add an annotation description and tags(optional).
-   ![Add annotation popover](/static/img/docs/time-series-panel/time-series-annotations-add-annotation.png)
-1. Click save.
+1. Add an annotation description and tags (optional).
+1. Click **Save**.
 
-Alternatively, to add an annotation, Ctrl/Cmd+Click on the Time series panel and the Add annotation popover will appear
+Alternatively, to add an annotation, press Ctrl/Cmd and click the panel, and the **Add annotation** popover will appear.
 
-### Add region annotation
+### Add a region annotation
 
-1. In the dashboard Ctrl/Cmd+click and drag on the Time series panel.
+1. In the dashboard press Ctrl/Cmd and click and drag on the panel.
    ![Add annotation popover](/static/img/docs/time-series-panel/time-series-annotations-add-region-annotation.gif)
-1. Add an annotation description and tags(optional).
-1. Click save.
+1. Add an annotation description and tags (optional).
+1. Click **Save**.
 
-### Edit annotation
+### Edit an annotation
 
-1. In the dashboard hover over an annotation indicator on the Time series panel.
+1. In the dashboard, hover over an annotation indicator on the Time series panel.
    <!--![Add annotation popover](/static/img/docs/time-series-panel/time-series-annotations-edit-annotation.gif)-->
 1. Click on the pencil icon in the annotation tooltip.
 1. Modify the description and/or tags.
 1. Click save.
 
-### Delete annotation
+### Delete an annotation
 
-1. In the dashboard hover over an annotation indicator on the Time series panel.
+1. In the dashboard hover over an annotation indicator on a panel.
    <!--![Add annotation popover](/static/img/docs/time-series-panel/time-series-annotations-edit-annotation.gif)-->
 1. Click on the trash icon in the annotation tooltip.
 
-### Built-in query
+## Fetch annotations through dashboard settings
 
-After you added an annotation they will still be visible. This is due to the built in annotation query that exists on all dashboards. This annotation query will
-fetch all annotation events that originate from the current dashboard and show them on the panel where they were created. This includes alert state history annotations. You can
-stop annotations from being fetched and drawn by opening the **Annotations** settings (via Dashboard cogs menu) and modifying the query named `Annotations & Alerts (Built-in)`.
+In the dashboard settings, under **Annotations**, you can add new queries to fetch annotations using any data source, including the built-in data annotation data source. Annotation queries return events that can be visualized as event markers in graphs across the dashboard.
 
-When you copy a dashboard using the **Save As** feature it will get a new dashboard id so annotations created on source dashboard will no longer be visible on the copy. You
-can still show them if you add a new **Annotation Query** and filter by tags. But this only works if the annotations on the source dashboard had tags to filter by.
+### Add new annotation queries
 
-### Query by tag
+To add a new annotation query to a dashboard, take the following steps:
 
-You can create new queries to fetch annotations from the native annotation store via the `-- Grafana --` data source by setting _Filter by_ to `Tags`.
+1. Click the dashboard settings (gear) icon in the dashboard header to open the settings menu.
+1. Select **Annotations**.
+1. Click **Add annotation query**.
+
+   If you've added a query before, the **+ New query** button is displayed.
+
+1. Enter a name for the annotation query.
+
+   This name is given to the toggle (checkbox) that will allow you to enable/disable showing annotation events from this query.
+
+1. Select the data source for the annotations.
+1. If you don't want to use the annotation query right away, clear the **Enabled** checkbox.
+1. If you don't want the annotation query toggle to be displayed in the dashboard, select the **Hidden** checkbox.
+1. Select a color for the event markers.
+1. Configure the query.
+
+   The annotation query options are different for each data source. For information about annotations in a specific data source, refer to the specific [data source]({{< relref "../../../datasources/" >}}) topic.
+
+## Built-in query
+
+After you add an annotation, they will still be visible. This is due to the built-in annotation query that exists on all dashboards. This annotation query will fetch all annotation events that originate from the current dashboard, which are stored in Grafana, and show them on the panel where they were created. This includes alert state history annotations.
+
+To add annotations directly to the dashboard, this query must be enabled.
+
+To confirm if the built-in query is enabled, take the following steps:
+
+1. Click the dashboard settings (gear) icon in the dashboard header to open the dashboard settings menu.
+1. Click **Annotations**.
+1. Find the **Annotations & Alerts (Built-in)** query.
+
+   If it says **Disabled** before the name of the query, then you'll need to click the query name to open it and update the setting.
+
+You can stop annotations from being fetched and drawn by taking the following steps:
+
+1. Click the dashboard settings (gear) icon in the dashboard header to open the settings menu.
+1. Click **Annotations**.
+1. Find and click the **Annotations & Alerts (Built-in)** query to open it.
+1. Click the **Enabled** toggle to turn it off.
+
+When you copy a dashboard using the **Save As** feature it will get a new dashboard id, so annotations created on source dashboard will no longer be visible on the copy. You can still show them if you add a new **Annotation Query** and filter by tags. However, this only works if the annotations on the source dashboard had tags to filter by.
+
+### Filter queries by tag
+
+You can create new queries to fetch annotations from the built-in annotation query using the `-- Grafana --` data source by setting _Filter by_ to `Tags`.
 
 Grafana v8.1 and later versions also support typeahead of existing tags, provide at least one tag.
 
 For example, create an annotation query name `outages` and specify a tag `outage`. This query will show all annotations (from any dashboard or via API) with the `outage` tag. If multiple tags are defined in an annotation query, then Grafana will only show annotations matching all the tags. To modify the behavior, enable `Match any`, and Grafana will show annotations that contain any one of the tags you provided.
 
-{{< figure src="/static/img/docs/annotations/annotations_typeahead_support-8-1-0.png" max-width="600px" >}}
+{{< figure src="/media/docs/grafana/dashboards/screenshot-annotations-typeahead-support-10.0.png" max-width="600px" >}}
 
-In Grafana v5.3+ it's possible to use template variables in the tag query. So if you have a dashboard showing stats for different services and a template variable that dictates which services to show, you can now use the same template variable in your annotation query to only show annotations for those services.
+You can also use template variables in the tag query. This means if you have a dashboard showing stats for different services and a template variable that dictates which services to show, you can use the same template variable in your annotation query to only show annotations for those services.
 
-{{< figure src="/static/img/docs/annotations/annotation_tag_filter_variable-8-1-0.png" max-width="600px" >}}
-
-## Querying other data sources
-
-Annotation events are fetched via annotation queries. To add a new annotation query to a dashboard
-open the dashboard settings menu, then select `Annotations`. This will open the dashboard annotations
-settings view. To create a new annotation query hit the `New` button.
-
-<!--![](/static/img/docs/v50/annotation_new_query.png)-->
-
-{{< figure src="/static/img/docs/v50/annotation_new_query.png" max-width="600px" >}}
-
-Specify a name for the annotation query. This name is given to the toggle (checkbox) that will allow
-you to enable/disable showing annotation events from this query. For example you might have two
-annotation queries named `Deploys` and `Outages`. The toggle will allow you to decide what annotations
-to show.
-
-### Annotation query details
-
-The annotation query options are different for each data source. For information about annotations in a specific data source, refer to the specific [data source]({{< relref "../../../datasources/" >}}) topic.
+{{< figure src="/media/docs/grafana/dashboards/screenshot-annotation-tag-filter-variable-10.0.png" max-width="600px" >}}

docs/sources/dashboards/build-dashboards/create-dashboard-url-variables/index.md

@@ -65,7 +65,7 @@ The query parameter `var-adhoc=key|=|value` applies the ad hoc filter configured
 
 ### Example
 
-See [https://play.grafana.org/d/000000002/influxdb-templated?orgId=1&var-datacenter=America&var-host=All&var-summarize=1m&var-adhoc=datacenter%7C%3D%7CAmerica] - this passes the ad hoc filter variable `adhoc` with the filter value `datacenter = America`.
+[This example in Grafana Play](https://play.grafana.org/d/000000002/influxdb-templated?orgId=1&var-datacenter=America&var-host=All&var-summarize=1m&var-adhoc=datacenter%7C%3D%7CAmerica) passes the ad hoc filter variable `adhoc` with the filter value `datacenter = America`.
 
 ## Controlling time range using the URL
 

docs/sources/dashboards/build-dashboards/create-dashboard/index.md

@@ -26,11 +26,18 @@ Dashboards and panels allow you to show your data in visual form. Each panel nee
 1. Click **Dashboards** in the left-side menu.
 1. Click **New** and select **New Dashboard**.
 1. On the empty dashboard, click **+ Add visualization**.
+
+   ![Empty dashboard state](/media/docs/grafana/dashboards/empty-dashboard-9.5.png)
+
 1. In the first line of the **Query** tab, click the dropdown list and select a data source.
 1. Write or construct a query in the query language of your data source.
 
    For more information about data sources, refer to [Data sources]({{< relref "../../../datasources/" >}}) for specific guidelines.
 
+1. Click the Refresh dashboard icon to query the data source.
+
+   ![Refresh dashboard icon](/media/docs/grafana/dashboards/screenshot-refresh-dashboard-9.5.png)
+
 1. In the visualization list, select a visualization type.
 
    ![Visualization selector](/media/docs/grafana/dashboards/screenshot-select-visualization-9-5.png)
@@ -49,9 +56,15 @@ Dashboards and panels allow you to show your data in visual form. Each panel nee
    - [Configure thresholds]({{< relref "../../../panels-visualizations/configure-thresholds/" >}})
    - [Configure standard options]({{< relref "../../../panels-visualizations/configure-standard-options/" >}})
 
-1. When you've finished editing your panel, click **Save** in the top right corner.
+1. When you've finished editing your panel, click **Save** to save the dashboard.
+
+   Alternatively, click **Apply** if you want to see your changes applied to the dashboard first. Then click the save icon in the dashboard header.
+
 1. Enter a name for your dashboard and select a folder, if applicable.
 1. Click **Save**.
+1. To add more panels to the dashboard, click **Add** in the dashboard header and select **Visualization** in the dropdown.
+
+   ![Add dropdown](/media/docs/grafana/dashboards/screenshot-add-dropdown-9.5.png)
 
 ## Configure repeating rows
 

docs/sources/dashboards/create-reports/index.md

@@ -10,6 +10,10 @@ keywords:
   - reporting
   - export
   - pdf
+labels:
+  products:
+    - cloud
+    - enterprise
 menuTitle: Reporting
 title: Create and manage reports
 weight: 85
@@ -26,7 +30,7 @@ Reporting enables you to automatically generate PDFs from any of your dashboards
 {{< figure src="/static/img/docs/enterprise/reports_list_8.1.png" max-width="500px" >}}
 -->
 
-Any changes you make to a dashboard used in a report are reflected the next time the report is sent. For example, if you change the time range in the dashboard, then the time range in the report also changes.
+Any changes you make to a dashboard used in a report are reflected the next time the report is sent. For example, if you change the time range in the dashboard, then the time range in the report also changes, unless you've configured a custom time range.
 
 For information about recent improvements to the reporting UI, refer to [Grafana reporting: How we improved the UX in Grafana](https://grafana.com/blog/2022/06/29/grafana-reporting-how-we-improved-the-ux-in-grafana/).
 
@@ -69,6 +73,14 @@ Only organization administrators can create reports by default. You can customiz
    - **Send test email:** To verify that the configuration works as expected. You can choose to send this email to the recipients configured for the report, or to a different set of email addresses only used for testing.
 1. Preview and save the report.
 
+### Save as draft
+
+{{% admonition type="note" %}}
+Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 9.1.0 and later and [Grafana Cloud Pro and Advanced](/docs/grafana-cloud/).
+{{% /admonition %}}
+
+You can save a report as a draft at any point during the report creation or update process. You can save a report as a draft even if it's missing required fields. Also, the report won't be sent according to its schedule while it's a draft.
+
 ### Choose template variables
 
 > **Note:** Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 7.5 and later behind the `reportVariables` feature flag, Grafana Enterprise version 8.0 and later without a feature flag, and [Grafana Cloud Pro and Advanced](/docs/grafana-cloud/).

docs/sources/dashboards/dashboard-public/index.md

@@ -8,9 +8,13 @@ weight: 8
 
 # Public dashboards
 
-> **Note:** This is an opt-in alpha feature.
+{{% admonition type="note" %}}
 
-> **Caution:** Making your dashboard public could result in a large number of queries to the datasources used by your dashboard.
+This feature is experimental.
+
+{{% /admonition %}}
+
+> **Caution:** Making your dashboard public could result in a large number of queries to the data sources used by your dashboard.
 > This can be mitigated by utilizing the enterprise [caching](https://grafana.com/docs/grafana/latest/enterprise/query-caching/) and/or rate limiting features.
 
 Public dashboards allow you to share your Grafana dashboard with anyone. This is useful when you want to expose your
@@ -20,7 +24,7 @@ dashboard to the world.
 
 - Anyone with the URL can access the dashboard.
 - Public dashboards are read-only.
-- Arbitrary queries **cannot** be run against your datasources through public dashboards. Public dashboards can only execute the
+- Arbitrary queries **cannot** be run against your data sources through public dashboards. Public dashboards can only execute the
   queries stored on the original dashboard.
 
 ## Enable the feature
@@ -66,21 +70,16 @@ The link no longer works. You must create a new public URL as in [Make a dashboa
 
 ## Email sharing
 
-> **Note:** Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Pro and Advanced](/docs/grafana-cloud).
+{{% admonition type="note" %}}
+
+This feature is experimental in [Grafana Cloud Pro and Advanced](/docs/grafana-cloud). The feature will have a cost by active users after being promoted into general availability.
+
+Please contact support to have the feature enabled.
+
+{{% /admonition %}}
 
 Email sharing allows you to share your public dashboard with only specific people via email, instead of having it accessible to anyone with the URL.
 
-### Enable email sharing
-
-> **Note:** For Grafana Cloud, contact support to have the feature enabled.
-
-Add the `publicDashboardsEmailSharing` feature toggle to your `custom.ini` file.
-
-```
-[feature_toggles]
-publicDashboardsEmailSharing = true
-```
-
 ### Invite a viewer
 
 1. Click the sharing icon to the right of the dashboard title.
@@ -158,7 +157,7 @@ guaranteed because plugin developers can override this functionality. The follow
 
 ### Unconfirmed:
 
-> **Note:** If you've confirmed one of these datasources work with public dashboards, let us know in our [Github](https://github.com/grafana/grafana/discussions/49253) discussion, and we'll mark it as confirmed!
+> **Note:** If you've confirmed one of these data sources work with public dashboards, let us know in our [Github](https://github.com/grafana/grafana/discussions/49253) discussion, and we'll mark it as confirmed!
 
 <table>
   <tr>
@@ -220,14 +219,14 @@ guaranteed because plugin developers can override this functionality. The follow
 
 ## Limitations
 
-- Panels that use frontend datasources will fail to fetch data.
+- Panels that use frontend data sources will fail to fetch data.
 - Template variables are currently not supported, but are planned to be in the future.
 - Exemplars will be omitted from the panel.
-- Only annotations that query the `-- Grafana --` datasource are supported.
+- Only annotations that query the `-- Grafana --` data source are supported.
 - Organization annotations are not supported.
 - Grafana Live and real-time event streams are not supported.
 - Library panels are currently not supported, but are planned to be in the future.
-- Datasources using Reverse Proxy functionality are not supported.
+- Data sources using Reverse Proxy functionality are not supported.
 
 We are excited to share this enhancement with you and we’d love your feedback! Please check out the [Github](https://github.com/grafana/grafana/discussions/49253) discussion and join the conversation.
 

docs/sources/dashboards/use-dashboards/index.md

@@ -25,13 +25,13 @@ This topic provides an overview of dashboard features and shortcuts, and describ
 
 The dashboard user interface provides a number of features that you can use to customize the presentation of your data.
 
-The following image and descriptions highlights all dashboards features.
+The following image and descriptions highlight all dashboard features.
 
 {{< figure src="/media/docs/grafana/dashboards/screenshot-dashboard-annotated-9-5-0.png" width="700px" >}}
 
 - (1) **Grafana home**: Click **Home** in the breadcrumb to be redirected to the home page configured in the Grafana instance.
-- (2) **Dashboard title**: When you click the dashboard title you can search for dashboard contained in the current folder.
-- (3) **Share dashboard or panel**: Use this option to share the current dashboard or panel by link or snapshot. You can also export the dashboard definition from the share modal.
+- (2) **Dashboard title**: When you click the dashboard title, you can search for dashboards contained in the current folder.
+- (3) **Share dashboard or panel**: Use this option to share the current dashboard or panel using a link or snapshot. You can also export the dashboard definition from the share modal.
 - (4) **Add**: Use this option to add a panel, dashboard row, or library panel to the current dashboard.
 - (5) **Save dashboard**: Click to save changes to your dashboard.
 - (6) **Dashboard insights**: Click to view analytics about your dashboard including information about users, activity, query counts. Learn more about [dashboard analytics]({{< relref "../assess-dashboard-usage/" >}}).
@@ -86,7 +86,7 @@ This section describes supported time units and relative ranges, the common time
 
 Grafana supports the following time units: `s (seconds)`, `m (minutes)`, `h (hours)`, `d (days)`, `w (weeks)`, `M (months)`, `Q (quarters)` and `y (years)`.
 
-The minus operator enables you to step back in time, relative to now. If you want to display the full period of the unit (day, week, month, etc...), append `/<time unit>` to the end. To view fiscal periods, use `fQ (fiscal quarter)` and `fy (fiscal year)` time units.
+The minus operator enables you to step back in time, relative to the current date and time, or `now`. If you want to display the full period of the unit (day, week, month, etc...), append `/<time unit>` to the end. To view fiscal periods, use `fQ (fiscal quarter)` and `fy (fiscal year)` time units.
 
 The plus operator enables you to step forward in time, relative to now. For example, you can use this feature to look at predicted data in the future.
 
@@ -105,13 +105,15 @@ The following table provides example relative ranges:
 | This Year              | `now/Y`     | `now/Y`     |
 | Previous fiscal year   | `now-1y/fy` | `now-1y/fy` |
 
-#### Note about Grafana Alerting
+{{% admonition type="note" %}}
 
-For Grafana Alerting, we do not support the following syntaxes at this time.
+Grafana Alerting does not support the following syntaxes at this time:
 
 - now+n for future timestamps.
 - now-1n/n for "start of n until end of n" because this is an absolute timestamp.
 
+{{% /admonition %}}
+
 ### Common time range controls
 
 The dashboard and panel time controls have a common UI.
@@ -156,6 +158,32 @@ You can set an absolute time range in the following ways:
 
 This section also displays recently used absolute ranges.
 
+#### Semi-relative time range
+
+{{% admonition type="note" %}}
+
+Grafana Alerting does not support semi-relative time ranges.
+
+{{% /admonition %}}
+
+You can also use the absolute time range settings to set a semi-relative time range. Semi-relative time range dashboards are useful when you need to monitor the progress of something over time, but you also want to see the entire history from a starting point.
+
+Set a semi-relative time range by setting the start time to an absolute timestamp and the end time to a “now” that is relative to the current time. For example:
+
+**Start time:** `2023-05-01 00:00:00`
+
+**End time:** `now`
+
+If you wanted to track the progress of something during business hours, you could set a time range that covers the current day, but starting at 8am, like so:
+
+**Start time:** `now/d+8h`
+
+**End time:** `now`
+
+This is equivalent to the **Today so far** time range preset, but it starts at 8:00am instead of 12:00am by appending +8h to the periodic start time.
+
+Using a semi-relative time range, as time progresses, your dashboard will automatically and progressively zoom out to show more history and fewer details. At the same rate, as high data resolution decreases, historical trends over the entire time period will become more clear.
+
 #### Zoom out (Cmd+Z or Ctrl+Z)
 
 Click the **Zoom out** icon to view a larger time range in the dashboard or panel visualization.

docs/sources/dashboards/variables/_index.md

@@ -45,18 +45,14 @@ To see variable settings, navigate to **Dashboard Settings > Variables**. Click
 
 Variables can be used in titles, descriptions, text panels, and queries. Queries with text that starts with `$` are templates. Not all panels will have template queries.
 
-The following dashboards in Grafana Play provide examples of template variables.
+The following dashboards in Grafana Play provide examples of template variables:
 
-- [Elasticsearch Metrics](https://play.grafana.org/d/z8OZC66nk/elasticsearch-8-2-0-sample-flight-data?orgId=1) - Uses ad hoc filters, global variables, and a custom variable.
-- [Graphite Templated Nested](https://play.grafana.org/d/000000056/graphite-templated-nested?orgId=1) - Uses query variables, chained query variables, an interval variable, and a repeated panel.
-- [Influx DB Group By Variable](https://play.grafana.org/d/000000137/influxdb-group-by-variable?orgId=1) - Query variable, panel uses the variable results to group the metric data.
-- [InfluxDB Raw Query Template Var](https://play.grafana.org/d/000000083/influxdb-raw-query-template-var?orgId=1) - Uses query variables, chained query variables, and an interval variable.
-- [InfluxDB Server Monitoring](https://play.grafana.org/d/AAy9r_bmk/influxdb-server-monitoring?orgId=1) - Uses query variables, chained query variables, an interval variable, and an ad hoc filter.
-- [Prometheus templating](https://play.grafana.org/d/000000063/prometheus-templating?orgId=1) - Uses chained query variables.
-- [Template Redux](https://play.grafana.org/d/p-k6QtkGz/template-redux?orgId=1) - Uses query variables, chained query variables, ad hoc filters, an interval variable, a text box variable, a custom variable, and a data source variable.
+- [Graphite Templated Nested](https://play.grafana.org/d/000000056/templated-dynamic-dashboard?orgId=1&var-app=backend&var-server=backend_01&var-server=backend_02&var-server=backend_03&var-server=backend_04&var-interval=1h) - Uses query variables, chained query variables, an interval variable, and a repeated panel.
+- [Global variables and interpolation](https://play.grafana.org/d/HYaGDGIMk/templating-global-variables-and-interpolation?orgId=1&var-Server=A%27A%22A&var-Server=BB%5CB)
+- [Elasticsearch Dummy Flight Data](https://play.grafana.org/d/z8OZC66nk/elasticsearch-8-2-0-sample-flight-data?orgId=1&var-Filters=Carrier%7C%3D%7CLogstash%20Airways&var-query0=) - Uses ad hoc filters.
 - [Templating, repeated panels](https://play.grafana.org/d/000000025/templating-repeated-panels?orgId=1) - Two sets of repeated panels use query variables.
-- [Templating showcase](https://play.grafana.org/d/000000091/templating-showcase?orgId=1) - Uses custom, query, chained query, and data source variables.
-- [Templating value groups](https://play.grafana.org/d/000000024/templating-value-groups?orgId=1) - Uses query variable with value groups.
+- [Template Redux](https://play.grafana.org/d/p-k6QtkGz/template-redux?orgId=1) - Uses query variables, chained query variables, an interval variable, a text box variable, a custom variable, and a data source variable.
+- [Nested Variables Drilldown](https://play.grafana.org/d/testdata-nested-variables-drilldown/templating-nested-variables-drilldown?orgId=1&var-datacenter=A&var-server=AA&var-server=AC&var-pod=All)
 
 ## Variable best practices
 

docs/sources/dashboards/variables/add-template-variables/index.md

@@ -247,13 +247,13 @@ Grafana has two built-in time range variables: `$__from` and `$__to`. They are c
 
 > **Note:** This special formatting syntax is only available in Grafana 7.1.2+
 
-| Syntax                   | Example result           | Description                                                                                               |
-| ------------------------ | ------------------------ | --------------------------------------------------------------------------------------------------------- |
-| `${__from}`              | 1594671549254            | Unix millisecond epoch                                                                                    |
-| `${__from:date}`         | 2020-07-13T20:19:09.254Z | No args, defaults to ISO 8601/RFC 3339                                                                    |
-| `${__from:date:iso}`     | 2020-07-13T20:19:09.254Z | ISO 8601/RFC 3339                                                                                         |
-| `${__from:date:seconds}` | 1594671549               | Unix seconds epoch                                                                                        |
-| `${__from:date:YYYY-MM}` | 2020-07                  | Any custom [date format](https://momentjs.com/docs/#/displaying/) that does not include the `:` character |
+| Syntax                   | Example result           | Description                                                                                                                                                      |
+| ------------------------ | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `${__from}`              | 1594671549254            | Unix millisecond epoch                                                                                                                                           |
+| `${__from:date}`         | 2020-07-13T20:19:09.254Z | No args, defaults to ISO 8601/RFC 3339                                                                                                                           |
+| `${__from:date:iso}`     | 2020-07-13T20:19:09.254Z | ISO 8601/RFC 3339                                                                                                                                                |
+| `${__from:date:seconds}` | 1594671549               | Unix seconds epoch                                                                                                                                               |
+| `${__from:date:YYYY-MM}` | 2020-07                  | Any custom [date format](https://momentjs.com/docs/#/displaying/) that does not include the `:` character. Uses browser time. Use `:date` or `:date:iso` for UTC |
 
 The syntax above also works with `${__to}`.
 
@@ -569,7 +569,7 @@ demo.robustperception.io:9100
 
 Using named capture groups, you can capture separate 'text' and 'value' parts from the options returned by the variable query. This allows the variable drop-down list to contain a friendly name for each value that can be selected.
 
-For example, when querying the `node_hwmon_chip_names` Prometheus metric, the `chip_name` is a lot friendlier that the `chip` value. So the following variable query result:
+For example, when querying the `node_hwmon_chip_names` Prometheus metric, the `chip_name` is a lot friendlier than the `chip` value. So the following variable query result:
 
 ```text
 node_hwmon_chip_names{chip="0000:d7:00_0_0000:d8:00_0",chip_name="enp216s0f0np0"} 1

docs/sources/datasources/_index.md

@@ -2,12 +2,6 @@
 aliases:
   - data-sources/
   - overview/
-cascade:
-  labels:
-    products:
-      - cloud
-      - enterprise
-      - oss
 title: Data sources
 weight: 60
 ---

docs/sources/datasources/azure-monitor/query-editor/index.md

@@ -129,6 +129,11 @@ The Azure documentation includes resources to help you learn KQL:
 - [Tutorial: Use Kusto queries in Azure Monitor](https://docs.microsoft.com/en-us/azure/data-explorer/kusto/query/tutorial?pivots=azuremonitor)
 - [SQL to Kusto cheat sheet](https://docs.microsoft.com/en-us/azure/data-explorer/kusto/query/sqlcheatsheet)
 
+> **Implicit dashboard time range usage:** As of Grafana v9.4.12 and v10.0, all Azure Monitor Logs queries
+> will use the specified dashboard or Explore time range by default.
+> Any query making use of a time range explicitly specified in the query body will have their query
+> executed against the intersection of the two time ranges. For more details on this change, refer to the [Azure Monitor Logs API documentation](https://learn.microsoft.com/en-us/rest/api/loganalytics/dataaccess/query/get?tabs=HTTP#uri-parameters).
+
 This example query returns a virtual machine's CPU performance, averaged over 5ms time grains:
 
 ```kusto

docs/sources/datasources/graphite/_index.md

@@ -50,10 +50,10 @@ To configure basic settings for the data source, complete the following steps:
 
 You can also configure settings specific to the Graphite data source:
 
-| Name        | Description                      |
-| ----------- | -------------------------------- |
-| **Version** | Select your version of Graphite. |
-| **Type**    | Select your type of Graphite.    |
+| Name        | Description                                                                                              |
+| ----------- | -------------------------------------------------------------------------------------------------------- |
+| **Version** | Select your version of Graphite. If you are using Grafana Cloud Graphite, this should be set to `1.1.x`. |
+| **Type**    | Select your type of Graphite. If you are using Grafana Cloud Graphite, this should be set to `Default`.  |
 
 ### Integrate with Loki
 

docs/sources/datasources/opentsdb/_index.md

@@ -35,16 +35,15 @@ To configure basic settings for the data source, complete the following steps:
 
 1.  Set the data source's basic configuration options:
 
-        | Name                | Description                                                                             |
-
-    | ------------------- | --------------------------------------------------------------------------------------- |
-    | **Name** | The data source name. This is how you refer to the data source in panels and queries. |
-    | **Default** | Default data source means that it will be pre-selected for new panels. |
-    | **URL** | The HTTP protocol, IP, and port of your OpenTSDB server (default port is usually 4242) |
-    | **Allowed cookies** | List the names of cookies to forward to the data source. |
-    | **Version** | Version = opentsdb version, either <=2.1 or 2.2 |
-    | **Resolution** | Metrics from opentsdb may have datapoints with either second or millisecond resolution. |
-    | **Lookup limit** | Default is 1000. |
+| Name                | Description                                                                              |
+| ------------------- | ---------------------------------------------------------------------------------------- |
+| **Name**            | The data source name. This is how you refer to the data source in panels and queries.    |
+| **Default**         | Default data source that will be be pre-selected for new panels.                         |
+| **URL**             | The HTTP protocol, IP, and port of your OpenTSDB server (default port is usually 4242).  |
+| **Allowed cookies** | Listing of cookies to forward to the data source.                                        |
+| **Version**         | The OpenTSDB version.                                                                    |
+| **Resolution**      | Metrics from OpenTSDB may have data points with either second or millisecond resolution. |
+| **Lookup limit**    | Default is 1000.                                                                         |
 
 ### Provision the data source
 
@@ -57,7 +56,7 @@ For more information about provisioning, and for available configuration options
 apiVersion: 1
 
 datasources:
-  - name: OpenTsdb
+  - name: OpenTSDB
     type: opentsdb
     access: proxy
     url: http://localhost:4242
@@ -70,7 +69,7 @@ datasources:
 
 Open a graph in edit mode by click the title. Query editor will differ if the data source has version <=2.1 or = 2.2.
 In the former version, only tags can be used to query OpenTSDB. But in the latter version, filters as well as tags
-can be used to query opentsdb. Fill Policy is also introduced in OpenTSDB 2.2.
+can be used to query OpenTSDB. Fill Policy is also introduced in OpenTSDB 2.2.
 
 ![](/static/img/docs/v43/opentsdb_query_editor.png)
 

docs/sources/datasources/prometheus/_index.md

@@ -62,16 +62,15 @@ To configure basic settings for the data source, complete the following steps:
     | `Disable metrics lookup`        | Checking this option will disable the metrics chooser and metric/label support in the query field's autocomplete. This helps if you have performance issues with bigger Prometheus instances.                                                                                                                   |
     | `Custom query parameters`       | Add custom parameters to the Prometheus query URL. For example `timeout`, `partial_response`, `dedup`, or `max_source_resolution`. Multiple parameters should be concatenated together with an '&'.                                                                                                         |
 
-        **Exemplars configuration:**
-
-        | Name              | Description                                                                                                                                                                                                                                                    |
+    **Exemplars configuration:**
 
+    | Name              | Description                                                                                                                                                                                                                                                    |
     | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-    | **Internal link** | Enable this option if you have an internal link. When enabled, this reveals the data source selector. Select the backend tracing data store for your exemplar data. |
-    | **Data source** | _(Visible only if you enable `Internal link`)_ Selects the backend tracing data store for your exemplar data. |
-    | **URL** | _(Visible only if you disable `Internal link`)_ Defines the external link's full URL. You can interpolate the value from the field by using the [`${__value.raw}` macro]({{< relref "../..//panels-visualizations/configure-data-links/#value-variables" >}}). |
-    | **URL label** | _(Optional)_ Adds a custom display label to override the value of the `Label name` field. |
-    | **Label name** | Adds a name for the exemplar traceID property. |
+    | **Internal link** | Enable this option if you have an internal link. When enabled, this reveals the data source selector. Select the backend tracing data store for your exemplar data.                                                                                            |
+    | **Data source**   | _(Visible only if you enable `Internal link`)_ Selects the backend tracing data store for your exemplar data.                                                                                                                                                  |
+    | **URL**           | _(Visible only if you disable `Internal link`)_ Defines the external link's full URL. You can interpolate the value from the field by using the [`${__value.raw}` macro]({{< relref "../..//panels-visualizations/configure-data-links/#value-variables" >}}). |
+    | **URL label**     | _(Optional)_ Adds a custom display label to override the value of the `Label name` field.                                                                                                                                                                      |
+    | **Label name**    | Adds a name for the exemplar traceID property.                                                                                                                                                                                                                 |
 
 ### Provision the data source
 

docs/sources/datasources/prometheus/query-editor/index.md

@@ -14,49 +14,56 @@ weight: 300
 
 # Prometheus query editor
 
-This topic explains querying specific to the Prometheus data source.
+Grafana provides a query editor for the Prometheus data source to create queries in PromQL. For more information about PromQL, see [Querying Prometheus](http://prometheus.io/docs/querying/basics/).
+
 For general documentation on querying data sources in Grafana, see [Query and transform data]({{< relref "../../../panels-visualizations/query-transform-data" >}}).
 
+For options and functions common to all query editors, see [Query editors]({{< relref "../../../panels-visualizations/query-transform-data" >}}).
+
 ## Choose a query editing mode
 
-You can switch the Prometheus query editor between two modes:
+The Prometheus query editor has two modes:
 
-- [Code mode](#code-mode), which provides a feature-rich editor for writing queries
-- [Builder mode](#builder-mode), which provides a visual query designer
+- [Builder mode](#builder-mode)
+- [Code mode](#code-mode)
 
-{{< figure src="/static/img/docs/prometheus/header-9-1.png" max-width="500px" class="docs-image--no-shadow" caption="Editor toolbar" >}}
+Each mode is explained in greater detail below.
 
-To switch between the editor modes, select the corresponding **Builder** and **Code** tabs.
+{{< figure src="/static/img/docs/prometheus/editing-mode.png" max-width="500px" class="docs-image--no-shadow" caption="Query editor mode" >}}
 
-To run a query, select **Run queries** located at the top of the editor.
+Both modes are synchronized, so you can switch between them. However, if there is an issue with the query while switching modes, a warning message will appear.
 
-> **Note:** To run Prometheus queries in [Explore]({{< relref "../../../explore" >}}), select **Run query**.
+## Toolbar elements
 
-Each mode is synchronized with the other modes, so you can switch between them without losing your work, although there are some limitations.
+The query editor toolbar contains the following elements:
 
-Builder mode doesn't yet support some complex queries.
-When you switch from Code mode to Builder mode with such a query, the editor displays a popup that explains how you might lose parts of the query if you continue.
-You can then decide whether you still want to switch to Builder mode.
+- **Kick start your query** - Click to see a list of operation patterns that help you quickly get started adding multiple operations to your query. These include:
 
-You can also use the [Explain feature]({{< relref "#use-explain-mode-to-understand-queries" >}}) to help understand how a query works, and augment queries by using [template variables]({{< relref "./template-variables/" >}}).
+  - Rate query starters
+  - Histogram query starters
+  - Binary query starters
 
-For options and functions common to all query editors, refer to [Query and transform data]({{< relref "../../../panels-visualizations/query-transform-data" >}}).
+Click the arrow next to each to see available options to add to your query.
+
+- **Explain** - Toggle to display a step-by-step explanation of all query components and operations.
+
+{{< figure src="/static/img/docs/prometheus/explain-results.png" max-width="500px" class="docs-image--no-shadow" caption="Explain results" >}}
+
+- **Builder/Code** - Click the corresponding **Builder** or **Code** tab on the toolbar to select a editor mode.
 
 ## Configure common options
 
-You can configure Prometheus-specific options in the query editor by setting several options regardless of its mode.
+You can configure Prometheus-specific options in the query editor by setting several options regardless of mode.
 
-{{< figure src="/static/img/docs/prometheus/options-9-1.png" max-width="500px" class="docs-image--no-shadow" caption="Options" >}}
+{{< figure src="/static/img/docs/prometheus/options.png" max-width="500px" class="docs-image--no-shadow" caption="Options" >}}
 
 ### Legend
 
 The **Legend** setting defines the time series's name. You can use a predefined or custom format.
 
-| Option      | Description                                                                                                                                                                                                           |
-| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Auto**    | Shows the value of a single label for each series with only one label, or displays all labels if a series has multiple labels.                                                                                        |
-| **Verbose** | Displays all labels.                                                                                                                                                                                                  |
-| **Custom**  | Uses templating to select which labels will be included.<br/>For example, `{{hostname}}` is replaced by the label value for the label `hostname`.<br/>Clear the input and click outside of it to select another mode. |
+- **Auto** - Displays unique labels. Also displays all overlapping labels if a series has multiple labels.
+- **Verbose** - Displays all label names.
+- **Custom** - Uses templating to select which labels will be included. For example, `{{hostname}}` is replaced by the label value for the label `hostname`. Clear the input and click outside of it to select another mode.
 
 ### Min step
 
@@ -66,155 +73,134 @@ This setting supports the `$__interval` and `$__rate_interval` macros.
 
 ### Format
 
-You can switch between **Table**, **Time series**, and **Heatmap** options by configuring the query's **Format**.
+Switch between the following format options:
 
-| Option          | Description                                                                                                                                                                                                                       |
-| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Table**       | This works only in a [Table panel]{{< relref "../../../panels-visualizations/visualizations/table" >}}.                                                                                                                           |
-| **Time series** | Uses the default time series format.                                                                                                                                                                                              |
-| **Heatmap**     | Displays metrics of the Histogram type on a [Heatmap panel]{{< relref "../../../panels-visualizations/visualizations/heatmap" >}} by converting cumulative histograms to regular ones and sorting the series by the bucket bound. |
+- **Time series** - The default time series format. See [Time series kind formats](https://grafana.github.io/dataplane/timeseries/) for information on time series data frames and how time and value fields are structured.
+- **Table** - This works only in a [Table panel]({{< relref "../../../panels-visualizations/visualizations/table" >}}).
+- **Heatmap** - Displays metrics of the Histogram type on a [Heatmap panel]({{< relref "../../../panels-visualizations/visualizations/heatmap" >}}) by converting cumulative histograms to regular ones and sorting the series by the bucket bound.
 
 ### Type
 
-The **Type** setting selects the query type.
+The **Type** setting sets the query type. These include:
 
-- A **Range** query returns a Range vector, comprised of a set of time series containing a range of data points over time for each time series.
-- An **Instant** query returns only the latest value that Prometheus has scraped for the requested time series. Instant queries can return results much faster than normal range queries and are well suited to look up label sets.
+- **Both** - The default option. Returns results for both a **Range** query and an **Instant** query.
+- **Range** - Returns a range vector consisting of a set of time series data containing a range of data points over time for each time series. You can choose lines, bars, points, stacked lines or stacked bars
+- **Instant** - Returns one data point per query and only the most recent point in the time range provided. The results can be shown in table format or as raw data. To depict instant query results in the time series panel, first add a field override, next add a property to the override named `Transform`, and finally select `Constant` from the **Transform** dropdown.
 
-  Instant query results are comprised of only one data point per series and can be shown in the time series panel by adding a field override, adding a property to the override named `Transform`, and selecting `Constant` from the **Transform** dropdown.
+For more information, refer to the [Time Series Transform option documentation]({{< relref "../../../panels-visualizations/visualizations/time-series#transform" >}}).
 
-  For more information, refer to the [Time Series Transform option documentation]({{< relref "../../../panels-visualizations/visualizations/time-series#transform" >}}).
+{{% admonition type="note" %}}
+Grafana modifies the request dates for queries to align them with the dynamically calculated step.
+This ensures a consistent display of metrics data, but it can result in a small gap of data at the right edge of a graph.
+{{% /admonition %}}
 
-- An **Exemplars** query runs with the regular query and shows exemplars in the graph.
+### Exemplars
 
-> **Note:** Grafana modifies the request dates for queries to align them with the dynamically calculated step.
-> This ensures a consistent display of metrics data, but it can result in a small gap of data at the right edge of a graph.
+Toggle **Exemplars** to run a query that includes exemplars in the graph. Exemplars are unique to Prometheus. For more information see [Introduction to exemplars](https://grafana.com/docs/grafana/latest/fundamentals/exemplars/).
 
-## Code mode
+{{% admonition type="note" %}}
+There is no option to add exemplars with an **Instant** query type.
+{{% /admonition %}}
 
-{{< figure src="/static/img/docs/prometheus/code-mode-9-1.png" max-width="500px" class="docs-image--no-shadow" caption="Code mode" >}}
+### Inspector
 
-In **Code mode**, you can write complex queries using a text editor with autocompletion features and syntax highlighting.
-It also contains a [Metrics browser]({{< relref "#metrics-browser" >}}) to further help you write queries.
+Click **Inspector** to get detailed statistics regarding your query. Inspector functions as a kind of debugging tool that "inspects" your query. It provides query statistics under **Stats**, request response time under **Query**, data frame details under **{} JSON**, and the shape of your data under **Data**.
 
-For more information about Prometheus's query language, refer to the [Prometheus documentation](http://prometheus.io/docs/querying/basics/).
-
-### Use autocompletion
-
-{{< figure src="/static/img/docs/prometheus/autocomplete-9-1.png" max-width="500px" class="docs-image--no-shadow" caption="Autocomplete" >}}
-
-Code mode's autocompletion feature works automatically while typing.
-To manually trigger autocompletion, use the keyboard shortcut <key>Ctrl</key>/<key>Cmd</key> + <key>Space</key>.
-
-The query editor can autocomplete static functions, aggregations, and keywords, and also dynamic items like metrics and labels.
-The autocompletion dropdown includes documentation for the suggested items where available.
-
-To run a query in [Explore]({{< relref "../../../explore/" >}}), use the keyboard shortcut <key>Shift</key> + <key>Enter</key>.
-
-### Metrics browser
-
-The metrics browser locates metrics and selects relevant labels to help you build basic queries.
-When you open the browser, it displays all available metrics and labels.
-If supported by your Prometheus instance, each metric also displays its HELP and TYPE as a tooltip.
-
-{{< figure src="/static/img/docs/prometheus/metric-browser-9-1.png" max-width="500px" class="docs-image--no-shadow" caption="Metrics browser" >}}
-
-When you select a metric, the browser narrows down the available labels to show only the ones applicable to the metric.
-You can then select one or more labels for which the available label values are shown in lists in the bottom section.
-Select one or more values for each label to tighten your query scope.
-
-> **Note:** If you do not remember a metric name to start with, you can also select a few labels to narrow down the list, then find relevant label values.
-
-All lists in the metrics browser have a search field above them to quickly filter for metrics or labels that match a certain string.
-The values section has only one search field, and its filtering applies to all labels to help you find values across labels once selected.
-
-For example, among your labels `app`, `job`, `job_name` only one might with the value you are looking for.
-
-Once you are satisfied with your query, click "Use query" to run the query. The button "Use as rate query" adds a `rate(...)[$__interval]` around your query to help write queries for counter metrics.
-The "Validate selector" button will check with Prometheus how many time series are available for that selector.
+{{< figure src="/static/img/docs/prometheus/insepctor-9-5.png" max-width="500px" class="docs-image--no-shadow" caption="Inspector" >}}
 
 ## Builder mode
 
-In **Builder mode**, you can build queries using a visual interface.
+**Builder mode** helps you build queries using a visual interface. This option is best for users who have limited or no previous experience working with Prometheus and PromQL.
 
-This video demonstrates how to use the visual Prometheus query builder available since Grafana v9.0:
+This video demonstrates how to use the visual Prometheus query builder available in Grafana v9.0:
 
 {{< vimeo 720004179 >}}
 
 </br>
 
-### Toolbar
+### Metrics
 
-In addition to the **Run query** button and mode switcher, Builder mode includes additional elements:
+{{< figure src="/static/img/docs/prometheus/metrics-and-labels.png" max-width="500px" class="docs-image--no-shadow" caption="Metric and label filters" >}}
 
-| Name                      | Description                                                                               |
-| ------------------------- | ----------------------------------------------------------------------------------------- |
-| **Kick start your query** | A list of operation patterns that help you quickly add multiple operations to your query. |
-| **Explain**               | Displays a step-by-step explanation of all query parts and its operations.                |
-
-### Metric and labels
-
-{{< figure src="/static/img/docs/prometheus/metric-select-9-1.png" max-width="500px" class="docs-image--no-shadow" caption="Metric and labels" >}}
-
-Select a specific metric name from the dropdown list.
+When you are ready to create a query, you can choose the specific metric name from the dropdown list under **Metric**.
 The data source requests the list of available metrics from the Prometheus server based on the selected time rage.
 You can also enter text into the selector when the dropdown is open to search and filter the list.
 
+### Label filters
+
 Select desired labels and their values from the dropdown list.
 When a metric is selected, the data source requests available labels and their values from the server.
 Use the `+` button to add a label, and the `x` button to remove a label.
 
 ### Operations
 
-{{< figure src="/static/img/docs/prometheus/operations-9-1.png" max-width="500px" class="docs-image--no-shadow" caption="Operations" >}}
+{{< figure src="/static/img/docs/prometheus/operations.png" max-width="500px" class="docs-image--no-shadow" caption="Operations" >}}
 
-Select the `+ Operations` button to add operations to your query.
-The query editor groups operations into related sections, and you can type while the operations dropdown is open to search and filter the list.
+Select the **+ Operations** button to add operations to your query.
 
-The query editor displays a query's operations as boxes in the operations section.
-Each operation's header displays its name, and additional action buttons appear when you hover your cursor over the header:
+The query editor groups operations into the following sections:
 
-| Button | Action                                                            |
-| ------ | ----------------------------------------------------------------- |
-| `v`    | Replaces the operation with different operation of the same type. |
-| `info` | Opens the operation's description tooltip.                        |
-| `x`    | Removes the operation.                                            |
+- Aggregations - for additional information see [Aggregation operators](https://prometheus.io/docs/prometheus/latest/querying/operators/#aggregation-operators).
+- Range functions - for additional information see [Functions](https://prometheus.io/docs/prometheus/latest/querying/functions/#functions).
+- Functions - for additional information see [Functions](https://prometheus.io/docs/prometheus/latest/querying/functions/#functions).
+- Binary operations - for additional information see [Binary operators](https://prometheus.io/docs/prometheus/latest/querying/operators/#binary-operators).
+- Trigonometric - for additional information see [Trigonometric functions](https://prometheus.io/docs/prometheus/latest/querying/functions/#trigonometric-functions).
+- Time functions - for additional information see [Functions](https://prometheus.io/docs/prometheus/latest/querying/functions/#functions).
 
-Some operations have additional parameters under the operation header.
-For details about each operation, use the `info` button to view the operation's description, or refer to the Prometheus documentation on [query functions](https://prometheus.io/docs/prometheus/latest/querying/functions/).
+All operations have function parameters under the operation header. Click the `operator` to see a full list of supported functions. Some operations allow you to apply specific labels to functions.
+
+{{< figure src="/static/img/docs/prometheus/use-function-by-label-9-5.png" max-width="500px" class="docs-image--no-shadow" caption="Functions and labels" >}}
 
 Some operations make sense only when used in a specific order.
 If adding an operation would result in nonsensical query, the query editor adds the operation to the correct place.
-To re-order operations manually, drag the operation box by its name and drop it into the desired place.
 
 #### Hints
 
-{{< figure src="/static/img/docs/prometheus/hint-8-5.png" max-width="500px" class="docs-image--no-shadow" caption="Hint" >}}
+{{< figure src="/static/img/docs/prometheus/hint-example.png" max-width="500px" class="docs-image--no-shadow" caption="Hint" >}}
 
 The query editor can detect which operations are most appropriate for some selected metrics.
-If it does, it displays a hint next to the `+ Operations` button.
+If it does, it displays a hint next to the **+ Operations** button.
 
-To add the operations to your query, click the hint.
+To add the operation to your query, click the **Hint**.
 
-## Use Explain mode to understand queries
+Once you are satisfied with your query, click **Run query**.
 
-{{< figure src="/static/img/docs/prometheus/explain-8-5.png" max-width="500px" class="docs-image--no-shadow" caption="Explain mode" >}}
+## Code mode
 
-Explain mode helps you understand a query by displaying a step-by-step explanation of all query components and operations.
+**Code mode** is for the experienced Prometheus user with prior expertise in PromQL, Prometheus' query language. The Code mode editor allows you to create queries just as you would in Prometheus. For more information about PromQL see [Querying Prometheus](http://prometheus.io/docs/querying/basics/).
 
-### Additional options
+{{< figure src="/static/img/docs/prometheus/code-mode.png" max-width="500px" class="docs-image--no-shadow" caption="Code mode" >}}
 
-In addition to these Builder mode-specific options, the query editor also displays the options it shares in common with Code mode.
-For details, refer to the [common options]({{< relref "#configure-common-options" >}}).
+The user interface (UI) also lets you select metrics, labels, filters and operations.
 
-## Apply annotations
+You can write complex queries using the text editor with autocompletion features and syntax highlighting.
+It also contains a [Metrics browser]({{< relref "#metrics-browser" >}}) to further help you write queries.
 
-[Annotations]({{< relref "../../../dashboards/build-dashboards/annotate-visualizations" >}}) overlay rich event information on top of graphs.
-You can add annotation queries in the Dashboard menu's Annotations view.
+### Use autocomplete
 
-Prometheus supports two ways to query annotations.
+Code mode's autocomplete feature works automatically while typing. The query editor can autocomplete static functions, aggregations, keywords, and also dynamic items like metrics and labels.
+The autocompletion dropdown includes documentation for the suggested items where available.
 
-- A regular metric query
-- A Prometheus query for pending and firing alerts (for details see [Inspecting alerts during runtime](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/#inspecting-alerts-during-runtime))
+### Metrics browser
 
-The step option is useful to limit the number of events returned from your query.
+The metrics browser locates metrics and selects relevant labels to help you build basic queries.
+When you click **Metrics browser**, it displays all available metrics and labels.
+If supported by your Prometheus instance, each metric also displays its `HELP` and `TYPE` as a tooltip.
+
+{{< figure src="/static/img/docs/prometheus/metric-browser.png" max-width="500px" class="docs-image--no-shadow" caption="Metrics browser" >}}
+
+When you select a metric under Step 1, the browser narrows down the available labels to show only the ones applicable to the metric.
+You can then select one or more labels shown in Step 2.
+Select one or more values in Step 3 for each label to tighten your query scope.
+In Step 4, you can select **Use query** to run the query, **Use as rate query** to add the rate operation to your query (`$__rate_interval`), **Validate selector** to verify the selector is valid and show the number of series found, or **Clear** to clear your selections and start over.
+
+{{% admonition type="note" %}}
+If you do not remember a metric name, you can also select a few labels to narrow down the list, then find relevant label values.
+{{% /admonition %}}
+
+All lists in the metrics browser have a search field above them to quickly filter for metrics or labels that match a certain string.
+The values section has only one search field, and its filtering applies to all labels to help you find values across labels once selected.
+
+For example, among your labels `app`, `job`, `job_name` only one might have the value you are looking for.
+
+Once you are satisfied with your query, click **Run query**.

docs/sources/datasources/prometheus/template-variables/index.md

@@ -15,15 +15,14 @@ weight: 400
 
 # Prometheus template variables
 
-Instead of hard-coding details such as server, application, and sensor names in metric queries, you can use variables.
+Instead of hard-coding details such as server, application, and sensor names in metric queries, you can use variables. Grafana refers to such variables as **template** variables.
 Grafana lists these variables in dropdown select boxes at the top of the dashboard to help you change the data displayed in your dashboard.
-Grafana refers to such variables as template variables.
 
-For an introduction to templating and template variables, refer to the [Templating]({{< relref "../../../dashboards/variables" >}}) and [Add and manage variables]({{< relref "../../../dashboards/variables/add-template-variables" >}}) documentation.
+For an introduction to templating and template variables, see [Templating]({{< relref "../../../dashboards/variables" >}}) and [Add and manage variables]({{< relref "../../../dashboards/variables/add-template-variables" >}}).
 
 ## Use query variables
 
-Use variables of the type _Query_ to query Prometheus for a list of metrics, labels, or label values.
+You have the option to use several different variable types, but variables of the type `Query` will query Prometheus for a list of metrics, labels, label values, a query result or a series.
 
 Select a Prometheus data source query type and enter the required inputs:
 
@@ -37,6 +36,26 @@ Select a Prometheus data source query type and enter the required inputs:
 
 For details on _metric names_, _label names_, and _label values_, refer to the [Prometheus documentation](http://prometheus.io/docs/concepts/data_model/#metric-names-and-labels).
 
+### Query options
+
+Under the query variable type, you can set the following query options:
+
+| Option                | Description                                                                                             |
+| --------------------- | ------------------------------------------------------------------------------------------------------- |
+| **Data source**       | Select your data source from the dropdown list.                                                         |
+| **Select query type** | Options are `default`, `value` and `metric name`. Each query type hits a different Prometheus endpoint. |
+| **Regex**             | Optional, if you want to extract part of a series name or metric node segment.                          |
+| **Sort**              | Default is `disabled`. Options include `alphabetical`, `numerical` and `alphabetical case-sensitive`.   |
+| **Refresh**           | When to update the values for the variable. Options are `On dashboard load` and `On time range change`. |
+
+### Selection options
+
+The following selection options are available:
+
+- **Multi-value** - Check this option to enable multiple values to be selected at the same time.
+
+- **Include All option** - Check this option to include all variables.
+
 ### Use interval and range variables
 
 You can use some global built-in variables in query variables, for example, `$__interval`, `$__interval_ms`, `$__range`, `$__range_s` and `$__range_ms`.

docs/sources/datasources/tempo/query-editor/index.md

@@ -58,15 +58,25 @@ To configure your Tempo data source to use this feature, refer to the [Tempo doc
 
 To query a particular trace:
 
-1. Select the **TraceID** query type.
-1. Enter the trace's ID into the **Trace ID** field.
+1. Select the **TraceQL** query type.
+1. Enter the trace's ID into the query field.
 
 {{< figure src="/static/img/docs/tempo/query-editor-traceid.png" class="docs-image--no-shadow" max-width="750px" caption="Screenshot of the Tempo TraceID query type" >}}
 
 ## Query by TraceQL
 
+Inspired by PromQL and LogQL, TraceQL is a query language designed for selecting traces.
+The default traces search reviews the whole trace.
+TraceQL provides a method for formulating precise queries so you can zoom in to the data you need. Query results are returned faster because the queries limit what is searched
+
 To learn more about how to query by TraceQL, refer to the [TraceQL documentation](/docs/tempo/latest/traceql).
 
+You can create TraceQL queries using the Query editor or using Search query tab (preview feature).
+
+[//]: # 'Include content for preview of Search tab featuring TraceQL query builder'
+
+{{< docs/shared source="grafana" lookup="datasources/tempo-search-traceql.md" leveloffset="+1" >}}
+
 ## Query Loki for traces
 
 To find traces to visualize, you can use the [Loki query editor]({{< relref "../../loki#loki-query-editor" >}}).

docs/sources/datasources/testdata/_index.md

@@ -40,7 +40,7 @@ To configure basic settings for the data source, complete the following steps:
 
 ## Create mock data
 
-{{< figure src="/static/img/docs/v41/test_data_add.png" class="docs-image--no-shadow" caption="Adding test data" >}}
+{{< figure src="/media/docs/grafana/data-sources/screenshot-testdata-add-10.0.png" class="docs-image--no-shadow" caption="Adding test data" >}}
 
 Once you've added the TestData data source, your Grafana instance's users can use it as a data source in any metric panel.
 
@@ -50,7 +50,7 @@ Instead of providing a query editor, the TestData data source helps you select a
 
 You can assign an **Alias** to each scenario, and many have their own options that appear when selected.
 
-{{< figure src="/static/img/docs/v41/test_data_csv_example.png" class="docs-image--no-shadow" caption="Using CSV Metric Values" >}}
+{{< figure src="/media/docs/grafana/data-sources/screenshot-testdata-csv-example-10.0.png" class="docs-image--no-shadow" caption="Using CSV Metric Values" >}}
 
 **Available scenarios:**
 

docs/sources/developers/angular_deprecation/_index.md

@@ -18,7 +18,7 @@ AngularJS is an old frontend framework whose active development stopped many yea
 
 ## When will Angular plugins stop working?
 
-Our goal is to transfer all the remaining Angular code to the core of Grafana before Grafana 10 is released in Summer 2023. Once this is done, the option "[angular_support_enabled](https://github.com/grafana/grafana/blob/d61bcdf4ca5e69489e0067c56fbe7f0bfdf84ee4/conf/defaults.ini#L362)" will be disabled by default, resulting in the deactivation of all Angular plugins. In case you still rely on AngularJS-based plugins developed internally or by the community, you will need to enable this option to continue using them.
+Our goal is to transfer all the remaining Angular code to the core of Grafana before Grafana 10 is released in Summer 2023. Once this is done, the option "[angular_support_enabled](https://github.com/grafana/grafana/blob/d61bcdf4ca5e69489e0067c56fbe7f0bfdf84ee4/conf/defaults.ini#L362)" will be disabled by default for new Grafana Cloud users, resulting in the inability to use Angular plugins. In case you still rely on AngularJS-based plugins developed internally or by the community, you will need to enable this option to continue using them. Following the release of Grafana 10 we will be migrating Grafana Cloud users where possible and disabling Angular support when appropriate, we will also be introducing new features to help all users identify how they are impacted and to warn of the use of deprecated plugins within the Grafana UI.
 
 ## When will we remove Angular support completely?
 
@@ -36,6 +36,7 @@ We encourage you to locate the repository of the corresponding plugin and create
 
 ### Links
 
-- [Migrate Angular to React](https://grafana.com/docs/grafana/latest/developers/plugins/migration-guide/#migrate-a-plugin-from-angular-to-react)
+- [Migrate Angular to React]({{< relref "../plugins/migration-guide/angular-react/" >}})
 - [Build a panel plugin](https://grafana.com/tutorials/build-a-panel-plugin/)
 - [Build a data source plugin](https://grafana.com/tutorials/build-a-data-source-plugin/)
+- [List of current Angular plugins]({{< relref "./angular-plugins/" >}})

docs/sources/developers/angular_deprecation/angular-plugins.md

@@ -0,0 +1,642 @@
+---
+keywords:
+  - grafana
+  - plugins
+  - plugin
+  - angular
+  - deprecation
+  - migration
+title: Plugins using AngularJS
+---
+
+The use of AngularJS in Grafana has been [deprecated]({{< relref "../angular_deprecation" >}}) and support for it will be removed in a future release.
+
+This page is to help users of Grafana understand how they might be impacted by the removal of Angular support, and whether a migration option exists.
+
+It lists the latest versions of plugins currently available in the [Plugins Catalog](https://grafana.com/plugins) which depend on Angular, and will stop working when Angular support is removed from Grafana. The list will be updated as more plugins migrate to React or offer migration advice.
+
+> **Note:** We advise you to ensure you are running the latest version of plugins, as previous releases of plugins not listed here may still require AngularJS.
+
+We also list the year in which the plugin was last updated in the catalog and where appropriate, highlight warnings for plugins where the source repository has not been updated in a number of years and appears inactive. This may help indicate the likelihood of a migration being undertaken, but is informational rather than definitive.
+
+> **Note:** Plugins were updated to include signatures in 2021, so whilst a plugin may show as having been updated at that point - the last update to its functionality or dependencies may have been longer ago.
+
+## What should I do with the information below?
+
+- Consider the available migration steps.
+- Check your Grafana instances for usage of these plugins - see information here on [browsing installed plugins]({{< relref "../../administration/plugin-management/#browse-plugins" >}}).
+- Review the project repositories to add your support to any migration issues.
+
+## I'm a plugin author
+
+We are greatly appreciative of the developers who have contributed plugins to the Grafana ecosystem, your work has helped support millions of users to gain insights into their data. A plugin being listed below is no reflection on its quality, and is purely to help users understand the impact of the removal of Angular support in Grafana.
+
+Guidance on migrating a plugin to React can be found in our [migration guide]({{< relref "../plugins/migration-guide/angular-react/" >}}). If you would like to add any specific migration guidance for your plugin here or update our assessment, please open a PR by clicking the `Suggest an edit` button at the bottom of this page.
+
+# Current AngularJS based plugins
+
+## Apps
+
+### [Cloudflare Grafana App](https://grafana.com/grafana/plugins/cloudflare-app/)
+
+Latest Version: 0.2.4 | Signature: Commercial | Last Updated: 2022
+
+### [DevOpsProdigy KubeGraf](https://grafana.com/grafana/plugins/devopsprodigy-kubegraf-app/)
+
+Latest Version: 1.5.2 | Signature: Community | Last Updated: 2021
+
+> **Warning:** [Issues](https://github.com/devopsprodigy/kubegraf/issues/71) in the project repository suggest that the project _may_ be unsupported.
+
+> **Migration available - potential alternative:** Grafana Cloud includes a [Kubernetes integration](https://grafana.com/solutions/kubernetes/).
+
+### [Kentik Connect Pro](https://grafana.com/grafana/plugins/kentik-connect-app/)
+
+Latest Version: 1.6.2 | Signature: Commercial | Last Updated: 2023
+
+## Datasources
+
+### [Druid](https://grafana.com/grafana/plugins/abhisant-druid-datasource/)
+
+Latest Version: v0.0.6 | Signature: Community | Last Updated: 2021
+
+> **Migration available - plugin superseded:** The original plugin only claims support for Grafana v4.x.x, it was replaced with a [new plugin](https://grafana.com/grafana/plugins/grafadruid-druid-datasource/) based on React.
+
+### [Akumuli](https://grafana.com/grafana/plugins/akumuli-datasource/)
+
+Latest Version: 1.3.12 | Signature: Community | Last Updated: 2021
+
+> **Warning:** [Issues](https://github.com/akumuli/Akumuli/issues/379) in the project repository suggest that the project _may_ be unsupported.
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/akumuli/Akumuli/) in the past 3 years suggests project _may_ not be actively maintained.
+
+### [DarkSky](https://grafana.com/grafana/plugins/andig-darksky-datasource/)
+
+Latest Version: 1.0.2 | Signature: Community | Last Updated: 2021
+
+> **Warning:** [Project repository](https://github.com/andig/grafana-darksky) was archived on September 27, 2022.
+
+> **Warning:** Apple removed support for the DarkSky API on March 31, 2023 - [source](https://support.apple.com/en-us/HT213526).
+
+### [Finance](https://grafana.com/grafana/plugins/ayoungprogrammer-finance-datasource/)
+
+Latest Version: 1.0.1 | Signature: Community | Last Updated: 2021
+
+> **Warning:** [Issues](https://github.com/ayoungprogrammer/grafana-finance/issues/7) in the project repository suggest that the project _may_ be unsupported.
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/ayoungprogrammer/grafana-finance) in the past 6 years suggests project _may_ not be actively maintained.
+
+### [Prometheus AlertManager](https://grafana.com/grafana/plugins/camptocamp-prometheus-alertmanager-datasource/)
+
+Latest Version: 1.2.1 | Signature: Community | Last Updated: 2022
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/camptocamp/grafana-prometheus-alertmanager-datasource) in the past year suggests project _may_ not be actively maintained.
+
+> **Migration available - potential alternative:** Grafana includes an AlertManager data source as a Core plugin.
+
+### [Chaos Mesh](https://grafana.com/grafana/plugins/chaosmeshorg-datasource/)
+
+Latest Version: 2.2.3 | Signature: Community | Last Updated: 2022
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/chaos-mesh/datasource) in the past year suggests project _may_ not be actively maintained.
+
+### [Cognite Data Fusion](https://grafana.com/grafana/plugins/cognitedata-datasource/)
+
+Latest Version: 3.0.0 | Signature: Commercial | Last Updated: 2023
+
+### [DeviceHive](https://grafana.com/grafana/plugins/devicehive-devicehive-datasource/)
+
+Latest Version: 2.0.2 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/devicehive/devicehive-grafana-datasource) in the past 5 years suggests project _may_ not be actively maintained.
+
+### [Google BigQuery](https://grafana.com/grafana/plugins/doitintl-bigquery-datasource/)
+
+Latest Version: 2.0.3 | Signature: Community | Last Updated: 2022
+
+> **Migration available - plugin superseded:** Grafana provides its own [Google BigQuery Plugin](https://grafana.com/grafana/plugins/grafana-bigquery-datasource/). The previous [Project repository](https://github.com/doitintl/bigquery-grafana) was archived on December 11, 2022 with a recommendation to migrate to the aforementioned Grafana provided plugin.
+
+### [Open-Falcon](https://grafana.com/grafana/plugins/fastweb-openfalcon-datasource/)
+
+Latest Version: 1.0.1 | Signature: Community | Last Updated: 2021
+
+> **Warning:** [Project repository](https://github.com/open-falcon/grafana-openfalcon-datasource) suggests support for Grafana v4.2 - Grafana v5.4.
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/open-falcon/grafana-openfalcon-datasource) in the past year suggests project _may_ not be actively maintained.
+
+### [GraphQL Data Source](https://grafana.com/grafana/plugins/fifemon-graphql-datasource/)
+
+Latest Version: 1.3.0 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Project support is unclear after a request for new maintainers - [source](https://github.com/fifemon/graphql-datasource/issues/77).
+
+> **Migration available - potential alternative:** The [Infinity](https://grafana.com/grafana/plugins/yesoreyeram-infinity-datasource/) data source supports GraphQL.
+
+### [Cloudera Manager](https://grafana.com/grafana/plugins/foursquare-clouderamanager-datasource/)
+
+Latest Version: 0.9.3 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/foursquare/datasource-plugin-clouderamanager) in the past 7 years suggests project _may_ not be actively maintained.
+
+### [Simple Annotations](https://grafana.com/grafana/plugins/fzakaria-simple-annotations-datasource/)
+
+Latest Version: 1.0.1 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Plugin only claims support for Grafana v4.x.x.
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/fzakaria/simple-annotations-plugin/) in the past 6 years suggests project _may_ not be actively maintained.
+
+> **Warning:** Developer no longer maintains the project, but is open to contributions: https://github.com/fzakaria/simple-annotations-plugin/issues/2
+
+### [Gnocchi](https://grafana.com/grafana/plugins/gnocchixyz-gnocchi-datasource/)
+
+Latest Version: 1.7.1 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Plugin only claims support for Grafana v4.x.x
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/gnocchixyz/grafana-gnocchi-datasource) in the past 3 years suggests project _may_ not be actively maintained.
+
+### [MetaQueries](https://grafana.com/grafana/plugins/goshposh-metaqueries-datasource/)
+
+Latest Version: 0.0.9 | Signature: Community | Last Updated: 2022
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/GoshPosh/grafana-meta-queries) in the past year suggests project _may_ not be actively maintained.
+
+### [Open Distro for Elasticsearch](https://grafana.com/grafana/plugins/grafana-es-open-distro-datasource/)
+
+Latest Version: 1.0.6 | Signature: Grafana | Last Updated: 2021
+
+> **Migration available - plugin superseded:** Plugin was deprecated in favour of the [OpenSearch Plugin](https://grafana.com/grafana/plugins/grafana-opensearch-datasource/).
+
+### [KairosDB](https://grafana.com/grafana/plugins/grafana-kairosdb-datasource/)
+
+Latest Version: 3.0.2 | Signature: Grafana | Last Updated: 2021
+
+> **Warning:** [Project repository](https://github.com/grafana/kairosdb-datasource) was archived on August 30th, 2021 and is no longer maintained.
+
+### [SimpleJson](https://grafana.com/grafana/plugins/grafana-simple-json-datasource/)
+
+Latest Version: 1.4.2 | Signature: Grafana | Last Updated: 2021
+
+> **Migration available - potential alternative:** [Project repository](https://github.com/grafana/simple-json-datasource) is no longer maintained, but a number of alternatives exist, including - [Infinity](https://grafana.com/grafana/plugins/yesoreyeram-infinity-datasource/), [JSON](https://grafana.com/grafana/plugins/simpod-json-datasource) and [JSON API](https://grafana.com/grafana/plugins/marcusolsson-json-datasource).
+
+> **Note:** If you're looking for an example of a data source plugin to start from, refer to [grafana-starter-datasource-backend](https://github.com/grafana/grafana-starter-datasource-backend).
+
+### [Splunk](https://grafana.com/grafana/plugins/grafana-splunk-datasource/)
+
+Latest Version: 4.1.6 | Signature: Grafana | Last Updated: 2023
+
+> **Note:** Removal of any angular dependency is on the near term roadmap.
+
+### [Strava](https://grafana.com/grafana/plugins/grafana-strava-datasource/)
+
+Latest Version: 1.5.1 | Signature: Grafana | Last Updated: 2022
+
+> **Note:** Removal of any angular dependency is on the near term roadmap.
+
+### [openHistorian](https://grafana.com/grafana/plugins/gridprotectionalliance-openhistorian-datasource/)
+
+Latest Version: 1.0.3 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/GridProtectionAlliance/openHistorian-grafana/) in the past 2 years suggests project _may_ not be actively maintained.
+
+### [OSIsoft-PI](https://grafana.com/grafana/plugins/gridprotectionalliance-osisoftpi-datasource/)
+
+Latest Version: 3.1.0 | Signature: Community | Last Updated: 2023
+
+> **Note:** Fixed in 4.0.0 which should be published soon - [source](https://github.com/GridProtectionAlliance/osisoftpi-grafana/issues/119#issuecomment-1493566212).
+
+### [Hawkular](https://grafana.com/grafana/plugins/hawkular-datasource/)
+
+Latest Version: 1.1.2 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/hawkular/hawkular-grafana-datasource) in the past 5 years suggests project _may_ not be actively maintained.
+
+### [Humio](https://grafana.com/grafana/plugins/humio-datasource/)
+
+Latest Version: 3.3.1 | Signature: Commercial | Last Updated: 2022
+
+### [IBM APM](https://grafana.com/grafana/plugins/ibm-apm-datasource/)
+
+Latest Version: 0.9.1 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/rafal-szypulka/grafana-ibm-apm) in the past 3 years suggests project _may_ not be actively maintained.
+
+### [PRTG](https://grafana.com/grafana/plugins/jasonlashua-prtg-datasource/)
+
+Latest Version: 4.0.4 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/neuralfraud/grafana-prtg) in the past 4 years suggests project _may_ not be actively maintained.
+
+> **Warning:** Unmaintained since 2017 - [source](https://github.com/neuralfraud/grafana-prtg/wiki).
+
+### [LinkSmart HDS Datasource](https://grafana.com/grafana/plugins/linksmart-hds-datasource/)
+
+Latest Version: 1.0.2 | Signature: Community | Last Updated: 2021
+
+> **Warning:** [Project repository](https://github.com/linksmart/grafana-hds-datasource) was archived on April 4th, 2022 and is no longer maintained.
+
+### [LinkSmart SensorThings](https://grafana.com/grafana/plugins/linksmart-sensorthings-datasource/)
+
+Latest Version: 1.3.1 | Signature: Community | Last Updated: 2021
+
+> **Warning:** [Project repository](https://github.com/linksmart/grafana-sensorthings-datasource) was archived on April 4th, 2022 and is no longer maintained.
+
+### [Monasca](https://grafana.com/grafana/plugins/monasca-datasource/)
+
+Latest Version: 1.0.1 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/openstack/monasca-grafana-datasource) in the past 2 years suggests project _may_ not be actively maintained.
+
+> **Warning:** Last updated to support Grafana v7.
+
+### [Monitoring Art](https://grafana.com/grafana/plugins/monitoringartist-monitoringart-datasource/)
+
+Latest Version: 1.0.1 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/monitoringartist/grafana-monitoring-art) in the past 6 years suggests project _may_ not be actively maintained.
+
+### [GoogleCalendar](https://grafana.com/grafana/plugins/mtanda-google-calendar-datasource/)
+
+Latest Version: 1.0.5 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/mtanda/grafana-google-calendar-datasource) in the past 2 years suggests project _may_ not be actively maintained.
+
+### [USGS Water Services](https://grafana.com/grafana/plugins/natel-usgs-datasource/)
+
+Latest Version: 0.0.3 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/NatelEnergy/natel-usgs-datasource) in the past 3 years suggests project _may_ not be actively maintained.
+
+### [ntopng](https://grafana.com/grafana/plugins/ntop-ntopng-datasource/)
+
+Latest Version: 1.0.1 | Signature: Community | Last Updated: 2021
+
+> **Migration available - plugin superseded:** this plugin was [discontinued in favour of the InfluxDB data source](https://github.com/ntop/ntopng-grafana-datasource) - a Core plugin included in Grafana, additional guidance is available [here](https://www.ntop.org/guides/ntopng/basic_concepts/timeseries.html#influxdb-driver).
+
+### [Oracle Cloud Infrastructure Logs](https://grafana.com/grafana/plugins/oci-logs-datasource/)
+
+Latest Version: 3.0.0 | Signature: Commercial | Last Updated: 2023
+
+### [Oracle Cloud Infrastructure Metrics](https://grafana.com/grafana/plugins/oci-metrics-datasource/)
+
+Latest Version: 4.0.0 | Signature: Commercial | Last Updated: 2023
+
+### [Warp 10](https://grafana.com/grafana/plugins/ovh-warp10-datasource/)
+
+Latest Version: 2.2.1 | Signature: Community | Last Updated: 2021
+
+> **Warning:** [Project repository](https://github.com/ovh/ovh-warp10-datasource) was archived on March 22nd, 2023 and is no longer maintained.
+
+### [KapacitorSimpleJson](https://grafana.com/grafana/plugins/paytm-kapacitor-datasource/)
+
+Latest Version: 0.1.3 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/paytm/kapacitor-grafana-datasource-plugin) in the past 4 years suggests project _may_ not be actively maintained.
+
+### [Ambari Metrics](https://grafana.com/grafana/plugins/praj-ams-datasource/)
+
+Latest Version: 1.2.1 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/prajwalrao/ambari-metrics-grafana) in the past 5 years suggests project _may_ not be actively maintained.
+
+### [Solr](https://grafana.com/grafana/plugins/pue-solr-datasource/)
+
+Latest Version: 1.0.3 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Unclear progress on migration to React - [issue](https://github.com/pueteam/datasource-plugin-solr/issues/12).
+
+> **Migration available - potential alternative:** Users could configure the solr-exporter for Prometheus as described [here](https://solr.apache.org/guide/solr/latest/deployment-guide/monitoring-with-prometheus-and-grafana.html).
+
+### [QuasarDB](https://grafana.com/grafana/plugins/quasardb-datasource/)
+
+Latest Version: 3.8.3 | Signature: Community | Last Updated: 2021
+
+### [Blueflood](https://grafana.com/grafana/plugins/rackerlabs-blueflood-datasource/)
+
+Latest Version: 0.0.3 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/rax-maas/blueflood-grafana) in the past 7 years suggests project _may_ not be actively maintained.
+
+### [NetXMS](https://grafana.com/grafana/plugins/radensolutions-netxms-datasource/)
+
+Latest Version: 1.2.3 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/netxms/grafana) in the past 2 years suggests project _may_ not be actively maintained.
+
+### [Shoreline Data Source](https://grafana.com/grafana/plugins/shorelinesoftware-shoreline-datasource/)
+
+Latest Version: 1.1.0 | Signature: Commercial | Last Updated: 6 months ago
+
+### [Sidewinder](https://grafana.com/grafana/plugins/sidewinder-datasource/)
+
+Latest Version: 0.2.1 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/srotya/sidewinder-grafana) in the past 5 years suggests project _may_ not be actively maintained.
+
+### [Skydive](https://grafana.com/grafana/plugins/skydive-datasource/)
+
+Latest Version: 1.2.1 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/skydive-project/skydive-grafana-datasource) in the past 4 years suggests project _may_ not be actively maintained.
+
+> **Warning:** Issues suggest the entire project, not just the plugin, may be abandoned - [source](https://github.com/skydive-project/skydive/issues/2417).
+
+### [Heroic](https://grafana.com/grafana/plugins/spotify-heroic-datasource/)
+
+Latest Version: 0.0.2 | Signature: Community | Last Updated: 2021
+
+> **Warning:** [Plugin](https://github.com/spotify/spotify-heroic-datasource) and [Heroic](https://github.com/spotify/heroic) were both archived on April 17th, 2021 and March 27th, 2021 respectively.
+
+### [Heroic](https://grafana.com/grafana/plugins/udoprog-heroic-datasource/)
+
+Latest Version: 0.1.1 | Signature: Community | Last Updated: 2021
+
+> **Warning:** [Plugin](https://github.com/udoprog/udoprog-heroic-datasource) and [Heroic](https://github.com/spotify/heroic) were both archived on October 16th, 2022 and March 27th, 2021 respectively.
+
+### [Altinity plugin for ClickHouse](https://grafana.com/grafana/plugins/vertamedia-clickhouse-datasource/)
+
+Latest Version: 2.5.3 | Signature: Community | Last Updated: 2022
+
+> **Note:** The [migration issue](https://github.com/Altinity/clickhouse-grafana/issues/475) has been assigned to a new major version milestone.
+
+### [Pagerduty](https://grafana.com/grafana/plugins/xginn8-pagerduty-datasource/)
+
+Latest Version: 0.2.2 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/skydive-project/skydive-grafana-datasource) in the past year suggests project _may_ not be actively maintained.
+
+> **Warning:** Plugin only claims support for Grafana v5.
+
+### [Chaos Mesh](https://grafana.com/grafana/plugins/yeya24-chaosmesh-datasource/)
+
+Latest Version: 0.2.3 | Signature: Community | Last Updated: 2022
+
+> **Warning:** Plugin declares itself deprecated in favour of [chaosmeshorg-datasource](https://grafana.com/grafana/plugins/chaosmeshorg-datasource/) which also appears above in this list with warnings around its future.
+
+## Panels
+
+### [FlowCharting](https://grafana.com/grafana/plugins/agenty-flowcharting-panel/)
+
+Latest Version: 0.9.1 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/algenty/grafana-flowcharting) in the past year suggests project _may_ not be actively maintained.
+
+### [HTML](https://grafana.com/grafana/plugins/aidanmountford-html-panel/)
+
+Latest Version: 0.0.2 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/aidanmountford/aidanmountford-html-panel) in the past 4 years suggests project _may_ not be actively maintained.
+
+> **Migration available - potential alternative:** The [Text]({{< relref "../../panels-visualizations/visualizations/text/#html" >}}) panel included with Grafana supports rendering HTML content.
+
+### [Track Map](https://grafana.com/grafana/plugins/alexandra-trackmap-panel/)
+
+Latest Version: 1.2.6 | Signature: Community | Last Updated: 2021
+
+> **Warning:** [Issue](https://github.com/alexandrainst/alexandra-trackmap-panel/issues/72#issuecomment-1332179974) suggests problems with ongoing maintenance unless new contributors are found.
+
+> **Warning:** [Migration issue](https://github.com/alexandrainst/alexandra-trackmap-panel/issues/105) has been marked as needing help.
+
+### [PictureIt](https://grafana.com/grafana/plugins/bessler-pictureit-panel/)
+
+Latest Version: 1.0.1 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/vbessler/grafana-pictureit) in the past 6 years suggests project _may_ not be actively maintained.
+
+> **Migration available - potential alternative:** another plugin exists which provides similar capabilities - [ePict](https://grafana.com/grafana/plugins/larona-epict-panel/).
+
+### [Singlestat Math](https://grafana.com/grafana/plugins/blackmirror1-singlestat-math-panel/)
+
+Latest Version: 1.1.8 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/black-mirror-1/singlestat-math) in the past 5 years suggests project _may_ not be actively maintained.
+
+### [Status By Group Panel](https://grafana.com/grafana/plugins/blackmirror1-statusbygroup-panel/)
+
+Latest Version: 1.1.2 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/black-mirror-1/Grafana_Status_panel) in the past 5 years suggests project _may_ not be actively maintained.
+
+### [Datatable Panel](https://grafana.com/grafana/plugins/briangann-datatable-panel/)
+
+Latest Version: 1.0.3 | Signature: Community | Last Updated: 2021
+
+> **Note:** Migration to react is planned - [issue](https://github.com/briangann/grafana-datatable-panel/issues/174).
+
+### [D3 Gauge](https://grafana.com/grafana/plugins/briangann-gauge-panel/)
+
+Latest Version: 0.0.9 | Signature: Community | Last Updated: 2021
+
+> **Note:** Migration to react is a planned [update](https://github.com/briangann/grafana-gauge-panel/issues/740).
+
+### [GeoLoop](https://grafana.com/grafana/plugins/citilogics-geoloop-panel/)
+
+Latest Version: 1.1.2 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/CitiLogics/citilogics-geoloop-panel) in the past 2 years suggests project _may_ not be actively maintained.
+
+### [Progress List](https://grafana.com/grafana/plugins/corpglory-progresslist-panel/)
+
+Latest Version: 1.0.6 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/CorpGlory/grafana-progress-list) in the past 2 years suggests project _may_ not be actively maintained.
+
+### [Bubble Chart](https://grafana.com/grafana/plugins/digrich-bubblechart-panel/)
+
+Latest Version: 1.2.1 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/digrich/bubblechart-panel) in the past 3 years suggests project _may_ not be actively maintained.
+
+### [Blendstat](https://grafana.com/grafana/plugins/farski-blendstat-panel/)
+
+Latest Version: 1.0.3 | Signature: Community | Last Updated: 2021
+
+> **Migration available - potential alternative:** plugin author recommends use of single stat panel and transformations functionality - [source](https://github.com/farski/blendstat-grafana/issues/11#issuecomment-1112158909).
+
+### [WindRose](https://grafana.com/grafana/plugins/fatcloud-windrose-panel/)
+
+Latest Version: 0.7.1 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/fatcloud/windrose-panel) in the past 4 years suggests project _may_ not be actively maintained.
+
+### [Statusmap](https://grafana.com/grafana/plugins/flant-statusmap-panel/)
+
+Latest Version: 0.5.1 | Signature: Community | Last Updated: 2022
+
+> **Warning:** Unknown whether migration to react will be undertaken - [migration issue](https://github.com/flant/grafana-statusmap/issues/302).
+
+### [Singlestat](https://grafana.com/grafana/plugins/grafana-singlestat-panel/)
+
+Latest Version: 2.0.0 | Signature: Grafana | Last Updated: 2022
+
+> **Migration available - plugin superseded:** Singlestat plugin was replaced by the [Stat]({{< relref "../../panels-visualizations/visualizations/stat/" >}})panel included in Grafana.
+
+### [Worldmap Panel](https://grafana.com/grafana/plugins/grafana-worldmap-panel/)
+
+Latest Version: 1.0.3 | Signature: Grafana | Last Updated: 2023
+
+> **Migration available - plugin superseded:** Worldmap plugin was replaced by [Geomap]({{< relref "../../panels-visualizations/visualizations/geomap/" >}}) panel included in Grafana.
+
+### [Topology Panel](https://grafana.com/grafana/plugins/gretamosa-topology-panel/)
+
+Latest Version: 1.0.1 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/gretamosa/gretamosa-topology-panel) in the past 4 years suggests project _may_ not be actively maintained
+
+### [SVG](https://grafana.com/grafana/plugins/marcuscalidus-svg-panel/)
+
+Latest Version: 0.3.4 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/MarcusCalidus/marcuscalidus-svg-panel) in the past year suggests project _may_ not be actively maintained.
+
+> **Migration available - potential alternative:** another plugin exists which provides similar capabilities - [aceiot-svg-panel](https://grafana.com/grafana/plugins/aceiot-svg-panel/)
+
+### [Annunciator](https://grafana.com/grafana/plugins/michaeldmoore-annunciator-panel/)
+
+Latest Version: 1.1.0 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Plugin developer has indicated they will retire the plugin once Angular support is discontinued - [source](https://github.com/michaeldmoore/michaeldmoore-annunciator-panel/issues/24#issuecomment-1479372673).
+
+### [Multistat](https://grafana.com/grafana/plugins/michaeldmoore-multistat-panel/)
+
+Latest Version: 1.7.2 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Plugin developer has indicated they will retire the plugin once Angular support is discontinued - [source](https://github.com/michaeldmoore/michaeldmoore-multistat-panel/issues/71#issuecomment-1479372977).
+
+### [HeatmapEpoch](https://grafana.com/grafana/plugins/mtanda-heatmap-epoch-panel/)
+
+Latest Version: 0.1.8 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Plugin advises caution as not stable; [project repository](https://github.com/mtanda/grafana-heatmap-epoch-panel) has not been updated in 7 years.
+
+> **Migration available - potential alternative:** Other Heatmap panels exist including natively in Grafana - [learn more]({{< relref "../../panels-visualizations/visualizations/heatmap/" >}}).
+
+### [Histogram](https://grafana.com/grafana/plugins/mtanda-histogram-panel/)
+
+Latest Version: 0.1.7 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/mtanda/grafana-histogram-panel) in the past 7 years suggests project _may_ not be actively maintained
+
+> **Migration available - potential alternative:** other Histogram panels exist including natively in Grafana - [learn more]({{< relref "../../panels-visualizations/visualizations/histogram/" >}}).
+
+### [Separator](https://grafana.com/grafana/plugins/mxswat-separator-panel/)
+
+Latest Version: 1.0.1 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/mxswat/grafana-separator-panel) in the past 5 years suggests project _may_ not be actively maintained
+
+> **Migration available - potential alternative:** the [Text]({{< relref "../../panels-visualizations/visualizations/text/#html" >}}) panel can be used with no data to provide space within dashboards.
+
+### [Discrete](https://grafana.com/grafana/plugins/natel-discrete-panel/)
+
+Latest Version: 0.1.1 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/NatelEnergy/grafana-discrete-panel) in the past 3 years suggests project _may_ not be actively maintained
+
+### [Influx Admin](https://grafana.com/grafana/plugins/natel-influx-admin-panel/)
+
+Latest Version: 0.0.6 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/NatelEnergy/grafana-influx-admin) in the past 5 years suggests project _may_ not be actively maintained.
+
+### [Plotly](https://grafana.com/grafana/plugins/natel-plotly-panel/)
+
+Latest Version: 0.0.7 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/NatelEnergy/grafana-plotly-panel) in the past 2 years suggests project _may_ not be actively maintained.
+
+> **Migration available - potential alternative:** another plugin exists which provides similar capabilities - [nline-plotlyjs-panel/](https://grafana.com/grafana/plugins/nline-plotlyjs-panel/).
+
+### [Cal-HeatMap](https://grafana.com/grafana/plugins/neocat-cal-heatmap-panel/)
+
+Latest Version: 0.0.4 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Plugin advises caution as not stable; [project repository](https://github.com/NeoCat/grafana-cal-heatmap-panel) has not been updated in 7 years.
+
+> **Migration available - potential alternative:** other Heatmap panels exist including natively in Grafana - [learn more]({{< relref "../../panels-visualizations/visualizations/heatmap/" >}}).
+
+### [Annotation Panel](https://grafana.com/grafana/plugins/novalabs-annotations-panel/)
+
+Latest Version: 0.0.2 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/novalabs/grafana-annotations-panel) in the past 6 years suggests project _may_ not be actively maintained.
+
+### [Carpet plot](https://grafana.com/grafana/plugins/petrslavotinek-carpetplot-panel/)
+
+Latest Version: 0.1.2 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/petrslavotinek/grafana-carpetplot) in the past 6 years suggests project _may_ not be actively maintained.
+
+### [TrackMap](https://grafana.com/grafana/plugins/pr0ps-trackmap-panel/)
+
+Latest Version: 2.1.4 | Signature: Community | Last Updated: 2023
+
+> **Warning:** Unknown whether migration to react will be undertaken - [migration issue](https://github.com/pR0Ps/grafana-trackmap-panel/issues/84).
+
+### [AJAX](https://grafana.com/grafana/plugins/ryantxu-ajax-panel/)
+
+Latest Version: 0.1.0 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/ryantxu/ajax-panel) in the past 2 years suggests project _may_ not be actively maintained.
+
+### [Annotation List](https://grafana.com/grafana/plugins/ryantxu-annolist-panel/)
+
+Latest Version: 0.0.2 | Signature: Community | Last Updated: 2021
+
+> **Migration available - plugin superseded:** [Project repository](https://github.com/ryantxu/annotations-panel) for the plugin was archived on July 13th, 2019 in favour of native [annotations]({{< relref "../../panels-visualizations/visualizations/annotations/" >}}).
+
+### [3D Globe Panel](https://grafana.com/grafana/plugins/satellogic-3d-globe-panel/)
+
+Latest Version: 0.1.1 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/satellogic/grafana-3d-globe-panel) in the past 5 years suggests project _may_ not be actively maintained.
+
+### [Heatmap](https://grafana.com/grafana/plugins/savantly-heatmap-panel/)
+
+Latest Version: 0.2.1 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/savantly-net/grafana-heatmap) in the past 6 years suggests project _may_ not be actively maintained.
+
+> **Migration available - potential alternative:** other Heatmap panels exist including natively in Grafana - [learn more]({{< relref "../../panels-visualizations/visualizations/heatmap/" >}}).
+
+### [SCADAvis Synoptic Panel](https://grafana.com/grafana/plugins/scadavis-synoptic-panel/)
+
+Latest Version: 1.0.5 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/riclolsen/scadavis-synoptic-panel) in the past 3 years suggests project _may_ not be actively maintained.
+
+### [TrafficLight](https://grafana.com/grafana/plugins/smartmakers-trafficlight-panel/)
+
+Latest Version: 1.0.1 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/smartmakers/grafana-trafficlight) in the past 5 years suggests project _may_ not be actively maintained.
+
+### [Radar Graph](https://grafana.com/grafana/plugins/snuids-radar-panel/)
+
+Latest Version: 1.5.1 | Signature: Community | Last Updated: 2022
+
+> **Warning:** Unknown whether migration to react will be undertaken - [migration issue](https://github.com/snuids/grafana-radar-panel/issues/29).
+
+### [Traffic Lights](https://grafana.com/grafana/plugins/snuids-trafficlights-panel/)
+
+Latest Version: 1.6.0 | Signature: Community | Last Updated: 2023
+
+> **Warning:** Unknown whether migration to react will be undertaken - [migration issue](https://github.com/snuids/trafficlights-panel/issues/44).
+
+### [Status Panel](https://grafana.com/grafana/plugins/vonage-status-panel/)
+
+Latest Version: 1.0.11 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/Vonage/Grafana_Status_panel) in the past 3 years suggests project _may_ not be actively maintained.
+
+### [Boom Table](https://grafana.com/grafana/plugins/yesoreyeram-boomtable-panel/)
+
+Latest Version: 1.4.1 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Lack of recent activity in the [project repository](https://github.com/yesoreyeram/yesoreyeram-boomtable-panel) in the past 3 years suggests project _may_ not be actively maintained.
+
+### [Parity Report](https://grafana.com/grafana/plugins/zuburqan-parity-report-panel/)
+
+Latest Version: 1.2.2 | Signature: Community | Last Updated: 2021
+
+> **Warning:** Unknown whether migration to react will be undertaken - [migration issue](https://github.com/zuburqan/grafana-parity-report/issues/17).

docs/sources/developers/http_api/_index.md

@@ -62,6 +62,6 @@ Grafana Enterprise includes all of the Grafana OSS APIs as well as those that fo
 
 - [Role-based access control API]({{< relref "access_control/" >}})
 - [Data source permissions API]({{< relref "datasource_permissions/" >}})
-- [External group sync API]({{< relref "external_group_sync/" >}})
+- [Team sync API]({{< relref "team_sync/" >}})
 - [License API]({{< relref "licensing/" >}})
 - [Reporting API]({{< relref "reporting/" >}})

docs/sources/developers/http_api/serviceaccount.md

@@ -217,8 +217,168 @@ Content-Type: application/json
 Authorization: Basic YWRtaW46YWRtaW4=
 ```
 
+**Example Response**:
+
+```http
+HTTP/1.1 200
+Content-Type: application/json
+
+```
+
+## Get API key to service account migration status
+
+`GET /api/serviceaccounts/migrationstatus`
+
+**Required permissions**
+
+See note in the [introduction]({{< ref "#service-account-api" >}}) for an explanation.
+
+| Action               | Scope              |
+| -------------------- | ------------------ |
+| serviceaccounts:read | serviceaccounts:\* |
+
+**Example Request**:
+
+```http
+POST /api/serviceaccounts/migrationstatus HTTP/1.1
+Accept: application/json
+Content-Type: application/json
+Authorization: Basic YWRtaW46YWRtaW4=
+```
+
+**Example Response**:
+
+```http
 HTTP/1.1 200
 Content-Type: application/json
+
+```
+
+## Hide the API keys tab
+
+`GET /api/serviceaccounts/hideApiKeys`
+
+**Required permissions**
+
+See note in the [introduction]({{< ref "#service-account-api" >}}) for an explanation.
+
+| Action                | Scope              |
+| --------------------- | ------------------ |
+| serviceaccounts:write | serviceaccounts:\* |
+
+**Example Request**:
+
+```http
+POST /api/serviceaccounts/hideApiKeys HTTP/1.1
+Accept: application/json
+Content-Type: application/json
+Authorization: Basic YWRtaW46YWRtaW4=
+```
+
+**Example Response**:
+
+```http
+HTTP/1.1 200
+Content-Type: application/json
+
+```
+
+## Get service account tokens
+
+`GET /api/serviceaccounts/:id/tokens`
+
+**Required permissions**
+
+See note in the [introduction]({{< ref "#service-account-api" >}}) for an explanation.
+
+| Action               | Scope                 |
+| -------------------- | --------------------- |
+| serviceaccounts:read | serviceaccounts:id:\* |
+
+**Example Request**:
+
+```http
+GET /api/serviceaccounts/2/tokens HTTP/1.1
+Accept: application/json
+Content-Type: application/json
+Authorization: Basic YWRtaW46YWRtaW4=
+```
+
+**Example Response**:
+
+```http
+HTTP/1.1 200
+Content-Type: application/json
+
+```
+
+## Create service account tokens
+
+`POST /api/serviceaccounts/:id/tokens`
+
+**Required permissions**
+
+See note in the [introduction]({{< ref "#service-account-api" >}}) for an explanation.
+
+| Action                | Scope                 |
+| --------------------- | --------------------- |
+| serviceaccounts:write | serviceaccounts:id:\* |
+
+**Example Request**:
+
+```http
+POST /api/serviceaccounts/2/tokens HTTP/1.1
+Accept: application/json
+Content-Type: application/json
+Authorization: Basic YWRtaW46YWRtaW4=
+
+```
+
+**Example Response**:
+
+```http
+HTTP/1.1 200
+Content-Type: application/json
+
+```
+
+## Delete service account tokens
+
+`DELETE /api/serviceaccounts/:id/tokens/:tokenId`
+
+**Required permissions**
+
+See note in the [introduction]({{< ref "#service-account-api" >}}) for an explanation.
+
+| Action                | Scope                 |
+| --------------------- | --------------------- |
+| serviceaccounts:write | serviceaccounts:id:\* |
+
+**Example Request**:
+
+```http
+DELETE /api/serviceaccounts/2/tokens/1 HTTP/1.1
+Accept: application/json
+Content-Type: application/json
+Authorization: Basic YWRtaW46YWRtaW4=
+```
+
+**Example Response**:
+
+```http
+HTTP/1.1 200
+Content-Type: application/json
+
+```
+
+## Revert service account token to API key
+
+`DELETE /api/serviceaccounts/:serviceAccountId/revert/:keyId`
+
+This operation will delete the service account and create a legacy API Key for the given `keyId`.
+
+**Required permissions**
+
 See note in the [introduction]({{< ref "#service-account-api" >}}) for an explanation.
 
 | Action                 | Scope                 |

docs/sources/developers/http_api/team_sync.md

@@ -1,8 +1,9 @@
 ---
 aliases:
   - ../../http_api/external_group_sync/
-canonical: /docs/grafana/latest/developers/http_api/external_group_sync/
-description: Grafana External Group Sync HTTP API
+  - ./external_group_sync/
+canonical: /docs/grafana/latest/developers/http_api/team_sync/
+description: Grafana Team Sync HTTP API
 keywords:
   - grafana
   - http
@@ -13,12 +14,12 @@ keywords:
   - group
   - member
   - enterprise
-title: External Group Sync HTTP API
+title: Team Sync HTTP API
 ---
 
-# External Group Synchronization API
+# Team Sync API
 
-> External Group Synchronization is only available in Grafana Enterprise. Read more about [Grafana Enterprise]({{< relref "/docs/grafana/latest/introduction/grafana-enterprise" >}}).
+> Team Sync is only available in Grafana Enterprise. Read more about [Grafana Enterprise]({{< relref "/docs/grafana/latest/introduction/grafana-enterprise" >}}).
 
 > If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions]({{< relref "/docs/grafana/latest/administration/roles-and-permissions/access-control/custom-role-actions-scopes" >}}) for more information.
 

docs/sources/developers/kinds/composable/bargaugepanelcfg/schema-reference.md

@@ -21,28 +21,16 @@ title: BarGaugePanelCfg kind
 
 It extends [SingleStatBaseOptions](#singlestatbaseoptions).
 
-<<<<<<< HEAD
 | Property        | Type                                            | Required | Default | Description                                                                                                                                   |
 |-----------------|-------------------------------------------------|----------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------|
 | `displayMode`   | string                                          | **Yes**  |         | Enum expressing the possible display modes<br/>for the bar gauge component of Grafana UI<br/>Possible values are: `basic`, `lcd`, `gradient`. |
 | `minVizHeight`  | uint32                                          | **Yes**  | `10`    |                                                                                                                                               |
 | `minVizWidth`   | uint32                                          | **Yes**  | `0`     |                                                                                                                                               |
 | `showUnfilled`  | boolean                                         | **Yes**  | `true`  |                                                                                                                                               |
+| `valueMode`     | string                                          | **Yes**  |         | Allows for the table cell gauge display type to set the gauge mode.<br/>Possible values are: `color`, `text`, `hidden`.                       |
 | `orientation`   | string                                          | No       |         | *(Inherited from [SingleStatBaseOptions](#singlestatbaseoptions))*<br/>TODO docs<br/>Possible values are: `auto`, `vertical`, `horizontal`.   |
 | `reduceOptions` | [ReduceDataOptions](#reducedataoptions)         | No       |         | *(Inherited from [SingleStatBaseOptions](#singlestatbaseoptions))*<br/>TODO docs                                                              |
 | `text`          | [VizTextDisplayOptions](#viztextdisplayoptions) | No       |         | *(Inherited from [SingleStatBaseOptions](#singlestatbaseoptions))*<br/>TODO docs                                                              |
-=======
-| Property        | Type                                            | Required | Description                                                                                                                                   |
-|-----------------|-------------------------------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------|
-| `displayMode`   | string                                          | **Yes**  | Enum expressing the possible display modes<br/>for the bar gauge component of Grafana UI<br/>Possible values are: `basic`, `lcd`, `gradient`. |
-| `minVizHeight`  | uint32                                          | **Yes**  | Default: `10`.                                                                                                                                |
-| `minVizWidth`   | uint32                                          | **Yes**  | Default: `0`.                                                                                                                                 |
-| `showUnfilled`  | boolean                                         | **Yes**  | Default: `true`.                                                                                                                              |
-| `valueMode`     | string                                          | **Yes**  | Allows for the table cell gauge display type to set the gauge mode.<br/>Possible values are: `color`, `text`, `hidden`.                       |
-| `orientation`   | string                                          | No       | *(Inherited from [SingleStatBaseOptions](#singlestatbaseoptions))*<br/>TODO docs<br/>Possible values are: `auto`, `vertical`, `horizontal`.   |
-| `reduceOptions` | [ReduceDataOptions](#reducedataoptions)         | No       | *(Inherited from [SingleStatBaseOptions](#singlestatbaseoptions))*<br/>TODO docs                                                              |
-| `text`          | [VizTextDisplayOptions](#viztextdisplayoptions) | No       | *(Inherited from [SingleStatBaseOptions](#singlestatbaseoptions))*<br/>TODO docs                                                              |
->>>>>>> main
 
 ### ReduceDataOptions
 

docs/sources/developers/kinds/composable/prometheusdataquery/schema-reference.md

@@ -15,18 +15,18 @@ title: PrometheusDataQuery kind
 
 It extends [DataQuery](#dataquery).
 
-| Property     | Type    | Required | Description                                                                                                                                                                                                                                                                                            |
-|--------------|---------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `expr`       | string  | **Yes**  | The actual expression/query that will be evaluated by Prometheus                                                                                                                                                                                                                                       |
-| `refId`      | string  | **Yes**  | *(Inherited from [DataQuery](#dataquery))*<br/>A unique identifier for the query within the list of targets.<br/>In server side expressions, the refId is used as a variable name to identify results.<br/>By default, the UI will assign A->Z; however setting meaningful names may be useful.        |
-| `datasource` |         | No       | *(Inherited from [DataQuery](#dataquery))*<br/>For mixed data sources the selected datasource is on the query level.<br/>For non mixed scenarios this is undefined.<br/>TODO find a better way to do this ^ that's friendly to schema<br/>TODO this shouldn't be unknown but DataSourceRef &#124; null |
-| `editorMode` | string  | No       | Possible values are: `code`, `builder`.                                                                                                                                                                                                                                                                |
-| `exemplar`   | boolean | No       | Execute an additional query to identify interesting raw samples relevant for the given expr                                                                                                                                                                                                            |
-| `format`     | string  | No       | Possible values are: `time_series`, `table`, `heatmap`.                                                                                                                                                                                                                                                |
-| `hide`       | boolean | No       | *(Inherited from [DataQuery](#dataquery))*<br/>true if query is disabled (ie should not be returned to the dashboard)<br/>Note this does not always imply that the query should not be executed since<br/>the results from a hidden query may be used as the input to other queries (SSE etc)          |
-| `instant`    | boolean | No       | Returns only the latest value that Prometheus has scraped for the requested time series                                                                                                                                                                                                                |
-| `queryType`  | string  | No       | *(Inherited from [DataQuery](#dataquery))*<br/>Specify the query flavor<br/>TODO make this required and give it a default                                                                                                                                                                              |
-| `range`      | boolean | No       | Returns a Range vector, comprised of a set of time series containing a range of data points over time for each time series                                                                                                                                                                             |
+| Property     | Type    | Required | Default | Description                                                                                                                                                                                                                                                                                            |
+|--------------|---------|----------|---------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `expr`       | string  | **Yes**  |         | The actual expression/query that will be evaluated by Prometheus                                                                                                                                                                                                                                       |
+| `refId`      | string  | **Yes**  |         | *(Inherited from [DataQuery](#dataquery))*<br/>A unique identifier for the query within the list of targets.<br/>In server side expressions, the refId is used as a variable name to identify results.<br/>By default, the UI will assign A->Z; however setting meaningful names may be useful.        |
+| `datasource` |         | No       |         | *(Inherited from [DataQuery](#dataquery))*<br/>For mixed data sources the selected datasource is on the query level.<br/>For non mixed scenarios this is undefined.<br/>TODO find a better way to do this ^ that's friendly to schema<br/>TODO this shouldn't be unknown but DataSourceRef &#124; null |
+| `editorMode` | string  | No       |         | Possible values are: `code`, `builder`.                                                                                                                                                                                                                                                                |
+| `exemplar`   | boolean | No       |         | Execute an additional query to identify interesting raw samples relevant for the given expr                                                                                                                                                                                                            |
+| `format`     | string  | No       |         | Possible values are: `time_series`, `table`, `heatmap`.                                                                                                                                                                                                                                                |
+| `hide`       | boolean | No       |         | *(Inherited from [DataQuery](#dataquery))*<br/>true if query is disabled (ie should not be returned to the dashboard)<br/>Note this does not always imply that the query should not be executed since<br/>the results from a hidden query may be used as the input to other queries (SSE etc)          |
+| `instant`    | boolean | No       |         | Returns only the latest value that Prometheus has scraped for the requested time series                                                                                                                                                                                                                |
+| `queryType`  | string  | No       |         | *(Inherited from [DataQuery](#dataquery))*<br/>Specify the query flavor<br/>TODO make this required and give it a default                                                                                                                                                                              |
+| `range`      | boolean | No       |         | Returns a Range vector, comprised of a set of time series containing a range of data points over time for each time series                                                                                                                                                                             |
 
 ### DataQuery
 
@@ -34,11 +34,11 @@ These are the common properties available to all queries in all datasources.
 Specific implementations will *extend* this interface, adding the required
 properties for the given context.
 
-| Property     | Type    | Required | Description                                                                                                                                                                                                                                             |
-|--------------|---------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `refId`      | string  | **Yes**  | A unique identifier for the query within the list of targets.<br/>In server side expressions, the refId is used as a variable name to identify results.<br/>By default, the UI will assign A->Z; however setting meaningful names may be useful.        |
-| `datasource` |         | No       | For mixed data sources the selected datasource is on the query level.<br/>For non mixed scenarios this is undefined.<br/>TODO find a better way to do this ^ that's friendly to schema<br/>TODO this shouldn't be unknown but DataSourceRef &#124; null |
-| `hide`       | boolean | No       | true if query is disabled (ie should not be returned to the dashboard)<br/>Note this does not always imply that the query should not be executed since<br/>the results from a hidden query may be used as the input to other queries (SSE etc)          |
-| `queryType`  | string  | No       | Specify the query flavor<br/>TODO make this required and give it a default                                                                                                                                                                              |
+| Property     | Type    | Required | Default | Description                                                                                                                                                                                                                                             |
+|--------------|---------|----------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `refId`      | string  | **Yes**  |         | A unique identifier for the query within the list of targets.<br/>In server side expressions, the refId is used as a variable name to identify results.<br/>By default, the UI will assign A->Z; however setting meaningful names may be useful.        |
+| `datasource` |         | No       |         | For mixed data sources the selected datasource is on the query level.<br/>For non mixed scenarios this is undefined.<br/>TODO find a better way to do this ^ that's friendly to schema<br/>TODO this shouldn't be unknown but DataSourceRef &#124; null |
+| `hide`       | boolean | No       |         | true if query is disabled (ie should not be returned to the dashboard)<br/>Note this does not always imply that the query should not be executed since<br/>the results from a hidden query may be used as the input to other queries (SSE etc)          |
+| `queryType`  | string  | No       |         | Specify the query flavor<br/>TODO make this required and give it a default                                                                                                                                                                              |
 
 

docs/sources/developers/kinds/composable/statpanelcfg/schema-reference.md

@@ -23,7 +23,7 @@ It extends [SingleStatBaseOptions](#singlestatbaseoptions).
 
 | Property        | Type                                            | Required | Default | Description                                                                                                                                 |
 |-----------------|-------------------------------------------------|----------|---------|---------------------------------------------------------------------------------------------------------------------------------------------|
-| `colorMode`     | string                                          | **Yes**  |         | TODO docs<br/>Possible values are: `value`, `background`, `none`.                                                                           |
+| `colorMode`     | string                                          | **Yes**  |         | TODO docs<br/>Possible values are: `value`, `background`, `background_solid`, `none`.                                                       |
 | `graphMode`     | string                                          | **Yes**  |         | TODO docs<br/>Possible values are: `none`, `line`, `area`.                                                                                  |
 | `justifyMode`   | string                                          | **Yes**  |         | TODO docs<br/>Possible values are: `auto`, `center`.                                                                                        |
 | `textMode`      | string                                          | **Yes**  |         | TODO docs<br/>Possible values are: `auto`, `value`, `value_and_name`, `name`, `none`.                                                       |

docs/sources/developers/kinds/composable/tablepanelcfg/schema-reference.md

@@ -19,26 +19,14 @@ title: TablePanelCfg kind
 
 ### PanelOptions
 
-<<<<<<< HEAD
 | Property        | Type                                              | Required | Default                                      | Description                                                        |
 |-----------------|---------------------------------------------------|----------|----------------------------------------------|--------------------------------------------------------------------|
 | `frameIndex`    | number                                            | **Yes**  | `0`                                          | Represents the index of the selected frame                         |
 | `showHeader`    | boolean                                           | **Yes**  | `true`                                       | Controls whether the panel should show the header                  |
+| `cellHeight`    | string                                            | No       |                                              | Height of a table cell<br/>Possible values are: `sm`, `md`, `lg`.  |
 | `footer`        | [object](#footer)                                 | No       | `map[countRows:false reducer:[] show:false]` | Controls footer options                                            |
-| `showRowNums`   | boolean                                           | No       | `false`                                      | Controls whether the columns should be numbered                    |
 | `showTypeIcons` | boolean                                           | No       | `false`                                      | Controls whether the header should show icons for the column types |
 | `sortBy`        | [TableSortByFieldState](#tablesortbyfieldstate)[] | No       |                                              | Used to control row sorting                                        |
-=======
-| Property        | Type                                              | Required | Description                                                                          |
-|-----------------|---------------------------------------------------|----------|--------------------------------------------------------------------------------------|
-| `frameIndex`    | number                                            | **Yes**  | Represents the index of the selected frame Default: `0`.                             |
-| `showHeader`    | boolean                                           | **Yes**  | Controls whether the panel should show the header Default: `true`.                   |
-| `cellHeight`    | string                                            | No       | Height of a table cell<br/>Possible values are: `sm`, `md`, `lg`.                    |
-| `footer`        | [object](#footer)                                 | No       | Controls footer options Default: `map[countRows:false reducer:[] show:false]`.       |
-| `showRowNums`   | boolean                                           | No       | Controls whether the columns should be numbered Default: `false`.                    |
-| `showTypeIcons` | boolean                                           | No       | Controls whether the header should show icons for the column types Default: `false`. |
-| `sortBy`        | [TableSortByFieldState](#tablesortbyfieldstate)[] | No       | Used to control row sorting                                                          |
->>>>>>> main
 
 ### TableSortByFieldState
 

docs/sources/developers/kinds/composable/timeseriespanelcfg/schema-reference.md

@@ -0,0 +1,224 @@
+---
+keywords:
+  - grafana
+  - schema
+title: TimeSeriesPanelCfg kind
+---
+> Both documentation generation and kinds schemas are in active development and subject to change without prior notice.
+
+## TimeSeriesPanelCfg
+
+#### Maturity: [merged](../../../maturity/#merged)
+#### Version: 0.0
+
+
+
+| Property           | Type                                  | Required | Default | Description |
+|--------------------|---------------------------------------|----------|---------|-------------|
+| `PanelFieldConfig` | [GraphFieldConfig](#graphfieldconfig) | **Yes**  |         | TODO docs   |
+| `PanelOptions`     | [object](#paneloptions)               | **Yes**  |         |             |
+
+### GraphFieldConfig
+
+TODO docs
+
+It extends [LineConfig](#lineconfig) and [FillConfig](#fillconfig) and [PointsConfig](#pointsconfig) and [AxisConfig](#axisconfig) and [BarConfig](#barconfig) and [StackableFieldConfig](#stackablefieldconfig) and [HideableFieldConfig](#hideablefieldconfig).
+
+| Property            | Type                                                      | Required | Default | Description                                                                                                                                                                                                                                                                   |
+|---------------------|-----------------------------------------------------------|----------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `axisCenteredZero`  | boolean                                                   | No       |         | *(Inherited from [AxisConfig](#axisconfig))*                                                                                                                                                                                                                                  |
+| `axisColorMode`     | string                                                    | No       |         | *(Inherited from [AxisConfig](#axisconfig))*<br/>TODO docs<br/>Possible values are: `text`, `series`.                                                                                                                                                                         |
+| `axisGridShow`      | boolean                                                   | No       |         | *(Inherited from [AxisConfig](#axisconfig))*                                                                                                                                                                                                                                  |
+| `axisLabel`         | string                                                    | No       |         | *(Inherited from [AxisConfig](#axisconfig))*                                                                                                                                                                                                                                  |
+| `axisPlacement`     | string                                                    | No       |         | *(Inherited from [AxisConfig](#axisconfig))*<br/>TODO docs<br/>Possible values are: `auto`, `top`, `right`, `bottom`, `left`, `hidden`.                                                                                                                                       |
+| `axisSoftMax`       | number                                                    | No       |         | *(Inherited from [AxisConfig](#axisconfig))*                                                                                                                                                                                                                                  |
+| `axisSoftMin`       | number                                                    | No       |         | *(Inherited from [AxisConfig](#axisconfig))*                                                                                                                                                                                                                                  |
+| `axisWidth`         | number                                                    | No       |         | *(Inherited from [AxisConfig](#axisconfig))*                                                                                                                                                                                                                                  |
+| `barAlignment`      | integer                                                   | No       |         | *(Inherited from [BarConfig](#barconfig))*<br/>TODO docs<br/>Possible values are: `-1`, `0`, `1`.                                                                                                                                                                             |
+| `barMaxWidth`       | number                                                    | No       |         | *(Inherited from [BarConfig](#barconfig))*                                                                                                                                                                                                                                    |
+| `barWidthFactor`    | number                                                    | No       |         | *(Inherited from [BarConfig](#barconfig))*                                                                                                                                                                                                                                    |
+| `drawStyle`         | string                                                    | No       |         | TODO docs<br/>Possible values are: `line`, `bars`, `points`.                                                                                                                                                                                                                  |
+| `fillBelowTo`       | string                                                    | No       |         | *(Inherited from [FillConfig](#fillconfig))*                                                                                                                                                                                                                                  |
+| `fillColor`         | string                                                    | No       |         | *(Inherited from [FillConfig](#fillconfig))*                                                                                                                                                                                                                                  |
+| `fillOpacity`       | number                                                    | No       |         | *(Inherited from [FillConfig](#fillconfig))*                                                                                                                                                                                                                                  |
+| `gradientMode`      | string                                                    | No       |         | TODO docs<br/>Possible values are: `none`, `opacity`, `hue`, `scheme`.                                                                                                                                                                                                        |
+| `hideFrom`          | [HideSeriesConfig](#hideseriesconfig)                     | No       |         | *(Inherited from [HideableFieldConfig](#hideablefieldconfig))*<br/>TODO docs                                                                                                                                                                                                  |
+| `lineColor`         | string                                                    | No       |         | *(Inherited from [LineConfig](#lineconfig))*                                                                                                                                                                                                                                  |
+| `lineInterpolation` | string                                                    | No       |         | *(Inherited from [LineConfig](#lineconfig))*<br/>TODO docs<br/>Possible values are: `linear`, `smooth`, `stepBefore`, `stepAfter`.                                                                                                                                            |
+| `lineStyle`         | [LineStyle](#linestyle)                                   | No       |         | *(Inherited from [LineConfig](#lineconfig))*<br/>TODO docs                                                                                                                                                                                                                    |
+| `lineWidth`         | number                                                    | No       |         | *(Inherited from [LineConfig](#lineconfig))*                                                                                                                                                                                                                                  |
+| `pointColor`        | string                                                    | No       |         | *(Inherited from [PointsConfig](#pointsconfig))*                                                                                                                                                                                                                              |
+| `pointSize`         | number                                                    | No       |         | *(Inherited from [PointsConfig](#pointsconfig))*                                                                                                                                                                                                                              |
+| `pointSymbol`       | string                                                    | No       |         | *(Inherited from [PointsConfig](#pointsconfig))*                                                                                                                                                                                                                              |
+| `scaleDistribution` | [ScaleDistributionConfig](#scaledistributionconfig)       | No       |         | *(Inherited from [AxisConfig](#axisconfig))*<br/>TODO docs                                                                                                                                                                                                                    |
+| `showPoints`        | string                                                    | No       |         | *(Inherited from [PointsConfig](#pointsconfig))*<br/>TODO docs<br/>Possible values are: `auto`, `never`, `always`.                                                                                                                                                            |
+| `spanNulls`         |                                                           | No       |         | *(Inherited from [LineConfig](#lineconfig))*<br/>Indicate if null values should be treated as gaps or connected.<br/>When the value is a number, it represents the maximum delta in the<br/>X axis that should be considered connected.  For timeseries, this is milliseconds |
+| `stacking`          | [StackingConfig](#stackingconfig)                         | No       |         | *(Inherited from [StackableFieldConfig](#stackablefieldconfig))*<br/>TODO docs                                                                                                                                                                                                |
+| `thresholdsStyle`   | [GraphThresholdsStyleConfig](#graphthresholdsstyleconfig) | No       |         | TODO docs                                                                                                                                                                                                                                                                     |
+| `transform`         | string                                                    | No       |         | TODO docs<br/>Possible values are: `constant`, `negative-Y`.                                                                                                                                                                                                                  |
+
+### AxisConfig
+
+TODO docs
+
+| Property            | Type                                                | Required | Default | Description                                                                            |
+|---------------------|-----------------------------------------------------|----------|---------|----------------------------------------------------------------------------------------|
+| `axisCenteredZero`  | boolean                                             | No       |         |                                                                                        |
+| `axisColorMode`     | string                                              | No       |         | TODO docs<br/>Possible values are: `text`, `series`.                                   |
+| `axisGridShow`      | boolean                                             | No       |         |                                                                                        |
+| `axisLabel`         | string                                              | No       |         |                                                                                        |
+| `axisPlacement`     | string                                              | No       |         | TODO docs<br/>Possible values are: `auto`, `top`, `right`, `bottom`, `left`, `hidden`. |
+| `axisSoftMax`       | number                                              | No       |         |                                                                                        |
+| `axisSoftMin`       | number                                              | No       |         |                                                                                        |
+| `axisWidth`         | number                                              | No       |         |                                                                                        |
+| `scaleDistribution` | [ScaleDistributionConfig](#scaledistributionconfig) | No       |         | TODO docs                                                                              |
+
+### ScaleDistributionConfig
+
+TODO docs
+
+| Property          | Type   | Required | Default | Description                                                              |
+|-------------------|--------|----------|---------|--------------------------------------------------------------------------|
+| `type`            | string | **Yes**  |         | TODO docs<br/>Possible values are: `linear`, `log`, `ordinal`, `symlog`. |
+| `linearThreshold` | number | No       |         |                                                                          |
+| `log`             | number | No       |         |                                                                          |
+
+### BarConfig
+
+TODO docs
+
+| Property         | Type    | Required | Default | Description                                        |
+|------------------|---------|----------|---------|----------------------------------------------------|
+| `barAlignment`   | integer | No       |         | TODO docs<br/>Possible values are: `-1`, `0`, `1`. |
+| `barMaxWidth`    | number  | No       |         |                                                    |
+| `barWidthFactor` | number  | No       |         |                                                    |
+
+### FillConfig
+
+TODO docs
+
+| Property      | Type   | Required | Default | Description |
+|---------------|--------|----------|---------|-------------|
+| `fillBelowTo` | string | No       |         |             |
+| `fillColor`   | string | No       |         |             |
+| `fillOpacity` | number | No       |         |             |
+
+### GraphThresholdsStyleConfig
+
+TODO docs
+
+| Property | Type   | Required | Default | Description                                                                                               |
+|----------|--------|----------|---------|-----------------------------------------------------------------------------------------------------------|
+| `mode`   | string | **Yes**  |         | TODO docs<br/>Possible values are: `off`, `line`, `dashed`, `area`, `line+area`, `dashed+area`, `series`. |
+
+### HideSeriesConfig
+
+TODO docs
+
+| Property  | Type    | Required | Default | Description |
+|-----------|---------|----------|---------|-------------|
+| `legend`  | boolean | **Yes**  |         |             |
+| `tooltip` | boolean | **Yes**  |         |             |
+| `viz`     | boolean | **Yes**  |         |             |
+
+### HideableFieldConfig
+
+TODO docs
+
+| Property   | Type                                  | Required | Default | Description |
+|------------|---------------------------------------|----------|---------|-------------|
+| `hideFrom` | [HideSeriesConfig](#hideseriesconfig) | No       |         | TODO docs   |
+
+### LineConfig
+
+TODO docs
+
+| Property            | Type                    | Required | Default | Description                                                                                                                                                                                                                  |
+|---------------------|-------------------------|----------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `lineColor`         | string                  | No       |         |                                                                                                                                                                                                                              |
+| `lineInterpolation` | string                  | No       |         | TODO docs<br/>Possible values are: `linear`, `smooth`, `stepBefore`, `stepAfter`.                                                                                                                                            |
+| `lineStyle`         | [LineStyle](#linestyle) | No       |         | TODO docs                                                                                                                                                                                                                    |
+| `lineWidth`         | number                  | No       |         |                                                                                                                                                                                                                              |
+| `spanNulls`         |                         | No       |         | Indicate if null values should be treated as gaps or connected.<br/>When the value is a number, it represents the maximum delta in the<br/>X axis that should be considered connected.  For timeseries, this is milliseconds |
+
+### LineStyle
+
+TODO docs
+
+| Property | Type     | Required | Default | Description                                            |
+|----------|----------|----------|---------|--------------------------------------------------------|
+| `dash`   | number[] | No       |         |                                                        |
+| `fill`   | string   | No       |         | Possible values are: `solid`, `dash`, `dot`, `square`. |
+
+### PointsConfig
+
+TODO docs
+
+| Property      | Type   | Required | Default | Description                                                   |
+|---------------|--------|----------|---------|---------------------------------------------------------------|
+| `pointColor`  | string | No       |         |                                                               |
+| `pointSize`   | number | No       |         |                                                               |
+| `pointSymbol` | string | No       |         |                                                               |
+| `showPoints`  | string | No       |         | TODO docs<br/>Possible values are: `auto`, `never`, `always`. |
+
+### StackableFieldConfig
+
+TODO docs
+
+| Property   | Type                              | Required | Default | Description |
+|------------|-----------------------------------|----------|---------|-------------|
+| `stacking` | [StackingConfig](#stackingconfig) | No       |         | TODO docs   |
+
+### StackingConfig
+
+TODO docs
+
+| Property | Type   | Required | Default | Description                                                     |
+|----------|--------|----------|---------|-----------------------------------------------------------------|
+| `group`  | string | No       |         |                                                                 |
+| `mode`   | string | No       |         | TODO docs<br/>Possible values are: `none`, `normal`, `percent`. |
+
+### PanelOptions
+
+It extends [OptionsWithTimezones](#optionswithtimezones).
+
+| Property   | Type                                    | Required | Default | Description                                                      |
+|------------|-----------------------------------------|----------|---------|------------------------------------------------------------------|
+| `legend`   | [VizLegendOptions](#vizlegendoptions)   | **Yes**  |         | TODO docs                                                        |
+| `tooltip`  | [VizTooltipOptions](#viztooltipoptions) | **Yes**  |         | TODO docs                                                        |
+| `timezone` | string[]                                | No       |         | *(Inherited from [OptionsWithTimezones](#optionswithtimezones))* |
+
+### OptionsWithTimezones
+
+TODO docs
+
+| Property   | Type     | Required | Default | Description |
+|------------|----------|----------|---------|-------------|
+| `timezone` | string[] | No       |         |             |
+
+### VizLegendOptions
+
+TODO docs
+
+| Property      | Type     | Required | Default | Description                                                                                                                             |
+|---------------|----------|----------|---------|-----------------------------------------------------------------------------------------------------------------------------------------|
+| `calcs`       | string[] | **Yes**  |         |                                                                                                                                         |
+| `displayMode` | string   | **Yes**  |         | TODO docs<br/>Note: "hidden" needs to remain as an option for plugins compatibility<br/>Possible values are: `list`, `table`, `hidden`. |
+| `placement`   | string   | **Yes**  |         | TODO docs<br/>Possible values are: `bottom`, `right`.                                                                                   |
+| `showLegend`  | boolean  | **Yes**  |         |                                                                                                                                         |
+| `asTable`     | boolean  | No       |         |                                                                                                                                         |
+| `isVisible`   | boolean  | No       |         |                                                                                                                                         |
+| `sortBy`      | string   | No       |         |                                                                                                                                         |
+| `sortDesc`    | boolean  | No       |         |                                                                                                                                         |
+| `width`       | number   | No       |         |                                                                                                                                         |
+
+### VizTooltipOptions
+
+TODO docs
+
+| Property | Type   | Required | Default | Description                                                   |
+|----------|--------|----------|---------|---------------------------------------------------------------|
+| `mode`   | string | **Yes**  |         | TODO docs<br/>Possible values are: `single`, `multi`, `none`. |
+| `sort`   | string | **Yes**  |         | TODO docs<br/>Possible values are: `asc`, `desc`, `none`.     |
+
+

docs/sources/developers/plugins/_index.md

@@ -2,81 +2,51 @@
 aliases:
   - ../plugins/developing/
 description: Resources for creating Grafana plugins
-title: Build a plugin
+title: Plugin developer's guide
 weight: 200
 ---
 
-# Build a plugin
+# Grafana plugin developer's guide
 
-For more information on the types of plugins you can build, refer to the [Plugin Overview]({{< relref "../../administration/plugin-management/" >}}).
+You can extend Grafana's built-in capabilities with plugins. Plugins enable Grafana to accomplish specialized tasks, custom-tailored to your requirements. By making a plugin for your organization, you can connect Grafana to other data sources, ticketing tools, and CI/CD tooling.
 
-## Get started
+You can create plugins for private use or contribute them to the open source community by publishing to the [Grafana plugin catalog](https://grafana.com/grafana/plugins/). This catalog has hundreds of other community and commercial plugins.
 
-The easiest way to start developing Grafana plugins is to use the Grafana [create-plugin tool](https://www.npmjs.com/package/@grafana/create-plugin).
+If you are a Grafana plugin developer or want to become one, this plugin developer's guide contains the tutorials and reference materials to help you get started.
 
-Open the terminal, and run the following command in your [plugin directory]({{< relref "../../setup-grafana/configure-grafana/#plugins" >}}):
+## Plugin basics
 
-```bash
-npx @grafana/create-plugin@latest
-```
+You can create several types of plugins, including:
 
-Follow the questions and you will have a starter plugin ready to develop.
+- **Panel plugins** - Visualize data and navigate between dashboards.
+- **Data source plugins** - Link to new databases or other sources of data.
+- **App plugins** - Create rich applications for custom out-of-the-box experiences.
 
-If you want a more guided introduction to plugin development, check out our tutorials:
+> **Note:** To learn more about the types of plugins you can build, refer to the [Plugin management]({{< relref "../../administration/plugin-management" >}}) documentation.
 
-- [Build a panel plugin](/tutorials/build-a-panel-plugin/)
-- [Build a data source plugin](/tutorials/build-a-data-source-plugin/)
+## Contents of this developer's guide
+
+The following topics are covered in this guide:
+
+- **[Get started with plugins]({{< relref "./get-started-with-plugins" >}})** - Start developing Grafana plugins with the [Create-plugin](https://www.npmjs.com/package/@grafana/create-plugin) tool.
+- **[Introduction to plugin development]({{< relref "./introduction-to-plugin-development" >}})** - Learn the fundamentals of Grafana plugin development: frontend and backend development processes, data frames, error handling, and more.
+- **[Create a Grafana plugin]({{< relref "./create-a-grafana-plugin" >}})** - If you're familiar with plugin creation, use the tutorials for creating panel plugins, data source plugins, and more to deepen your knowledge.
+- **[Migrate a plugin]({{< relref "./migration-guide" >}})** - Learn how to upgrade from a previous version of a Grafana plugin, rewrite an old Angular plugin in React, or update to a newer version.
+- **[Publish a Grafana plugin]({{< relref "./publish-a-plugin" >}})** - Learn about publishing a plugin to the Grafana plugin catalog, including publishing criteria, packaging, and deployment.
+- **[Reference]({{< relref "metadata.md" >}})** - Description of the `plugin.json` schema and plugin metadata.
 
 ## Go further
 
-Learn more about specific areas of plugin development.
+Learn more about additional tools and see plugin type examples.
 
-### Tutorials
-
-If you're looking to build your first plugin, check out these introductory tutorials:
-
-- [Build a panel plugin](/tutorials/build-a-panel-plugin/)
-- [Build a data source plugin](/tutorials/build-a-data-source-plugin/)
-- [Build a data source backend plugin](/tutorials/build-a-data-source-backend-plugin/)
-
-Ready to learn more? Check out our other tutorials:
-
-- [Build a panel plugin with D3.js](/tutorials/build-a-panel-plugin-with-d3/)
-
-### Guides
-
-Improve an existing plugin with one of our guides:
-
-- [Add authentication for data source plugins]({{< relref "add-authentication-for-data-source-plugins.md" >}})
-- [Add support for annotations]({{< relref "add-support-for-annotations.md" >}})
-- [Add support for Explore queries]({{< relref "add-support-for-explore-queries.md" >}})
-- [Add support for variables]({{< relref "add-support-for-variables.md" >}})
-- [Add a query editor help component]({{< relref "add-query-editor-help.md" >}})
-- [Add distributed tracing for backend plugins]({{< relref "add-distributed-tracing-for-backend-plugins.md" >}})
-- [Build a logs data source plugin]({{< relref "build-a-logs-data-source-plugin.md" >}})
-- [Build a streaming data source plugin]({{< relref "build-a-streaming-data-source-plugin.md" >}}/)
-- [Error handling]({{< relref "error-handling.md" >}})
-- [Working with data frames]({{< relref "working-with-data-frames.md" >}})
-- [Development with local Grafana]({{< relref "development-with-local-grafana.md" >}})
-
-### Concepts
-
-Deepen your knowledge through a series of high-level overviews of plugin concepts:
-
-- [Data frames]({{< relref "data-frames.md" >}})
-
-### UI library
+### User interface creation
 
 Explore the many UI components in our [Grafana UI library](https://developers.grafana.com/ui).
 
-### Examples
+### Plugin examples
 
-For inspiration, check out our [plugin examples](https://github.com/grafana/grafana-plugin-examples).
-
-### Metadata
-
-- [Plugin metadata]({{< relref "metadata.md" >}})
+Grafana Labs provides a number of best practice example plugins for different use cases to help you quickly get started. Browse our [plugin examples](https://github.com/grafana/grafana-plugin-examples).
 
 ### SDK
 
-- [Grafana Plugin SDK for Go]({{< relref "backend/grafana-plugin-sdk-for-go.md" >}})
+Learn more about [Grafana Plugin SDK for Go]({{< relref "./backend/grafana-plugin-sdk-for-go" >}}).

docs/sources/developers/plugins/add-anonymous-usage-reporting.md

@@ -2,13 +2,17 @@
 title: Add anonymous usage reporting
 ---
 
-# Add anonymous usage reporting to you plugin
+# Add anonymous usage reporting
 
-The Grafana server administrator has the possibility to configure [anonymous usage tracking]({{< relref "../../setup-grafana/configure-grafana/#reporting_enabled" >}}).
+Add anonymous usage tracking to your plugin to send [reporting events]({{< relref "../../setup-grafana/configure-grafana/#reporting_enabled" >}}) that describe how your plugin is being used to a tracking system configured by your Grafana server administrator.
 
-By adding usage tracking to your plugin you will send events of how your plugin is being used to the configured tracking system.
+## Event reporting
 
-Lets say we have a QueryEditor that looks something like the example below. It has an editor field where you can write your query and a query type selector so you can select what kind of query result you are expecting that query to return.
+In this section, we show an example of tracking usage data from a query editor and receiving a report back from the analytics service.
+
+### Sample query editor
+
+Let's say you have a `QueryEditor` that looks similar to the example below. It has a `CodeEditor` field where you can write your query and a query type selector so you can select the kind of query result that you expect to return:
 
 ```ts
 import React, { ReactElement } from 'react';
@@ -17,11 +21,11 @@ import type { EditorProps } from './types';
 
 export function QueryEditor(props: EditorProps): ReactElement {
   const { datasource, query, onChange, onRunQuery } = props;
-  const queryType = { value: query.value ?? 'timeserie' };
+  const queryType = { value: query.value ?? 'timeseries' };
   const queryTypes = [
     {
-      label: 'Timeserie',
-      value: 'timeserie',
+      label: 'Timeseries',
+      value: 'timeseries',
     },
     {
       label: 'Table',
@@ -66,7 +70,14 @@ export function QueryEditor(props: EditorProps): ReactElement {
 }
 ```
 
-Lets say that we would like to track how the usage looks between time series and table queries. All you need to do is to add the `usePluginInteractionReporter` to fetch a report function which takes two arguments. The first one is the event name which is used to identify the interaction being made. It need to start with `grafana_plugin_` which makes it easier to differentiate plugin events from Grafana core events. The second argument is optional and should be used to attach contextual data to the event. In our example, that would be the query type. It is optional because it does not make sense to pass contextual data for all user interactions.
+### Track usage with `usePluginInteractionReporter`
+
+Let's say that you want to track how the usage looks between time series and table queries.
+
+What you want to do is to add the `usePluginInteractionReporter` to fetch a report function that takes two arguments:
+
+- Required: An event name that begins with `grafana_plugin_`. It is used to identify the interaction being made.
+- Optional: Attached contextual data. In our example, that is the query type.
 
 ```ts
 import React, { ReactElement } from 'react';
@@ -78,11 +89,11 @@ export function QueryEditor(props: EditorProps): ReactElement {
   const { datasource, query, onChange, onRunQuery } = props;
   const report = usePluginInteractionReporter();
 
-  const queryType = { value: query.value ?? 'timeserie' };
+  const queryType = { value: query.value ?? 'timeseries' };
   const queryTypes = [
     {
-      label: 'Timeserie',
-      value: 'timeserie',
+      label: 'Timeseries',
+      value: 'timeseries',
     },
     {
       label: 'Table',
@@ -132,7 +143,11 @@ export function QueryEditor(props: EditorProps): ReactElement {
 }
 ```
 
-Another benefit of using the `usePluginInteractionReporter` is that the report function that is handed back to you will automatically attach contextual data about the plugin you are tracking to every event. In our example the following information will be sent to the analytics service configured by the Grafana server administrator.
+### Data returned from the analytics service
+
+When you use `usePluginInteractionReporter`, the report function that is handed back to you automatically attaches contextual data about the plugin you are tracking to the events.
+
+In our example, the following information is sent to the analytics service configured by the Grafana server administrator:
 
 ```ts
 {
@@ -145,7 +160,7 @@ Another benefit of using the `usePluginInteractionReporter` is that the report f
     plugin_id: 'grafana-example-datasource',
     plugin_name: 'Example',
     datasource_uid: 'qeSI8VV7z', // will only be added for datasources
-    query_type: 'timeserie'
+    query_type: 'timeseries'
   }
 }
 ```

docs/sources/developers/plugins/add-authentication-for-data-source-plugins.md

@@ -7,112 +7,121 @@ title: Add authentication for data source plugins
 
 # Add authentication for data source plugins
 
-This page explains how to configure your data source plugin to authenticate against a third-party API.
+Grafana plugins can perform authenticated requests against a third-party API by using the _data source proxy_ or through a custom a _backend plugin_.
 
-There are two ways you can perform authenticated requests from your plugin—using the [_data source proxy_](#authenticate-using-the-data-source-proxy), or by building a [_backend plugin_](#authenticate-using-a-backend-plugin). The one you choose depends on how your plugin authenticates against the third-party API.
+## Choose an authentication method
 
-- Use the data source proxy if you need to authenticate using Basic Auth or API keys
-- Use the data source proxy if the API supports OAuth 2.0 using client credentials
-- Use a backend plugin if the API uses a custom authentication method that isn't supported by the data source proxy, or if your API communicates over a different protocol than HTTP
+Configure your data source plugin to authenticate against a third-party API in one of either of two ways:
 
-Regardless of which approach you use, you first need to encrypt any sensitive information that the plugin needs to store.
+- Use the [_data source proxy_](#authenticate-using-the-data-source-proxy) method, or
+- Build a [_backend plugin_](#authenticate-using-a-backend-plugin).
+
+| Case                                                                                            | Use                             |
+| ----------------------------------------------------------------------------------------------- | ------------------------------- |
+| Do you need to authenticate your plugin using Basic Auth or API keys?                           | Use the data source proxy.      |
+| Does your API support OAuth 2.0 using client credentials?                                       | Use the data source proxy.      |
+| Does your API use a custom authentication method that isn't supported by the data source proxy? | Use a backend plugin.           |
+| Does your API communicate over a protocol other than HTTP?                                      | Build and use a backend plugin. |
+| Does your plugin require alerting support?                                                      | Build and use a backend plugin. |
 
 ## Encrypt data source configuration
 
 Data source plugins have two ways of storing custom configuration: `jsonData` and `secureJsonData`.
 
-Users with the _Viewer_ role can access data source configuration—such as the contents of `jsonData`—in cleartext. If you've enabled anonymous access, anyone that can access Grafana in their browser can see the contents of `jsonData`. **Only use `jsonData` to store non-sensitive configuration.**
+Users with the Viewer role can access data source configuration such as the contents of `jsonData` in cleartext. If you've enabled anonymous access, anyone who can access Grafana in their browser can see the contents of `jsonData`.
+
+Users of [Grafana Enterprise](https://grafana.com/products/enterprise/grafana/) can restrict access to data sources to specific users and teams. For more information, refer to [Data source permissions](https://grafana.com/docs/grafana/latest/enterprise/datasource_permissions).
+
+> **Important:** Do not use `jsonData` with sensitive data such as password, tokens, and API keys. If you need to store sensitive information, use `secureJsonData` instead.
 
 > **Note:** You can see the settings that the current user has access to by entering `window.grafanaBootData` in the developer console of your browser.
 
-> **Note:** Users of [Grafana Enterprise](https://grafana.com/products/enterprise/grafana/) can restrict access to data sources to specific users and teams. For more information, refer to [Data source permissions](https://grafana.com/docs/grafana/latest/enterprise/datasource_permissions).
+### Store configuration in `secureJsonData`
 
-If you need to store sensitive information, such as passwords, tokens and API keys, use `secureJsonData` instead. Whenever the user saves the data source configuration, the secrets in `secureJsonData` are sent to the Grafana server and encrypted before they're stored.
+If you need to store sensitive information, use `secureJsonData` instead of `jsonData`. Whenever the user saves the data source configuration, the secrets in `secureJsonData` are sent to the Grafana server and encrypted before they're stored.
 
-Once the secure configuration has been encrypted, it can no longer be accessed from the browser. The only way to access secrets after they've been saved is by using the [_data source proxy_](#authenticate-using-the-data-source-proxy).
+Once you have encrypted the secure configuration, it can no longer be accessed from the browser. The only way to access secrets after they've been saved is by using the [_data source proxy_](#authenticate-using-the-data-source-proxy).
 
-#### Add secret configuration to your data source plugin
+### Add secret configuration to your data source plugin
 
 To demonstrate how you can add secrets to a data source plugin, let's add support for configuring an API key.
 
-Create a new interface in `types.ts` to hold the API key.
+1. Create a new interface in `types.ts` to hold the API key:
+   ```ts
+   export interface MySecureJsonData {
+     apiKey?: string;
+   }
+   ```
+1. Add type information to your `secureJsonData` object by updating the props for your `ConfigEditor` to accept the interface as a second type parameter. Access the value of the secret from the `options` prop inside your `ConfigEditor`:
 
-```ts
-export interface MySecureJsonData {
-  apiKey?: string;
-}
-```
+   ```ts
+   interface Props extends DataSourcePluginOptionsEditorProps<MyDataSourceOptions, MySecureJsonData> {}
+   ```
 
-Add type information to your `secureJsonData` object by updating the props for your `ConfigEditor` to accept the interface as a second type parameter.
+   ```ts
+   const { secureJsonData, secureJsonFields } = options;
+   const { apiKey } = secureJsonData;
+   ```
 
-```ts
-interface Props extends DataSourcePluginOptionsEditorProps<MyDataSourceOptions, MySecureJsonData> {}
-```
+   > **Note:** You can do this until the user saves the configuration; when the user saves the configuration, Grafana clears the value. After that, you can use `secureJsonFields` to determine whether the property has been configured.
 
-You can access the value of the secret from the `options` prop inside your `ConfigEditor` until the user saves the configuration. When the user saves the configuration, Grafana clears the value. After that, you can use the `secureJsonFields` to determine whether the property has been configured.
+1. To securely update the secret in your plugin's configuration editor, update the `secureJsonData` object using the `onOptionsChange` prop:
 
-```ts
-const { secureJsonData, secureJsonFields } = options;
-const { apiKey } = secureJsonData;
-```
+   ```ts
+   const onAPIKeyChange = (event: ChangeEvent<HTMLInputElement>) => {
+     onOptionsChange({
+       ...options,
+       secureJsonData: {
+         apiKey: event.target.value,
+       },
+     });
+   };
+   ```
 
-To securely update the secret in your plugin's configuration editor, update the `secureJsonData` object using the `onOptionsChange` prop.
+1. Define a component that can accept user input:
 
-```ts
-const onAPIKeyChange = (event: ChangeEvent<HTMLInputElement>) => {
-  onOptionsChange({
-    ...options,
-    secureJsonData: {
-      apiKey: event.target.value,
-    },
-  });
-};
-```
+   ```ts
+   <Input
+     type="password"
+     placeholder={secureJsonFields?.apiKey ? 'configured' : ''}
+     value={secureJsonData.apiKey ?? ''}
+     onChange={onAPIKeyChange}
+   />
+   ```
 
-Next, define a component that can accept user input.
+1. Optional: If you want the user to be able to reset the API key, then you need to set the property to `false` in the `secureJsonFields` object:
 
-```ts
-<Input
-  type="password"
-  placeholder={secureJsonFields?.apiKey ? 'configured' : ''}
-  value={secureJsonData.apiKey ?? ''}
-  onChange={onAPIKeyChange}
-/>
-```
-
-Finally, if you want the user to be able to reset the API key, then you need to set the property to `false` in the `secureJsonFields` object.
-
-```ts
-const onResetAPIKey = () => {
-  onOptionsChange({
-    ...options,
-    secureJsonFields: {
-      ...options.secureJsonFields,
-      apiKey: false,
-    },
-    secureJsonData: {
-      ...options.secureJsonData,
-      apiKey: '',
-    },
-  });
-};
-```
+   ```ts
+   const onResetAPIKey = () => {
+     onOptionsChange({
+       ...options,
+       secureJsonFields: {
+         ...options.secureJsonFields,
+         apiKey: false,
+       },
+       secureJsonData: {
+         ...options.secureJsonData,
+         apiKey: '',
+       },
+     });
+   };
+   ```
 
 Now that users can configure secrets, the next step is to see how we can add them to our requests.
 
 ## Authenticate using the data source proxy
 
-Once the user has saved the configuration for a data source, any secret data source configuration will no longer be available in the browser. Encrypted secrets can only be accessed on the server. So how do you add them to you request?
+Once the user has saved the configuration for a data source, the secret data source configuration will no longer be available in the browser. Encrypted secrets can only be accessed on the server. So how do you add them to your request?
 
-The Grafana server comes with a proxy that lets you define templates for your requests. We call them _proxy routes_. Grafana sends the proxy route to the server, decrypts the secrets along with other configuration, and adds them to the request before sending it off.
+The Grafana server comes with a proxy that lets you define templates for your requests: _proxy routes_. Grafana sends the proxy route to the server, decrypts the secrets along with other configuration, and adds them to the request before sending it.
 
 > **Note:** Be sure not to confuse the data source proxy with the [auth proxy]({{< relref "../../setup-grafana/configure-security/configure-authentication/auth-proxy/" >}}). The data source proxy is used to authenticate a data source, while the auth proxy is used to log into Grafana itself.
 
 ### Add a proxy route to your plugin
 
-To forward requests through the Grafana proxy, you need to configure one or more proxy routes. A proxy route is a template for any outgoing request that is handled by the proxy. You can configure proxy routes in the [plugin.json](https://grafana.com/docs/grafana/latest/developers/plugins/metadata/) file.
+To forward requests through the Grafana proxy, you need to configure one or more _proxy routes_. A proxy route is a template for any outgoing request that is handled by the proxy. You can configure proxy routes in the [plugin.json](https://grafana.com/docs/grafana/latest/developers/plugins/metadata/) file.
 
-1. Add the route to plugin.json. Note that you need to restart the Grafana server every time you make a change to your plugin.json file.
+1. Add the route to `plugin.json`:
 
    ```json
    "routes": [
@@ -123,7 +132,9 @@ To forward requests through the Grafana proxy, you need to configure one or more
    ]
    ```
 
-1. In the `DataSource`, extract the proxy URL from `instanceSettings` to a class property called `url`.
+   > **Note:** You need to restart the Grafana server every time you make a change to your `plugin.json` file.
+
+1. In the `DataSource`, extract the proxy URL from `instanceSettings` to a class property called `url`:
 
    ```ts
    export class DataSource extends DataSourceApi<MyQuery, MyDataSourceOptions> {
@@ -139,7 +150,7 @@ To forward requests through the Grafana proxy, you need to configure one or more
    }
    ```
 
-1. In the `query` method, make a request using `BackendSrv`. The first section of the URL path needs to match the `path` of your proxy route. The data source proxy replaces `this.url + routePath` with the `url` of the route. The following request will be made to `https://api.example.com/v1/users`.
+1. In the `query` method, make a request using `BackendSrv`. The first section of the URL path needs to match the `path` of your proxy route. The data source proxy replaces `this.url + routePath` with the `url` of the route. Based on our example, the URL for the request would be `https://api.example.com/v1/users`:
 
    ```ts
    import { getBackendSrv } from '@grafana/runtime';
@@ -158,32 +169,36 @@ To forward requests through the Grafana proxy, you need to configure one or more
 
 Grafana sends the proxy route to the server, where the data source proxy decrypts any sensitive data and interpolates the template variables with the decrypted data before making the request.
 
-To add user-defined configuration to your routes, for example, add `{{ .JsonData.projectId }}` to the route, where `projectId` is the name of a property in the `jsonData` object.
+To add user-defined configuration to your routes:
 
-```json
-"routes": [
-  {
-    "path": "example",
-    "url": "https://api.example.com/projects/{{ .JsonData.projectId }}"
-  }
-]
-```
+- Use `.JsonData` for configuration stored in `jsonData`. For example, where `projectId` is the name of a property in the `jsonData` object:
 
-You can also configure your route to use sensitive data by using `.SecureJsonData`.
+  ```json
+  "routes": [
+    {
+      "path": "example",
+      "url": "https://api.example.com/projects/{{ .JsonData.projectId }}"
+    }
+  ]
+  ```
 
-```json
-"routes": [
-  {
-    "path": "example",
-    "url": "https://{{ .JsonData.username }}:{{ .SecureJsonData.password }}@api.example.com"
-  }
-]
-```
+- Use `.SecureJsonData` for sensitive data stored in `secureJsonData`. For example, where `password` is the name of a property in the `secureJsonData` object:
 
-In addition to the URL, you can also add headers, URL parameters, and a request body, to a proxy route.
+  ```json
+  "routes": [
+    {
+      "path": "example",
+      "url": "https://{{ .JsonData.username }}:{{ .SecureJsonData.password }}@api.example.com"
+    }
+  ]
+  ```
+
+In addition to adding the URL to the proxy route, you can also add headers, URL parameters, and a request body.
 
 #### Add HTTP headers to a proxy route
 
+Here's an example of adding `name` and `content` as HTTP headers:
+
 ```json
 "routes": [
   {
@@ -201,6 +216,8 @@ In addition to the URL, you can also add headers, URL parameters, and a request
 
 #### Add URL parameters to a proxy route
 
+Here's an example of adding `name` and `content` as URL parameters:
+
 ```json
 "routes": [
   {
@@ -218,6 +235,8 @@ In addition to the URL, you can also add headers, URL parameters, and a request
 
 #### Add a request body to a proxy route
 
+Here's an example of adding `username` and `password` to the request body:
+
 ```json
 "routes": [
   {
@@ -231,11 +250,9 @@ In addition to the URL, you can also add headers, URL parameters, and a request
 ]
 ```
 
-### Add a OAuth 2.0 proxy route to your plugin
+### Add an OAuth 2.0 proxy route to your plugin
 
-The data source proxy supports OAuth 2.0 authentication.
-
-Since the request to each route is made server-side, only machine-to-machine authentication is supported. In order words, if you need to use a different grant than client credentials, you need to implement it yourself.
+Since your request to each route is made server-side with OAuth 2.0 authentication, only machine-to-machine requests are supported. In order words, if you need to use a different grant than client credentials, you need to implement it yourself.
 
 To authenticate using OAuth 2.0, add a `tokenAuth` object to the proxy route definition. If necessary, Grafana performs a request to the URL defined in `tokenAuth` to retrieve a token before making the request to the URL in your proxy route. Grafana automatically renews the token when it expires.
 
@@ -264,10 +281,10 @@ Any parameters defined in `tokenAuth.params` are encoded as `application/x-www-f
 
 While the data source proxy supports the most common authentication methods for HTTP APIs, using proxy routes has a few limitations:
 
-- Proxy routes only support HTTP or HTTPS
-- Proxy routes don't support custom token authentication
+- Proxy routes only support HTTP or HTTPS.
+- Proxy routes don't support custom token authentication.
 
-If any of these limitations apply to your plugin, you need to add a [backend plugin]({{< relref "backend/" >}}). Since backend plugins run on the server they can access decrypted secrets, which makes it easier to implement custom authentication methods.
+If any of these limitations apply to your plugin, you need to add a [backend plugin]({{< relref "backend/" >}}). Because backend plugins run on the server, they can access decrypted secrets, which makes it easier to implement custom authentication methods.
 
 The decrypted secrets are available from the `DecryptedSecureJSONData` field in the instance settings.
 
@@ -285,21 +302,25 @@ func (ds *dataSource) QueryData(ctx context.Context, req *backend.QueryDataReque
 
 ## Forward OAuth identity for the logged-in user
 
-If your data source uses the same OAuth provider as Grafana itself, for example using [Generic OAuth Authentication]({{< relref "../../setup-grafana/configure-security/configure-authentication/generic-oauth/" >}}), your data source plugin can reuse the access token for the logged-in Grafana user.
+If your data source uses the same OAuth provider as Grafana itself, for example using [Generic OAuth Authentication]({{< relref "../../setup-grafana/configure-security/configure-authentication/generic-oauth/" >}}), then your data source plugin can reuse the access token for the logged-in Grafana user.
 
-To allow Grafana to pass the access token to the plugin, update the data source configuration and set the` jsonData.oauthPassThru` property to `true`. The [DataSourceHttpSettings](https://developers.grafana.com/ui/latest/index.html?path=/story/data-source-datasourcehttpsettings--basic) provides a toggle, the **Forward OAuth Identity** option, for this. You can also build an appropriate toggle to set `jsonData.oauthPassThru` in your data source configuration page UI.
+To allow Grafana to pass the access token to the plugin, update the data source configuration and set the `jsonData.oauthPassThru` property to `true`. The [DataSourceHttpSettings](https://developers.grafana.com/ui/latest/index.html?path=/story/data-source-datasourcehttpsettings--basic) settings provide a toggle, the **Forward OAuth Identity** option, for this. You can also build an appropriate toggle to set `jsonData.oauthPassThru` in your data source configuration page UI.
 
 When configured, Grafana can forward authorization HTTP headers such as `Authorization` or `X-ID-Token` to a backend data source. This information is available across the `QueryData`, `CallResource` and `CheckHealth` requests.
 
-To get Grafana to forward the headers, create a HTTP client using the [Grafana Plugin SDK](https://pkg.go.dev/github.com/grafana/grafana-plugin-sdk-go/backend/httpclient). This package exposes request information which can be subsequently forwarded downstream and/or used directly within the plugin.
+To get Grafana to forward the headers, create a HTTP client using the [Grafana plugin SDK for Go](https://pkg.go.dev/github.com/grafana/grafana-plugin-sdk-go/backend/httpclient) and set the `ForwardHTTPHeaders` option to `true` (by default, it's set to `false`). This package exposes request information which can be subsequently forwarded downstream and/or used directly within the plugin.
 
 ```go
 func NewDatasource(settings backend.DataSourceInstanceSettings) (instancemgmt.Instance, error) {
-	opts, err := settings.HTTPClientOptions()
+  opts, err := settings.HTTPClientOptions()
 	if err != nil {
 		return nil, fmt.Errorf("http client options: %w", err)
 	}
-  // Important to reuse the same client for each query, to avoid using all available connections on a host
+
+    // Important: Reuse the same client for each query to avoid using all available connections on a host.
+
+  opts.ForwardHTTPHeaders = true
+
 	cl, err := httpclient.New(opts)
 	if err != nil {
 		return nil, fmt.Errorf("httpclient new: %w", err)
@@ -310,7 +331,7 @@ func NewDatasource(settings backend.DataSourceInstanceSettings) (instancemgmt.In
 }
 
 func (ds *dataSource) QueryData(ctx context.Context, req *backend.QueryDataRequest) (*backend.QueryDataResponse, error) {
-    // Important to keep the Context, since the injected middleware is configured there
+    // Necessary to keep the Context, since the injected middleware is configured there
     req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://some-url", nil)
     if err != nil {
       return nil, fmt.Errorf("new request with context: %w", err)
@@ -321,9 +342,11 @@ func (ds *dataSource) QueryData(ctx context.Context, req *backend.QueryDataReque
 }
 ```
 
-You can see a full working example here: [datasource-http-backend](https://github.com/grafana/grafana-plugin-examples/tree/main/examples/datasource-http-backend).
+You can see a full working plugin example here: [datasource-http-backend](https://github.com/grafana/grafana-plugin-examples/tree/main/examples/datasource-http-backend).
 
-If you need to access HTTP header information directory, you can also extract that information from the request:
+### Extract a header from an HTTP request
+
+If you need to access the HTTP header information directly, you can also extract that information from the request:
 
 ```go
 func (ds *dataSource) CheckHealth(ctx context.Context, req *backend.CheckHealthRequest) (*backend.CheckHealthResult, error) {
@@ -359,27 +382,41 @@ func (ds *dataSource) CallResource(ctx context.Context, req *backend.CallResourc
 }
 ```
 
-## Forward cookies for the logged-in user
+## Work with cookies
+
+### Forward cookies for the logged-in user
 
 Your data source plugin can forward cookies for the logged-in Grafana user to the data source. Use the [DataSourceHttpSettings](https://developers.grafana.com/ui/latest/index.html?path=/story/data-source-datasourcehttpsettings--basic) component on the data source's configuration page. It provides the **Allowed cookies** option, where you can specify the cookie names.
 
-When configured, as with [authorization headers](#forward-oauth-identity-for-the-logged-in-user), these cookies are automatically injected if the SDK HTTP client is used.
+When configured, as with [authorization headers](#forward-oauth-identity-for-the-logged-in-user), these cookies are automatically injected if you use the SDK HTTP client.
+
+### Extract cookies for the logged-in user
 
 You can also extract the cookies in the `QueryData`, `CallResource` and `CheckHealth` requests if required.
 
+**`QueryData`**
+
 ```go
 func (ds *dataSource) QueryData(ctx context.Context, req *backend.QueryDataRequest) (*backend.QueryDataResponse, error) {
   cookies:= req.GetHTTPHeader(backend.CookiesHeaderName)
 
   // ...
 }
+```
 
+**`CallResource`**
+
+```go
 func (ds *dataSource) CallResource(ctx context.Context, req *backend.CallResourceRequest, sender backend.CallResourceResponseSender) error {
   cookies:= req.GetHTTPHeader(backend.CookiesHeaderName)
 
   // ...
 }
+```
 
+**`CheckHealth`**
+
+```go
 func (ds *dataSource) CheckHealth(ctx context.Context, req *backend.CheckHealthRequest) (*backend.CheckHealthResult, error) {
   cookies:= req.GetHTTPHeader(backend.CookiesHeaderName)
 
@@ -389,7 +426,9 @@ func (ds *dataSource) CheckHealth(ctx context.Context, req *backend.CheckHealthR
 
 ## Forward user header for the logged-in user
 
-When [send_user_header]({{< relref "../../setup-grafana/configure-grafana/_index.md#send_user_header" >}}) is enabled, Grafana will pass the user header to the plugin using the `X-Grafana-User` header. You can forward this header as well as [authorization headers](#forward-oauth-identity-for-the-logged-in-user) or [configured cookies](#forward-cookies-for-the-logged-in-user).
+When [send_user_header]({{< relref "../../setup-grafana/configure-grafana/_index.md#send_user_header" >}}) is enabled, Grafana passes the user header to the plugin using the `X-Grafana-User` header. You can forward this header as well as [authorization headers](#forward-oauth-identity-for-the-logged-in-user) or [configured cookies](#forward-cookies-for-the-logged-in-user).
+
+**`QueryData`**
 
 ```go
 func (ds *dataSource) QueryData(ctx context.Context, req *backend.QueryDataRequest) (*backend.QueryDataResponse, error) {
@@ -397,13 +436,21 @@ func (ds *dataSource) QueryData(ctx context.Context, req *backend.QueryDataReque
 
   // ...
 }
+```
 
+**`CallResource`**
+
+```go
 func (ds *dataSource) CallResource(ctx context.Context, req *backend.CallResourceRequest, sender backend.CallResourceResponseSender) error {
   u := req.GetHTTPHeader("X-Grafana-User")
 
   // ...
 }
+```
 
+**`CheckHealth`**
+
+```go
 func (ds *dataSource) CheckHealth(ctx context.Context, req *backend.CheckHealthRequest) (*backend.CheckHealthResult, error) {
   u := req.GetHTTPHeader("X-Grafana-User")
 

docs/sources/developers/plugins/add-distributed-tracing-for-backend-plugins.md

@@ -4,42 +4,39 @@ title: Add distributed tracing for backend plugins
 
 # Add distributed tracing for backend plugins
 
-> **Note:** This feature requires at least Grafana 9.5.0, and your plugin needs to be built at least with
-> grafana-plugins-sdk-go v0.157.0. If you run a plugin with tracing features on an older version of Grafana,
-> tracing will be disabled.
+> **Note:** This feature requires at least Grafana 9.5.0, and your plugin needs to be built at least with grafana-plugins-sdk-go v0.157.0. If you run a plugin with tracing features on an older version of Grafana, tracing is disabled.
 
-## Introduction
+Distributed tracing allows backend plugin developers to create custom spans in their plugins, and send them to the same endpoint and with the same propagation format as the main Grafana instance. The tracing context is also propagated from the Grafana instance to the plugin, so the plugin's spans will be correlated to the correct trace.
 
-Distributed tracing allows backend plugin developers to create custom spans in their plugins, and send them to the same endpoint
-and with the same propagation format as the main Grafana instance. The tracing context is also propagated from the Grafana instance
-to the plugin, so the plugin's spans will be correlated to the correct trace.
+## Plugin configuration
 
-## Configuration
-
-> **Note:** Only OpenTelemetry is supported. If Grafana is configured to use a deprecated tracing system (Jaeger or OpenTracing),
-> tracing will be disabled in the plugin. Please note that OpenTelemetry + Jaeger propagator is supported.
-
-OpenTelemetry must be enabled and configured for the Grafana instance. Please refer to [this section](
-{{< relref "../../setup-grafana/configure-grafana/#tracingopentelemetry" >}}) for more information.
-
-As of Grafana 9.5.0, plugins tracing must be enabled manually on a per-plugin basis, by specifying `tracing = true` in the plugin's config section:
+Plugin tracing must be enabled manually on a per-plugin basis, by specifying `tracing = true` in the plugin's config section:
 
 ```ini
 [plugin.myorg-myplugin-datasource]
 tracing = true
 ```
 
-## Implementing tracing in your plugin
+## OpenTelemetry configuration in Grafana
+
+Grafana supports [OpenTelemetry](https://opentelemetry.io/) for distributed tracing. If Grafana is configured to use a deprecated tracing system (Jaeger or OpenTracing), then tracing is disabled in the plugin provided by the SDK and configured when calling `datasource.Manage | app.Manage`.
+
+OpenTelemetry must be enabled and configured for the Grafana instance. Please refer to the [Grafana configuration documentation](
+{{< relref "../../setup-grafana/configure-grafana/#tracingopentelemetry" >}}) for more information.
+
+Refer to the [OpenTelemetry Go SDK](https://pkg.go.dev/go.opentelemetry.io/otel) for in-depth documentation about all the features provided by OpenTelemetry.
+
+> **Note:** If tracing is disabled in Grafana, `backend.DefaultTracer()` returns a no-op tracer.
+
+## Implement tracing in your plugin
 
 > **Note:** Make sure you are using at least grafana-plugin-sdk-go v0.157.0. You can update with `go get -u github.com/grafana/grafana-plugin-sdk-go`.
 
-When OpenTelemetry tracing is enabled on the main Grafana instance and tracing is enabeld for a plugin,
-the OpenTelemetry endpoint address and propagation format will be passed to the plugin during startup,
-which will be used to configure a global tracer.
+### Configure a global tracer
 
-1. The global tracer is configured automatically if you use <code>datasource.Manage</code> or <code>app.Manage</code> to run your plugin.
+When OpenTelemetry tracing is enabled on the main Grafana instance and tracing is enabled for a plugin, the OpenTelemetry endpoint address and propagation format is passed to the plugin during startup. These parameters are used to configure a global tracer.
 
-   This also allows you to specify custom attributes for the default tracer:
+1. Use `datasource.Manage` or `app.Manage` to run your plugin to automatically configure the global tracer. Specify any custom attributes for the default tracer using `CustomAttributes`:
 
    ```go
    func main() {
@@ -58,15 +55,15 @@ which will be used to configure a global tracer.
    }
    ```
 
-1. Once tracing is configured, you can access the global tracer with:
+1. Once you have configured tracing, use the global tracer like this:
 
    ```go
    tracing.DefaultTracer()
    ```
 
-   this returns an [OpenTelemetry trace.Tracer](https://pkg.go.dev/go.opentelemetry.io/otel/trace#Tracer), and can be used to create spans.
+   This returns an [OpenTelemetry `trace.Tracer`](https://pkg.go.dev/go.opentelemetry.io/otel/trace#Tracer) for creating spans.
 
-   For example:
+   **Example:**
 
    ```go
    func (d *Datasource) query(ctx context.Context, pCtx backend.PluginContext, query backend.DataQuery) (backend.DataResponse, error) {
@@ -89,18 +86,11 @@ which will be used to configure a global tracer.
    }
    ```
 
-   Refer to the [OpenTelemetry Go SDK](https://pkg.go.dev/go.opentelemetry.io/otel) for in-depth documentation about all the features provided by OpenTelemetry.
+### Tracing gRPC calls
 
-   If tracing is disabled in Grafana, `backend.DefaultTracer()` returns a no-op tracer.
+When tracing is enabled, a new span is created automatically for each gRPC call (`QueryData`, `CheckHealth`, etc.), both on Grafana's side and on the plugin's side. The plugin SDK also injects the trace context into the `context.Context` that is passed to those methods.
 
-### Tracing GRPC calls
-
-A new span is created automatically for each GRPC call (`QueryData`, `CheckHealth`, etc), both on Grafana's side and
-on the plugin's side.
-
-This also injects the trace context into the `context.Context` passed to those methods.
-
-This allows you to retrieve the [trace.SpanContext](https://pkg.go.dev/go.opentelemetry.io/otel/trace#SpanContext) by using `tracing.SpanContextFromContext` by passing the original `context.Context` to it:
+You can retrieve the [trace.SpanContext](https://pkg.go.dev/go.opentelemetry.io/otel/trace#SpanContext) with `tracing.SpanContextFromContext` by passing the original `context.Context` to it:
 
 ```go
 func (d *Datasource) query(ctx context.Context, pCtx backend.PluginContext, query backend.DataQuery) (backend.DataResponse, error) {
@@ -113,11 +103,8 @@ func (d *Datasource) query(ctx context.Context, pCtx backend.PluginContext, quer
 
 ### Tracing HTTP requests
 
-When tracing is enabled, a `TracingMiddleware` is also added to the default middleware stack to all HTTP clients created
-using the `httpclient.New` or `httpclient.NewProvider`, unless custom middlewares are specified.
+When tracing is enabled, a `TracingMiddleware` is also added to the default middleware stack to all HTTP clients created using the `httpclient.New` or `httpclient.NewProvider`, unless you specify custom middleware. This middleware creates spans for each outgoing HTTP request and provides some useful attributes and events related to the request's lifecycle.
 
-This middleware creates spans for each outgoing HTTP request and provides some useful attributes and events related to the request's lifecycle.
+## Plugin example
 
-## Complete plugin example
-
-You can refer to the [datasource-http-backend plugin example](https://github.com/grafana/grafana-plugin-examples/tree/main/examples/datasource-http-backend) for a complete example of a plugin that has full tracing support.
+Refer to the [datasource-http-backend plugin example](https://github.com/grafana/grafana-plugin-examples/tree/main/examples/datasource-http-backend) for a complete example of a plugin with full distributed tracing support.

docs/sources/developers/plugins/add-query-editor-help.md

@@ -2,11 +2,11 @@
 title: Add query editor help
 ---
 
-# Add a query editor help component
+# Add query editor help
 
-By adding a help component to your plugin, you can for example create "cheat sheets" with commonly used queries. When the user clicks on one of the examples, it automatically updates the query editor. It's a great way to increase productivity for your users.
+Query editors support the addition of a help component to display examples of potential queries. When the user clicks on one of the examples, the query editor is automatically updated. This helps the user to make faster queries.
 
-1. Create a file `QueryEditorHelp.tsx` in the `src` directory of your plugin, with the following content:
+1. In the `src` directory of your plugin, create a file `QueryEditorHelp.tsx` with the following content:
 
    ```ts
    import React from 'react';
@@ -17,7 +17,7 @@ By adding a help component to your plugin, you can for example create "cheat she
    };
    ```
 
-1. Configure the plugin to use the `QueryEditorHelp`.
+1. Configure the plugin to use `QueryEditorHelp`:
 
    ```ts
    import QueryEditorHelp from './QueryEditorHelp';
@@ -30,7 +30,7 @@ By adding a help component to your plugin, you can for example create "cheat she
      .setQueryEditorHelp(QueryEditorHelp);
    ```
 
-1. Create a few examples.
+1. Create a few examples of potential queries:
 
    ```ts
    import React from 'react';

docs/sources/developers/plugins/add-support-for-annotations.md

@@ -4,19 +4,15 @@ title: Add support for annotations
 
 # Add support for annotations
 
-This guide explains how to add support for [annotations]({{< relref "../../dashboards/build-dashboards/annotate-visualizations" >}}) to an existing data source plugin.
+You can add support to your plugin for annotations that will insert information into Grafana alerts. This guide explains how to add support for [annotations]({{< relref "../../dashboards/build-dashboards/annotate-visualizations/#querying-other-data-sources " >}}) to a data source plugin.
 
-This guide assumes that you're already familiar with how to [Build a data source plugin](/tutorials/build-a-data-source-plugin/).
+## Support annotations in your data source plugin
 
-> **Note:** Annotation support for React plugins was released in Grafana 7.2. To support earlier versions, refer to [Add support for annotation for Grafana 7.1](https://grafana.com/docs/grafana/v7.1/developers/plugins/add-support-for-annotations/).
-
-## Add annotations support to your data source
-
-To enable annotation support for your data source, add the following two lines of code. Grafana uses your default query editor for editing annotation queries.
+To enable annotations, simply add two lines of code to your plugin. Grafana uses your default query editor for editing annotation queries.
 
 1. Add `"annotations": true` to the [plugin.json]({{< relref "metadata/" >}}) file to let Grafana know that your plugin supports annotations.
 
-   **plugin.json**
+   **In `plugin.json`:**
 
    ```json
    {
@@ -24,9 +20,9 @@ To enable annotation support for your data source, add the following two lines o
    }
    ```
 
-2. In `datasource.ts`, override the `annotations` property from `DataSourceApi` (or `DataSourceWithBackend` for backend data sources). For the default behavior, you can set `annotations` to an empty object.
+2. In `datasource.ts`, override the `annotations` property from `DataSourceApi` (or `DataSourceWithBackend` for backend data sources). For the default behavior, set `annotations` to an empty object.
 
-   **datasource.ts**
+   **In `datasource.ts`:**
 
    ```ts
    annotations: {

docs/sources/developers/plugins/add-support-for-explore-queries.md

@@ -1,22 +1,18 @@
 ---
-title: Add support for Explore queries
+title: Add features to Explore queries
 ---
 
-# Add support for Explore queries
+# Add features for Explore queries
 
-This guide explains how to improve support for [Explore]({{< relref "../../explore/" >}}) in an existing data source plugin.
+[Explore]({{< relref "../../explore/" >}}) allows users can make ad-hoc queries without the use of a dashboard. This is useful when they want to troubleshoot or learn more about the data.
 
-This guide assumes that you're already familiar with how to [Build a data source plugin](/tutorials/build-a-data-source-plugin/).
-
-With Explore, users can make ad-hoc queries without the use of a dashboard. This is useful when users want to troubleshoot or to learn more about the data.
-
-Your data source supports Explore by default and uses the existing query editor for the data source.
+Your data source supports Explore by default and uses the existing query editor for the data source. This guide explains how to extend functionality for Explore queries in a data source plugin.
 
 ## Add an Explore-specific query editor
 
-To extend Explore functionality for your data source, you can define an Explore-specific query editor.
+To extend Explore functionality for your data source, define an Explore-specific query editor.
 
-1. Create a file `ExploreQueryEditor.tsx` in the `src` directory of your plugin, with the following content:
+1. Create a file `ExploreQueryEditor.tsx` in the `src` directory of your plugin, with content similar to this:
 
    ```ts
    import React from 'react';
@@ -54,13 +50,13 @@ To extend Explore functionality for your data source, you can define an Explore-
    };
    ```
 
-## Selecting preferred visualisation
+## Select a preferred visualization type
 
-Explore should by default select a reasonable visualization for your data so users do not have to tweak and play with the visualizations and just focus on querying. This usually works fairly well and Explore can figure out whether the returned data is time series data or logs or something else.
+By default, Explore should select an appropriate and useful visualization for your data. It can figure out whether the returned data is time series data or logs or something else, and creates the right type of visualization.
 
-If this does not work for you or you want to show some data in a specific visualization, add a hint to your returned data frame using the `preferredVisualisationType` meta attribute.
+However, if you want a custom visualization, you can add a hint to your returned data frame by setting the `meta' attribute to `preferredVisualisationType`.
 
-You can construct a data frame with specific metadata:
+Construct a data frame with specific metadata like this:
 
 ```
 const firstResult = new MutableDataFrame({

docs/sources/developers/plugins/add-support-for-variables.md

@@ -4,11 +4,9 @@ title: Add support for variables in plugins
 
 # Add support for variables in plugins
 
-Variables are placeholders for values, and can be used to create things like templated queries and dashboard or panel links. For more information on variables, refer to [Templates and variables]({{< relref "../../dashboards/variables/" >}}).
+Variables are placeholders for values, and you can use them to create templated queries, and dashboard or panel links. For more information on variables, refer to [Templates and variables]({{< relref "../../dashboards/variables/" >}}).
 
-This guide explains how to leverage template variables in your panel plugins and data source plugins.
-
-We'll see how you can turn a string like this:
+In this guide, you'll see how you can turn a query string like this:
 
 ```sql
 SELECT * FROM services WHERE id = "$service"
@@ -24,9 +22,9 @@ Grafana provides a couple of helper functions to interpolate variables in a stri
 
 ## Interpolate variables in panel plugins
 
-For panels, the `replaceVariables` function is available in the PanelProps.
+For panels, the `replaceVariables` function is available in the `PanelProps`.
 
-Add `replaceVariables` to the argument list, and pass it a user-defined template string.
+Add `replaceVariables` to the argument list, and pass a user-defined template string to it:
 
 ```ts
 export function SimplePanel({ options, data, width, height, replaceVariables }: Props) {
@@ -38,15 +36,15 @@ export function SimplePanel({ options, data, width, height, replaceVariables }:
 
 ## Interpolate variables in data source plugins
 
-For data sources, you need to use the getTemplateSrv, which returns an instance of TemplateSrv.
+For data sources, you need to use the `getTemplateSrv`, which returns an instance of `TemplateSrv`.
 
-1. Import `getTemplateSrv` from the `runtime` package.
+1. Import `getTemplateSrv` from the `runtime` package:
 
    ```ts
    import { getTemplateSrv } from '@grafana/runtime';
    ```
 
-1. In your `query` method, call the `replace` method with a user-defined template string.
+1. In your `query` method, call the `replace` method with a user-defined template string:
 
    ```ts
    async query(options: DataQueryRequest<MyQuery>): Promise<DataQueryResponse> {
@@ -60,9 +58,9 @@ For data sources, you need to use the getTemplateSrv, which returns an instance
 
 ## Format multi-value variables
 
-When a user selects multiple values for variable, the value of the interpolated variable depends on the [variable format]({{< relref "../../dashboards/variables/variable-syntax/#advanced-variable-format-options" >}}).
+When a user selects multiple values for a variable, the value of the interpolated variable depends on the [variable format]({{< relref "../../dashboards/variables/variable-syntax/#advanced-variable-format-options" >}}).
 
-A data source can define the default format option when no format is specified by adding a third argument to the interpolation function.
+A data source plugin can define the default format option when no format is specified by adding a third argument to the interpolation function.
 
 Let's change the SQL query to use CSV format by default:
 
@@ -84,8 +82,8 @@ Not only can you read the value of a variable, you can also update the variable
 
 The following example shows how to update a variable called `service`.
 
-- `query` contains the query parameters you want to update. Query parameters controlling variables are prefixed with `var-`.
-- `replace: true` tells Grafana to update the current URL state, rather than creating a new history entry.
+- `query` contains the query parameters you want to update. The query parameters that control variables are prefixed with `var-`.
+- `replace: true` tells Grafana to update the current URL state rather than creating a new history entry.
 
 ```ts
 import { locationService } from '@grafana/runtime';
@@ -99,9 +97,9 @@ locationService.partial({ 'var-service': 'billing' }, true);
 
 ## Add support for query variables to your data source
 
-[Query variables]({{< relref "../../dashboards/variables/add-template-variables/#add-a-query-variable" >}}) is a type of variable that allows you to query a data source for the values. By adding support for query variables to your data source plugin, users can create dynamic dashboards based on data from your data source.
+A [query variable]({{< relref "../../dashboards/variables/add-template-variables/#add-a-query-variable" >}}) is a type of variable that allows you to query a data source for the values. By adding support for query variables to your data source plugin, users can create dynamic dashboards based on data from your data source.
 
-Let's start by defining a query model for the variable query.
+Let's start by defining a query model for the variable query:
 
 ```ts
 export interface MyVariableQuery {
@@ -110,7 +108,7 @@ export interface MyVariableQuery {
 }
 ```
 
-For a data source to support query variables, you must override the `metricFindQuery` in your `DataSourceApi` class. `metricFindQuery` returns an array of `MetricFindValue` which has a single property, `text`:
+For a data source to support query variables, override the `metricFindQuery` in your `DataSourceApi` class. The `metricFindQuery` function returns an array of `MetricFindValue` which has a single property, `text`:
 
 ```ts
 async metricFindQuery(query: MyVariableQuery, options?: any) {
@@ -124,15 +122,15 @@ async metricFindQuery(query: MyVariableQuery, options?: any) {
 }
 ```
 
-> **Note:** By default, Grafana provides a default query model and editor for simple text queries. If that's all you need, then you can leave the query type as `string`.
->
-> ```ts
-> async metricFindQuery(query: string, options?: any)
-> ```
+> **Note:** By default, Grafana provides a basic query model and editor for simple text queries. If that's all you need, then leave the query type as `string`:
+
+```ts
+async metricFindQuery(query: string, options?: any)
+```
 
 Let's create a custom query editor to allow the user to edit the query model.
 
-1. Create a `VariableQueryEditor` component.
+1. Create a `VariableQueryEditor` component:
 
    ```ts
    import React, { useState } from 'react';
@@ -185,9 +183,9 @@ Let's create a custom query editor to allow the user to edit the query model.
 
    Grafana saves the query model whenever one of the text fields loses focus (`onBlur`) and then previews the values returned by `metricFindQuery`.
 
-   The second argument to `onChange` allows you to set a text representation of the query which will appear next to the name of the variable in the variables list.
+   The second argument to `onChange` allows you to set a text representation of the query that will appear next to the name of the variable in the variables list.
 
-1. Finally, configure your plugin to use the query editor.
+1. Configure your plugin to use the query editor:
 
    ```ts
    import { VariableQueryEditor } from './VariableQueryEditor';

docs/sources/developers/plugins/backend/_index.md

@@ -13,63 +13,85 @@ title: Backend plugins
 
 # Backend plugins
 
-Grafana added support for plugins in version 3.0 and this enabled the Grafana community to create panel plugins and data source plugins. It was wildly successful and has made Grafana much more useful as you can integrate it with anything and do any type of custom visualization that you want.
+The Grafana plugin system for backend development allows you to integrate Grafana with virtually anything and offer custom visualizations. This document explains the system's background, use cases, and key features.
 
-However, one limitation with these plugins are that they execute on the client-side (in the browser) which makes it hard to support certain use cases/features, e.g. enable Grafana Alerting for data sources. Grafana v7.0 adds official support for backend plugins which removes this limitation. At the same time it gives plugin developers the possibility to extend Grafana in new and interesting ways, with code running in the backend (server side).
+## Background
 
-We use the term _backend plugin_ to denote that a plugin has a backend component. Still, normally a backend plugin requires frontend components as well. This is for example true for backend data source plugins which normally need configuration and query editor components implemented for the frontend.
+Grafana added support for _frontend plugins_ in version 3.0 so that the Grafana community could create custom panels and data sources. It was wildly successful and has made Grafana much more useful for our user community.
 
-Data source plugins can be extended with a backend component. In the future we plan to support additional types and possibly new kinds of plugins, such as notifiers for Grafana Alerting and custom authentication to name a few.
+However, one limitation of these plugins is that they run on the client side, in the browser. Therefore, they can't support use cases that require server-side features.
+
+Since Grafana v7.0, we have supported server-side plugins that remove this limitation. We use the term _backend plugin_ to denote that a plugin has a backend component. A backend plugin usually requires frontend components as well. For example, some backend data source plugins need query editor components on the frontend.
 
 ## Use cases for implementing a backend plugin
 
-The following examples gives you an idea of why you'd consider implementing a backend plugin:
+The following examples give some common use cases for backend plugins:
 
 - Enable [Grafana Alerting]({{< relref "../../../alerting/" >}}) for data sources.
-- Connect to non-HTTP services that normally can't be connected to from a web browser, e.g. SQL database servers.
-- Keep state between users, e.g. query caching for data sources.
+- Connect to SQL database servers and other non-HTTP services that normally can't be connected to from a browser.
+- Keep state between users, for example, by query caching for data sources.
 - Use custom authentication methods and/or authorization checks that aren't supported in Grafana.
-- Use a custom data source request proxy, see [Resources]({{< relref "#resources" >}}).
+- Use a custom data source request proxy (refer to [Resources]({{< relref "#resources" >}}) for more information).
 
-## Grafana’s backend plugin system
+## Grafana backend plugin system
 
-The Grafana backend plugin system is based on the [go-plugin library by HashiCorp](https://github.com/hashicorp/go-plugin). The Grafana server launches each backend plugin as a subprocess and communicates with it over [gRPC](https://grpc.io/). This approach has a number of benefits:
+The Grafana backend plugin system is based on HashiCorp's [Go Plugin System over RPC](https://github.com/hashicorp/go-plugin). Our implementation of the Grafana server launches each backend plugin as a subprocess and communicates with it over [gRPC](https://grpc.io/).
 
-- Plugins can’t crash your grafana process: a panic in a plugin doesn’t panic the server.
-- Plugins are easy to develop: just write a Go application and run `go build` (or use any other language which supports gRPC).
-- Plugins can be relatively secure: The plugin only has access to the interfaces and arguments that are given to it, not to the entire memory space of the process.
+### Benefits for plugin development
 
-Grafana's backend plugin system exposes a couple of different capabilities, or building blocks, that a backend plugin can implement:
+Grafana's approach has benefits for developers:
+
+- **Stability:** Plugins can't crash your Grafana process: a panic in a plugin doesn't panic the server.
+- **Ease of development:** Plugins can be written in any language that supports gRPC (for example, write a Go application and run `go build`).
+- **Security:** Plugins only have access to the interfaces and arguments given to them, not to the entire memory space of the process.
+
+### Capabilities of the backend plugin system
+
+Grafana's backend plugin system exposes several key capabilities, or building blocks, that your backend plugin can implement:
 
 - Query data
 - Resources
 - Health checks
 - Collect metrics
+- Streaming
 
-### Query data
+#### Query data
 
-The query data capability allows a backend plugin to handle data source queries that are submitted from a [dashboard]({{< relref "../../../dashboards/" >}}), [Explore]({{< relref "../../../explore/" >}}) or [Grafana Alerting]({{< relref "../../../alerting/" >}}). The response contains [data frames]({{< relref "../data-frames/" >}}), which are used to visualize metrics, logs, and traces. The query data capability is required to implement for a backend data source plugin.
+The query data capability allows a backend plugin to handle data source queries that are submitted from a [dashboard]({{< relref "../../../dashboards/" >}}), [Explore]({{< relref "../../../explore/" >}}) or [Grafana Alerting]({{< relref "../../../alerting/" >}}). The response contains [data frames]({{< relref "../data-frames/" >}}), which are used to visualize metrics, logs, and traces.
 
-### Resources
+{{% admonition type="note" %}} Backend data source plugins are required to implement the query data capability.{{%
+/admonition %}}
 
-The resources capability allows a backend plugin to handle custom HTTP requests sent to the Grafana HTTP API and respond with custom HTTP responses. Here, the request and response formats can vary, e.g. JSON, plain text, HTML or static resources (files, images) etc. Compared to the query data capability where the response contains data frames, resources give the plugin developer a lot of flexibility for extending and open up Grafana for new and interesting use cases.
+#### Resources
+
+The resources capability allows a backend plugin to handle custom HTTP requests sent to the Grafana HTTP API and respond with custom HTTP responses. Here, the request and response formats can vary. For example, you can use JSON, plain text, HTML, or static resources such as images and files, and so on.
+
+Compared to the query data capability, where the response contains data frames, the resources capability gives the plugin developer more flexibility for extending and opening up Grafana for new and interesting use cases.
+
+### Use cases
 
 Examples of use cases for implementing resources:
 
-- Implement a custom data source proxy in case certain authentication/authorization or other requirements are required/needed that are not supported in Grafana's [built-in data proxy]({{< relref "../../http_api/data_source/#data-source-proxy-calls" >}}).
-- Return data or information in a format suitable to use within a data source query editor to provide auto-complete functionality.
-- Return static resources, such as images or files.
-- Send a command to a device, such as a micro controller or IOT device.
-- Request information from a device, such as a micro controller or IOT device.
+- Implement a custom data source proxy to provide certain authentication, authorization, or other requirements that are not supported in Grafana's [built-in data proxy]({{< relref "../../http_api/data_source/#data-source-proxy-calls" >}}).
+- Return data or information in a format suitable for use within a data source query editor to provide auto-complete functionality.
+- Return static resources such as images or files.
+- Send a command to a device, such as a microcontroller or IoT device.
+- Request information from a device, such as a microcontroller or IoT device.
 - Extend Grafana's HTTP API with custom resources, methods and actions.
-- Use [chunked transfer encoding](https://en.wikipedia.org/wiki/Chunked_transfer_encoding) to return large data responses in chunks or to enable "basic" streaming capabilities.
+- Use [chunked transfer encoding](https://en.wikipedia.org/wiki/Chunked_transfer_encoding) to return large data responses in chunks or to enable certain streaming capabilities.
 
-### Health checks
+#### Health checks
 
-The health checks capability allows a backend plugin to return the status of the plugin. For data source backend plugins the health check will automatically be called when you do _Save & Test_ in the UI when editing a data source. A plugin's health check endpoint is exposed in the Grafana HTTP API and allows external systems to continuously poll the plugin's health to make sure it's running and working as expected.
+The health checks capability allows a backend plugin to return the status of the plugin. For data source backend plugins, the health check is automatically called when a user edits a data source and selects _Save & Test_ in the UI.
 
-### Collect metrics
+A plugin's health check endpoint is exposed in the Grafana HTTP API and allows external systems to continuously poll the plugin's health to make sure that it's running and working as expected.
 
-A backend plugin can collect and return runtime, process and custom metrics using the text-based Prometheus [exposition format](https://prometheus.io/docs/instrumenting/exposition_formats/). If you’re using the [Grafana Plugin SDK for Go]({{< relref "grafana-plugin-sdk-for-go/" >}}) to implement your backend plugin, then the [Prometheus instrumentation library for Go applications](https://github.com/prometheus/client_golang) is built-in, and gives you Go runtime metrics and process metrics out of the box. By using the [Prometheus instrumentation library](https://github.com/prometheus/client_golang) you can add custom metrics to instrument your backend plugin.
+#### Collect metrics
 
-A metrics endpoint (`/api/plugins/<plugin id>/metrics`) for a plugin is available in the Grafana HTTP API and allows a Prometheus instance to be configured to scrape the metrics.
+A backend plugin can collect and return runtime, process, and custom metrics using the text-based Prometheus [exposition format](https://prometheus.io/docs/instrumenting/exposition_formats/). If you're using the [Grafana Plugin SDK for Go]({{< relref "grafana-plugin-sdk-for-go/" >}}) to implement your backend plugin, then the [Prometheus instrumentation library for Go applications](https://github.com/prometheus/client_golang) is built-in. This SDK gives you Go runtime metrics and process metrics out of the box. You can use the [Prometheus instrumentation library](https://github.com/prometheus/client_golang) to add custom metrics to instrument your backend plugin.
+
+The Grafana HTTP API offers an endpoint (`/api/plugins/<plugin id>/metrics`) that allows you to configure a Prometheus instance to scrape the metrics.
+
+#### Streaming
+
+The streaming capability allows a backend plugin to handle data source queries that are streaming. For more information, refer to [Build a streaming data source plugin]({{<relref  "../build-a-streaming-data-source-plugin.md">}})

docs/sources/developers/plugins/backend/grafana-plugin-sdk-for-go.md

@@ -12,15 +12,17 @@ title: Grafana Plugin SDK for Go
 
 # Grafana plugin SDK for Go
 
-The Grafana plugin SDK for Go enables building Grafana backend plugins using [Go](https://golang.org/). The SDK provides a high-level framework with APIs, utilities and tooling that abstract away the details of the [plugin protocol]({{< relref "plugin-protocol/" >}}) and RPC communication so plugin developers do not need to manage either.
+The [Grafana plugin SDK for Go](https://pkg.go.dev/mod/github.com/grafana/grafana-plugin-sdk-go?tab=overview) is a [Go](https://golang.org/) module that provides a set of [packages](https://pkg.go.dev/mod/github.com/grafana/grafana-plugin-sdk-go?tab=packages) that you can use to implement a backend plugin.
 
-The [github.com/grafana/grafana-plugin-sdk-go](https://pkg.go.dev/mod/github.com/grafana/grafana-plugin-sdk-go?tab=overview) is a Go module that provides a set of [Go packages](https://pkg.go.dev/mod/github.com/grafana/grafana-plugin-sdk-go?tab=packages) that can be used to implement a backend plugin.
+The plugin SDK provides a high-level framework with APIs, utilities, and tooling. By using the SDK, you can avoid the need to learn the details of the [plugin protocol]({{< relref "plugin-protocol/" >}}) and RPC communication protocol, so you don't have to manage either one.
 
 ## Versioning
 
-The SDK is still in development. The [plugin protocol]({{< relref "plugin-protocol/" >}}) between Grafana and the plugin SDK is versioned separately and considered stable. However, there might be breaking changes introduced in the SDK. This means that plugins using an older version of the SDK should still work with Grafana, but might lose out on new features and capabilities introduced in the SDK.
+The Grafana plugin Go SDK is still in development. It is based on the [plugin protocol]({{< relref "plugin-protocol/" >}}), which is versioned separately and is considered stable. However, from time to time, we might introduce breaking changes in the SDK.
+
+When we update the plugin SDK, those plugins that use an older version of the SDK should still work with Grafana. However, these older plugins may be unable to use the new features and capabilities we introduce in updated SDK versions.
 
 ## See also
 
-- [Source code](https://github.com/grafana/grafana-plugin-sdk-go)
+- [SDK source code](https://github.com/grafana/grafana-plugin-sdk-go)
 - [Go reference documentation](https://pkg.go.dev/github.com/grafana/grafana-plugin-sdk-go)

docs/sources/developers/plugins/backend/plugin-protocol.md

@@ -11,24 +11,35 @@ title: Plugin protocol
 
 # Plugin protocol
 
-There’s a physical wire protocol that Grafana server uses to communicate with backend plugins. This is the contract between Grafana and backend plugins, that must be agreed upon for Grafana and a backend plugin to be able to communicate with each other. The plugin protocol is built on [gRPC](https://grpc.io/) and is defined in [Protocol Buffers (a.k.a., protobuf)](https://developers.google.com/protocol-buffers).
+The Grafana server uses a physical wire protocol to communicate with backend plugins. This protocol establishes a contract between Grafana and backend plugins to allow them to communicate with each other.
 
-We advise for backend plugins to not be implemented directly against this protocol. Instead, prefer to use the [Grafana Plugin SDK for Go]({{< relref "grafana-plugin-sdk-for-go/" >}}) that implements this protocol and provides higher level APIs.
+## Developing with the plugin protocol
 
-The plugin protocol is available in the [GitHub repository](https://github.com/grafana/grafana-plugin-sdk-go/blob/master/proto/backend.proto). The plugin protocol lives in the [Grafana Plugin SDK for Go]({{< relref "grafana-plugin-sdk-for-go/" >}}) since Grafana itself uses parts of the SDK as a dependency.
+{{% admonition type="caution" %}} We strongly recommend that backend plugin development not be implemented directly against the protocol. Instead, we prefer that you use the [Grafana Plugin SDK for Go]({{< relref "grafana-plugin-sdk-for-go/" >}}) that implements this protocol and provides higher-level APIs. {{%
+/admonition %}}
+
+If you choose to develop against the plugin protocol directly, you can do so using [Protocol Buffers](https://developers.google.com/protocol-buffers) (that is, protobufs) with [gRPC](https://grpc.io/).
+
+Grafana's plugin protocol protobufs are available in the [GitHub repository](https://github.com/grafana/grafana-plugin-sdk-go/blob/master/proto/backend.proto).
+
+{{% admonition type="note" %}}
+The plugin protocol lives in the [Grafana Plugin SDK for Go]({{< relref "grafana-plugin-sdk-for-go/" >}}) because Grafana itself uses parts of the SDK as a dependency.
+{{% /admonition %}}
 
 ## Versioning
 
-Additions of services, messages and fields in the latest version of the plugin protocol are expected to happen, but should not introduce any breaking changes. If breaking changes to the plugin protocol is needed, a new major version of the plugin protocol will be created and released together with a new major Grafana release. Grafana will then support both the old and the new plugin protocol for some time to make sure existing backend plugins continue to work.
+From time to time, Grafana will offer additions of services, messages, and fields in the latest version of the plugin protocol. We don't expect these updates to introduce any breaking changes. However, if we must introduce breaking changes to the plugin protocol, we'll create a new major version of the plugin protocol.
 
-Because Grafana maintains the plugin protocol, the plugin protocol attempts to follow Grafana's versioning, However, that doesn't automatically mean that a new major version of the plugin protocol is created when a new major release of Grafana is released.
+Grafana will release new major versions of the plugin protocol alongside new major Grafana releases. When this happens, we'll support both the old and the new plugin protocol for some time to make sure existing backend plugins continue to work.
+
+The plugin protocol attempts to follow Grafana's versioning. However, that doesn't mean we will automatically create a new major version of the plugin protocol when a new major release of Grafana is released.
 
 ## Writing plugins without Go
 
-If you want to write a backend plugin in another language than Go, then it’s possible as long as the language supports [gRPC](https://grpc.io/). However, writing a plugin in Go is recommended and has several advantages that should be carefully taken into account before proceeding:
+If you want to write a backend plugin in a language other than Go, then it's possible as long as the language supports gRPC. However, we recommend that you develop your plugin in Go for several reasons:
 
-- There's an official [SDK]({{< relref "grafana-plugin-sdk-for-go/" >}}) available.
-- Single binary as the compiled output.
-- Building and compiling for multiple platforms is easy.
-- A statically compiled binary (in most cases) doesn't require any additional dependencies installed on the target platform enabling it to run “everywhere”.
-- Small footprint in regards to binary size and resource usage.
+- We offer an official plugin SDK.
+- The compiled output is a single binary.
+- Writing for multiple platforms is easy. Typically, no additional dependencies must be installed on the target platform.
+- Small footprint for binary size.
+- Small footprint for resource usage.

docs/sources/developers/plugins/build-a-logs-data-source-plugin.md

@@ -4,19 +4,22 @@ title: Build a logs data source plugin
 
 # Build a logs data source plugin
 
-This guide explains how to build a logs data source plugin.
+Grafana data source plugins support metrics, logs, and other data types. The steps to build a logs data source plugin are largely the same as for a metrics data source, but there are a few differences which we will explain in this guide.
 
-Data sources in Grafana supports both metrics and log data. The steps to build a logs data source plugin are largely the same as for a metrics data source. This guide assumes that you're already familiar with how to [Build a data source plugin](/tutorials/build-a-data-source-plugin/) for metrics.
+## Before you begin
+
+This guide assumes that you're already familiar with how to [Build a data source plugin](/tutorials/build-a-data-source-plugin/) for metrics. We recommend that you review this material before continuing.
 
 ## Add logs support to your data source
 
 To add logs support to an existing data source, you need to:
 
-- Enable logs support
-- Construct the log data
-- (Optional) Add preferred visualisation type hint to the data frame
+1. Enable logs support
+1. Construct the log data
 
-### Enable logs support
+When these steps are done, then you can improve the user experience with one or more [optional features](#enhance-your-logs-data-source-plugin-with-optional-features).
+
+### Step 1: Enable logs support
 
 Tell Grafana that your data source plugin can return log data, by adding `"logs": true` to the [plugin.json]({{< relref "metadata/" >}}) file.
 
@@ -26,9 +29,9 @@ Tell Grafana that your data source plugin can return log data, by adding `"logs"
 }
 ```
 
-### Construct the log data
+### Step 2: Construct the log data
 
-Just like for metrics data, Grafana expects your plugin to return log data as a [data frame]({{< relref "data-frames/" >}}).
+As it does with metrics data, Grafana expects your plugin to return log data as a [data frame]({{< relref "data-frames/" >}}).
 
 To return log data, return a data frame with at least one time field and one text field from the data source's `query` method.
 
@@ -51,9 +54,13 @@ That's all you need to start returning log data from your data source. Go ahead
 
 Congratulations, you just wrote your first logs data source plugin! Next, let's look at a couple of features that can further improve the experience for the user.
 
-### (Optional) Add preferred visualisation type hint to the data frame
+## Enhance your logs data source plugin with optional features
 
-To make sure Grafana recognizes data as logs and shows logs visualization automatically in Explore you have do set `meta.preferredVisualisationType` to `'logs'` in the returned data frame. See [Selecting preferred visualisation section]({{< relref "add-support-for-explore-queries/#selecting-preferred-visualisation" >}})
+Add visualization type hints, labels, and other optional features to logs.
+
+### Add a preferred visualization type hint to the data frame
+
+To make sure Grafana recognizes data as logs and shows logs visualization automatically in Explore, set `meta.preferredVisualisationType` to `'logs'` in the returned data frame. See [Selecting preferred visualisation section]({{< relref "add-support-for-explore-queries/#selecting-preferred-visualisation" >}})
 
 **Example:**
 
@@ -70,11 +77,11 @@ const frame = new MutableDataFrame({
 });
 ```
 
-## Add labels to your logs
+### Add labels to your logs
 
-To help filter log lines, many log systems let you query logs based on metadata, or _labels_.
+Many log systems let you query logs based on metadata, or _labels_, to help filter log lines.
 
-You can add labels to a stream of logs by setting the labels property on the Field.
+Add labels to a stream of logs by setting the `labels` property on the Field.
 
 **Example**:
 
@@ -91,15 +98,15 @@ frame.add({ time: 1589189388597, content: 'user registered' });
 frame.add({ time: 1589189406480, content: 'user logged in' });
 ```
 
-## Extract detected fields from your logs
+### Extract detected fields from your logs
 
-You can add additional information about each log line by adding more data frame fields.
+Add additional information about each log line by supplying more data frame fields.
 
-If a data frame has more than one text field, then Grafana assumes the first field in the data frame to be the actual log line. Any subsequent text fields are treated as [detected fields]({{< relref "../../explore/#labels-and-detected-fields" >}}).
+If a data frame has more than one text field, then Grafana assumes the first field in the data frame to be the actual log line. Grafana treats subsequent text fields as [detected fields]({{< relref "../../explore/#labels-and-detected-fields" >}}).
 
-While you can add any number of custom fields to your data frame, Grafana comes with a couple of dedicated fields: `levels` and `id`. Let's have a closer look at each one.
+Any number of custom fields can be added to your data frame; Grafana comes with two dedicated fields: `levels` and `id`.
 
-### Levels
+#### Levels
 
 To set the level for each log line, add a `level` field.
 
@@ -119,7 +126,7 @@ frame.add({ time: 1589189388597, content: 'user registered', level: 'info' });
 frame.add({ time: 1589189406480, content: 'unknown error', level: 'error' });
 ```
 
-### Unique log lines
+#### 'id' for assigning unique identifiers to log lines
 
 By default, Grafana offers basic support for deduplicating log lines. You can improve the support by adding an `id` field to explicitly assign identifiers to each log line.
 

docs/sources/developers/plugins/build-a-streaming-data-source-plugin.md

@@ -4,100 +4,112 @@ title: Build a streaming data source plugin
 
 # Build a streaming data source plugin
 
-This guide explains how to build a streaming data source plugin.
+In Grafana, you can set your dashboards to automatically refresh at a certain interval, no matter what data source you use. Unfortunately, this means that your queries are requesting all the data to be sent again, regardless of whether the data has actually changed. Adding streaming to a plugin helps reduce queries so your dashboard is only updated when new data becomes available.
+
+## Before you begin
 
 This guide assumes that you're already familiar with how to [Build a data source plugin](/tutorials/build-a-data-source-plugin/).
 
-When monitoring critical applications, you want your dashboard to refresh as soon as your data does. In Grafana, you can set your dashboards to automatically refresh at a certain interval, no matter what data source you use. Unfortunately, this means that your queries are requesting all the data to be sent again, regardless of whether the data has actually changed.
+Grafana uses [RxJS](https://rxjs.dev/) to continuously send data from a data source to a panel visualization.
 
-By enabling _streaming_ for your data source plugin, you can update your dashboard as soon as new data becomes available.
+> **Note:** To learn more about RxJs, refer to the [RxJS documentation](https://rxjs.dev/guide/overview).
+
+## Add streaming to your data source
+
+Enable streaming for your data source plugin to update your dashboard when new data becomes available.
 
 For example, a streaming data source plugin can connect to a websocket, or subscribe to a message bus, and update the visualization whenever a new message is available.
 
-Let's see how you can add streaming to an existing data source!
+### Step 1: Edit the `plugin.json` file
 
-Grafana uses [RxJS](https://rxjs.dev/) to continuously send data from a data source to a panel visualization. There's a lot more to RxJS than what's covered in this guide. If you want to learn more, check out the [RxJS documentation](https://rxjs.dev/guide/overview).
+Enable streaming for your data source in the `plugin.json` file.
 
-1. Enable streaming for your data source in the `plugin.json` file.
+```json
+{
+  "streaming": true
+}
+```
 
-   ```json
-   {
-     "streaming": true
-   }
-   ```
+### Step 2: Change the signature of the `query` method
 
-1. Change the signature of the `query` method to return an `Observable` from the `rxjs` package. Make sure you remove the `async` keyword.
+Modify the signature of the `query` method to return an `Observable` from the `rxjs` package. Make sure you remove the `async` keyword.
 
-   ```ts
-   import { Observable } from 'rxjs';
-   ```
+```ts
+import { Observable } from 'rxjs';
+```
 
-   ```ts
-   query(options: DataQueryRequest<MyQuery>): Observable<DataQueryResponse> {
-     // ...
-   }
-   ```
+```ts
+query(options: DataQueryRequest<MyQuery>): Observable<DataQueryResponse> {
+  // ...
+}
+```
 
-1. Create an `Observable` for each query, and then combine them all using the `merge` function from the `rxjs` package.
+### Step 3: Create an `Observable` instance for each query
 
-   ```ts
-   import { Observable, merge } from 'rxjs';
-   ```
+Create an `Observable` instance for each query, and then combine them all using the `merge` function from the `rxjs` package.
 
-   ```ts
-   const observables = options.targets.map((target) => {
-     return new Observable<DataQueryResponse>((subscriber) => {
-       // ...
-     });
-   });
+```ts
+import { Observable, merge } from 'rxjs';
+```
 
-   return merge(...observables);
-   ```
+```ts
+const observables = options.targets.map((target) => {
+  return new Observable<DataQueryResponse>((subscriber) => {
+    // ...
+  });
+});
 
-1. In the `subscribe` function, create a `CircularDataFrame`.
+return merge(...observables);
+```
 
-   ```ts
-   import { CircularDataFrame } from '@grafana/data';
-   ```
+### Step 4: Create a `CircularDataFrame` instance
 
-   ```ts
-   const frame = new CircularDataFrame({
-     append: 'tail',
-     capacity: 1000,
-   });
+In the `subscribe` function, create a `CircularDataFrame` instance.
 
-   frame.refId = query.refId;
-   frame.addField({ name: 'time', type: FieldType.time });
-   frame.addField({ name: 'value', type: FieldType.number });
-   ```
+```ts
+import { CircularDataFrame } from '@grafana/data';
+```
 
-   Circular data frames have a limited capacity. When a circular data frame reaches its capacity, the oldest data point is removed.
+```ts
+const frame = new CircularDataFrame({
+  append: 'tail',
+  capacity: 1000,
+});
 
-1. Use `subscriber.next()` to send the updated data frame whenever you receive new updates.
+frame.refId = query.refId;
+frame.addField({ name: 'time', type: FieldType.time });
+frame.addField({ name: 'value', type: FieldType.number });
+```
 
-   ```ts
-   import { LoadingState } from '@grafana/data';
-   ```
+Circular data frames have a limited capacity. When a circular data frame reaches its capacity, the oldest data point is removed.
 
-   ```ts
-   const intervalId = setInterval(() => {
-     frame.add({ time: Date.now(), value: Math.random() });
+### Step 5: Send the updated data frame
 
-     subscriber.next({
-       data: [frame],
-       key: query.refId,
-       state: LoadingState.Streaming,
-     });
-   }, 500);
+Use `subscriber.next()` to send the updated data frame whenever you receive new updates.
 
-   return () => {
-     clearInterval(intervalId);
-   };
-   ```
+```ts
+import { LoadingState } from '@grafana/data';
+```
 
-   > **Note:** In practice, you'd call `subscriber.next` as soon as you receive new data from a websocket or a message bus. The example above simulates data being received every 500 milliseconds.
+```ts
+const intervalId = setInterval(() => {
+  frame.add({ time: Date.now(), value: Math.random() });
 
-Here's the final `query` method.
+  subscriber.next({
+    data: [frame],
+    key: query.refId,
+    state: LoadingState.Streaming,
+  });
+}, 500);
+
+return () => {
+  clearInterval(intervalId);
+};
+```
+
+> **Note:** In practice, you'd call `subscriber.next` as soon as you receive new data from a websocket or a message bus. In the example above, data is being received every 500 milliseconds.
+
+### Example code for final `query` method
 
 ```ts
 query(options: DataQueryRequest<MyQuery>): Observable<DataQueryResponse> {
@@ -134,4 +146,6 @@ query(options: DataQueryRequest<MyQuery>): Observable<DataQueryResponse> {
 }
 ```
 
-One limitation with this example is that the panel visualization is cleared every time you update the dashboard. If you have access to historical data, you can add, or _backfill_, it to the data frame before the first call to `subscriber.next()`.
+One limitation with this example is that the panel visualization is cleared every time you update the dashboard. If you have access to historical data, you can add it, or _backfill_ it, to the data frame before the first call to `subscriber.next()`.
+
+For another example of a streaming plugin, refer to the [streaming websocket example](https://github.com/grafana/grafana-plugin-examples/tree/main/examples/datasource-streaming-websocket) on GitHub.

docs/sources/developers/plugins/create-a-grafana-plugin/_index.md

@@ -0,0 +1,27 @@
+---
+description: How-to topics for plugin development
+title: Create a plugin
+---
+
+# Create a Grafana plugin
+
+This section contains how-to topics for developing Grafana plugins.
+
+- [Build a Grafana plugin](https://grafana.github.io/plugin-tools/docs/creating-a-plugin)
+  - [Build a panel plugin](https://grafana.com/tutorials/build-a-panel-plugin/)
+  - [Build a data source plugin](https://grafana.com/tutorials/build-a-data-source-plugin/)
+  - [Build a data source backend plugin](https://grafana.com/tutorials/build-a-data-source-backend-plugin/)
+  - [Build a logs data source plugin]({{< relref "../build-a-logs-data-source-plugin.md">}})
+  - [Build a streaming data source plugin]({{< relref "../build-a-streaming-data-source-plugin.md">}})
+- Extend a Grafana plugin
+  - [Add annotations]({{< relref "add-support-for-annotations.md">}})
+  - [Add anonymous usage reporting]({{< relref "add-anonymous-usage-reporting.md">}})
+  - [Add authentication for a data source plugin]({{< relref "add-authentication-for-data-source-plugins.md">}})
+  - [Add Explore queries]({{< relref "add-support-for-explore-queries.md">}})
+  - [Add query editor help]({{< relref "add-query-editor-help.md">}})
+  - [Add variables]({{< relref "add-support-for-variables.md">}})
+  - [Create panel option editors]({{< relref "custom-panel-option-editors.md">}})
+- [Sign a plugin]({{< relref "sign-a-plugin.md">}})
+- [Automate development with CI](https://grafana.github.io/plugin-tools/docs/ci)
+- [Create nested plugins](https://grafana.github.io/plugin-tools/docs/nested-plugins)
+- [Extend configurations](https://grafana.github.io/plugin-tools/docs/advanced-configuration)

docs/sources/developers/plugins/cross-plugin-linking.md

@@ -1,21 +1,25 @@
 ---
-title: Cross plugin links
+title: Work with cross-plugin links
 description: Learn how to add plugin links to a Grafana app plugin
 ---
 
-# Cross plugin links
+# Work with cross-plugin links
 
-Using the Plugin extensions API, App plugins can register extension points of their own to display other plugins links. This cross-plugin linking creates a more immersive user experience for installed plugins.
+With the Plugins extension API, app plugins can register extension points of their own to display other plugins links. This is called _cross-plugin linking_, and you can use it to create more immersive user experiences with installed plugins.
 
 ## Available extension points within plugins
 
-An extension point is a location in another plugins UI where your plugin can insert links. All extension point ids within plugins should follow the naming convention `plugins/<plugin-id>/<extension-point-id>`.
+An extension point is a location in another plugin's UI where your plugin can insert links. All extension point IDs within plugins should follow the naming convention `plugins/<plugin-id>/<extension-point-id>`.
 
 ## How to create an extension point within a plugin
 
-The `getPluginExtensions` method in `@grafana/runtime` can be used to create an extension point within your plugin. An extension point is a way of specifying where in the plugin UI other plugins links are rendered. `getPluginExtensions` takes an object consisting of the `extensionPointId`, which must begin `plugin/<pluginId>`, and any contextual information you would like to provide. It returns a list of `extensionLinks` that your program can loop over.
+Use the `getPluginExtensions` method in `@grafana/runtime` to create an extension point within your plugin. An extension point is a way to specify where in the plugin UI other plugins links are rendered.
 
-_Note: Creating a extension point in a plugin creates a public interface for other plugins to interact with. Changes to the extension point id or the context it passes could break any plugin that attempts to register a link inside your plugin._
+{{% admonition type="note" %}}
+Creating an extension point in a plugin creates a public interface for other plugins to interact with. Changes to the extension point ID or its context could break any plugin that attempts to register a link inside your plugin.
+{{% /admonition %}}
+
+The `getPluginExtensions` method takes an object consisting of the `extensionPointId`, which must begin `plugin/<pluginId>`, and any contextual information that you want to provide. The `getPluginExtensions` method returns a list of `extensionLinks` that your program can loop over:
 
 ```typescript
 import { getPluginExtensions } from '@grafana/runtime';
@@ -52,13 +56,13 @@ function AppExtensionPointExample() {
 }
 ```
 
-In the above example, we created a component that renders `<LinkButton />` components for all link extensions other plugins registered for the `plugin/another-app-plugin/menu` extension point id. We pass the context as the second parameter to `getPluginExtensions`, which will use `Object.freeze` to make the context immutable before passing it to other plugins.
+The preceding example shows a component that renders `<LinkButton />` components for all link extensions that other plugins registered for the `plugin/another-app-plugin/menu` extension point ID. The context is passed as the second parameter to `getPluginExtensions`, which uses `Object.freeze` to make the context immutable before passing it to other plugins.
 
-## How to insert links into another plugin
+## Insert links into another plugin
 
-Create links for other plugins in the same way you would [extend the Grafana application UI]({{< relref "./extend-the-grafana-ui-with-links" >}}) with a link. Rather than specify a `grafana/...` extension point, specify the plugin extension point `plugin/<pluginId>/<extensionPointId>` instead. Given the example above, use a plugin link such as the following.
+Create links for other plugins in the same way you [extend the Grafana application UI]({{< relref "./extend-the-grafana-ui-with-links" >}}) with a link. Don't specify a `grafana/...` extension point. Instead, specify the plugin extension point `plugin/<pluginId>/<extensionPointId>`.
 
-### Link example
+Given the preceding example, use a plugin link such as the following:
 
 ```typescript
 new AppPlugin().configureExtensionLink({

docs/sources/developers/plugins/custom-panel-option-editors.md

@@ -1,12 +1,17 @@
 ---
-title: Custom panel option editors
+title: Build a custom panel option editor
 ---
 
-# Custom panel option editors
+# Build a custom panel option editor
 
-The Grafana plugin platform comes with a range of editors that allow your users to customize a panel. The standard editors cover the most common types of options, such as text input and boolean switches. If you don't find the editor you're looking for, you can build your own. In this guide, you'll learn how to build your own panel option editor.
+The Grafana plugin platform comes with a range of editors that allow your users to customize a panel. The standard editors cover the most common types of options, such as text input and boolean switches. If you don't find the editor you're looking for, you can build your own.
 
-The simplest editor is a React component that accepts two props: `value` and `onChange`. `value` contains the current value of the option, and `onChange` updates it.
+## Panel option editor basics
+
+The simplest editor is a React component that accepts two props:
+
+- **`value`**: the current value of the option
+- **`onChange`**: updates the option's value
 
 The editor in the example below lets the user toggle a boolean value by clicking a button:
 
@@ -22,7 +27,7 @@ export const SimpleEditor = ({ value, onChange }: StandardEditorProps<boolean>)
 };
 ```
 
-To use a custom panel option editor, use the `addCustomEditor` on the `OptionsUIBuilder` object in your `module.ts` file. Configure the editor to use by setting the `editor` property to the `SimpleEditor` component.
+To use a custom panel option editor, use the `addCustomEditor` on the `OptionsUIBuilder` object in your `module.ts` file and set the `editor` property to the name of your custom editor component.
 
 **module.ts**
 
@@ -39,9 +44,9 @@ export const plugin = new PanelPlugin<SimpleOptions>(SimplePanel).setPanelOption
 
 ## Add settings to your panel option editor
 
-If you're using your custom editor to configure multiple options, you might want to be able to customize it. Add settings to your editor by setting the second template variable of `StandardEditorProps` to an interface that contains the settings you want to be able to configure.
+You can use your custom editor to customize multiple possible settings. To add settings to your editor, set the second template variable of `StandardEditorProps` to an interface that contains the settings you want to configure. Access the editor settings through the `item` prop.
 
-You can access the editor settings through the `item` prop. Here's an example of an editor that populates a drop-down with a range of numbers. The range is defined by the `from` and `to` properties in the `Settings` interface.
+Here's an example of an editor that populates a drop-down with a range of numbers. The `Settings` interface defines the range of the `from` and `to` properties.
 
 **SimpleEditor.tsx**
 
@@ -71,7 +76,7 @@ export const SimpleEditor = ({ item, value, onChange }: Props) => {
 };
 ```
 
-You can now configure the editor for each option, by configuring the `settings` property in the call to `addCustomEditor`.
+You can now configure the editor for each option by configuring the `settings` property to call `addCustomEditor`:
 
 ```ts
 export const plugin = new PanelPlugin<SimpleOptions>(SimplePanel).setPanelOptions((builder) => {
@@ -90,9 +95,7 @@ export const plugin = new PanelPlugin<SimpleOptions>(SimplePanel).setPanelOption
 
 ## Use query results in your panel option editor
 
-Option editors can access the results from the last query. This lets you update your editor dynamically, based on the data returned by the data source.
-
-> **Note:** This feature was introduced in 7.0.3. Anyone using an older version of Grafana will see an error when using your plugin.
+Option editors can access the results from the last query. This lets you update your editor dynamically based on the data returned by the data source.
 
 The editor context is available through the `context` prop. The data frames returned by the data source are available under `context.data`.
 
@@ -116,5 +119,3 @@ export const SimpleEditor = ({ item, value, onChange, context }: StandardEditorP
   return <Select options={options} value={value} onChange={(selectableValue) => onChange(selectableValue.value)} />;
 };
 ```
-
-Have you built a custom editor that you think would be useful to other plugin developers? Consider contributing it as a standard editor!

docs/sources/developers/plugins/data-frames.md

@@ -6,7 +6,7 @@ title: Data frames
 
 Grafana supports a variety of different data sources, each with its own data model. To make this possible, Grafana consolidates the query results from each of these data sources into one unified data structure called a _data frame_.
 
-The data frame structure is a concept that's borrowed from data analysis tools like the [R programming language](https://www.r-project.org), and [Pandas](https://pandas.pydata.org/).
+The data frame structure is a concept that's borrowed from data analysis tools like the [R programming language](https://www.r-project.org) and [Pandas](https://pandas.pydata.org/).
 
 > Data frames are available in Grafana 7.0+, and replaced the Time series and Table structures with a more generic data structure that can support a wider range of data types.
 
@@ -163,7 +163,7 @@ Dimensions: 5 fields by 2 rows
 +---------------------+------------------+------------------+------------------+------------------+
 ```
 
-> **Note:** Not all panels support the wide time series data frame format. To keep full backward compatibility we have introduced a transformation that can be used to convert from the wide to the long format. For usage information, refer to the [Prepare time series-transformation]({{< relref "../../panels-visualizations/query-transform-data/transform-data/#prepare-time-series" >}}).
+> **Note:** Not all panels support the wide time series data frame format. To keep full backward compatibility we've introduced a transformation that can be used to convert from the wide to the long format. For usage information, refer to the [Prepare time series-transformation]({{< relref "../../panels-visualizations/query-transform-data/transform-data/#prepare-time-series" >}}).
 
 ## Technical references
 

docs/sources/developers/plugins/development-with-local-grafana.md

@@ -1,24 +1,24 @@
 ---
-title: Development with local Grafana
+title: Develop with a local environment
 ---
 
-# Development with local Grafana
+# Develop with a local environment
 
-This guide allows you to setup a development environment where you run Grafana and your plugin locally. With this, you will be able to see your changes as you add them.
+Follow the steps in this guide to set up a development environment where you run Grafana and your plugin locally. With this setup, you can see your changes as you add them.
 
 ## Run Grafana in your host
 
-If you have git, Go and the required version of NodeJS in your system, you can clone and run Grafana locally:
+To clone and run Grafana locally:
 
-1. Download and set up Grafana. You can find instructions on how to do it in the [developer-guide](https://github.com/grafana/grafana/blob/HEAD/contribute/developer-guide.md).
+1. Download and set up Grafana. Refer to the [developer-guide](https://github.com/grafana/grafana/blob/HEAD/contribute/developer-guide.md).
 
-2. Grafana will look for plugins, by default, on its `data/plugins` directory. You can create a symbolic link to your plugin repository to detect new changes:
+2. Grafana looks for plugins, by default, in its `data/plugins` directory. You can create a symbolic link to your plugin repository to detect new changes:
 
    ```bash
    ln -s <plugin-path>/dist data/plugins/<plugin-name>
    ```
 
-3. (Optional) If the step above doesn't work for you (e.g. you are running on Windows), you can also modify the default path in the Grafana configuration (that can be found at `conf/custom.ini`) and point to the directory with your plugin:
+3. Optional: If the preceding step doesn't work for you (for example, if you are running on Windows), then modify the default path in the Grafana configuration. Find the default path at `conf/custom.ini`) and point it to your plugin's directory:
 
    ```ini
    [paths]
@@ -27,9 +27,11 @@ If you have git, Go and the required version of NodeJS in your system, you can c
 
 ## Run Grafana with docker-compose
 
-Another possibility is to run Grafana with docker-compose so it runs in a container. For doing so, create the docker-compose file in your plugin directory:
+Another option is to run Grafana with docker-compose so that it runs in a container. To do so, create the `docker-compose` file in your plugin directory.
 
-**NOTE**: Some plugins already include a docker-compose file so you can skip this step.
+{{% admonition type="note" %}}
+If your plugin already includes a docker-compose file, then skip this step.
+{{% /admonition %}}
 
 ```yaml
 version: '3.7'
@@ -41,7 +43,7 @@ services:
     ports:
       - 3000:3000/tcp
     volumes:
-      # Use your plugin folder (e.g. redshift-datasource)
+      # Use your plugin folder (for example, redshift-datasource)
       - ./dist:/var/lib/grafana/plugins/<plugin-folder>
       - ./provisioning:/etc/grafana/provisioning
     environment:
@@ -51,9 +53,9 @@ services:
       - GF_DEFAULT_APP_MODE=development
 ```
 
-## Run your plugin
+## Run your plugin in development mode
 
-Finally start your plugin in development mode. Go to your plugin root directory and follow these steps:
+Finally, start your plugin in development mode. Go to your plugin's root directory and follow these steps:
 
 1. Build your plugin backend and start the frontend in watch mode:
 
@@ -62,9 +64,9 @@ Finally start your plugin in development mode. Go to your plugin root directory
    yarn watch
    ```
 
-2. Start Grafana backend and frontend:
+2. Start the Grafana backend and frontend:
 
-   2.1 For a local copy of Grafana, go to the directory with Grafana source code and run:
+   1. For a local copy of Grafana, go to the directory with Grafana source code and run:
 
    ```bash
    make run
@@ -74,25 +76,29 @@ Finally start your plugin in development mode. Go to your plugin root directory
    yarn start
    ```
 
-   2.2 Or with docker-compose, in your plugin directory, run:
+   2. Or, with docker-compose, in your plugin directory, run:
 
    ```bash
    docker-compose up
    ```
 
-After this, you should be able to see your plugin listed in Grafana and test your changes. Note that any change in the fronted will require you to refresh your browser while changes in the backend may require to rebuild your plugin binaries and reload the plugin (`mage && mage reloadPlugin` for local development or `docker-compose up` again if you are using docker-compose).
+After this, you should be able to see your plugin listed in Grafana, and then you can test your changes.
+
+If you make a change in the frontend, you must refresh your browser. However, changes in the backend may require that you rebuild your plugin binaries and reload the plugin (`mage && mage reloadPlugin` for local development, or run `docker-compose up` again if you are using docker-compose).
 
 ## Run your backend plugin with a debugger
 
-> Note: The following method only works with a local Grafana instance and currently doesn't work with Docker.
+{{% admonition type="note" %}}
+The following method only works with a local Grafana instance and currently doesn't work with Docker.
+{{% /admonition %}}
 
-You can run a backend plugin and attach a debugger to it, which allows you to set breakpoints and debug your backend plugin directly from your IDE of choice.
+Running a backend plugin with a debugger is supported in Visual Studio Code and GoLand out of the box, but it can also work with any other IDE or debugger.
 
-We support Visual Studio Code and GoLand out of the box, but this feature can also work with any other IDE or debugger.
+You can run a backend plugin and attach a debugger to it, which allows you to set breakpoints and debug your backend plugin directly from your IDE of choice:
 
 1. Go to your plugin's folder.
 
-1. Check your `go.mod` and make sure `grafana-plugin-sdk-go` is at least on `v0.156.0`
+1. Check your `go.mod` to make sure `grafana-plugin-sdk-go` are at least on `v0.156.0`
    - If not, update it to the latest version:
      ```
      go get -u github.com/grafana/grafana-plugin-sdk-go
@@ -127,9 +133,9 @@ Now that your plugin is ready to run, follow the instructions bellow for your ID
    ```
 
 1. Press `F5` to run your plugin in debug mode.
-1. Start Grafana, if it's not already running.
+1. If Grafana isn't already running, run it.
 
-> If you re-run the configuration, Grafana will automatically reload the plugin.
+> If you re-run the configuration, Grafana automatically reloads the plugin.
 
 ### GoLand
 
@@ -141,30 +147,32 @@ Now that your plugin is ready to run, follow the instructions bellow for your ID
 
 1. Run the config (with or without the debugger).
 
-1. Start Grafana, if it's not already running.
+1. If Grafana isn't already running, run it.
 
-> If you re-run the configuration, Grafana will automatically reload the plugin.
+{{% admonition type="note" %}}
+If you re-run the configuration, Grafana automatically reloads the plugin.
+{{% /admonition %}}
 
 ### Other IDEs
 
 Configure your code editor to run the following steps:
 
-1. Build the executable with debug flags.
+1. Build the executable file with debug flags.
    ```
    mage build:debug
    ```
-1. Run the plugin's executable (inside `dist`) with `-standalone -debug` flags.
+1. Run the plugin's executable file (inside `dist`) with `-standalone -debug` flags.
    ```
    ./gpx_xyz_linux_amd64 -standalone -debug
    ```
 1. Attach a debugger to the process.
 
-Then, you can start Grafana, if it's not already running.
+1. If Grafana isn't already running, run it.
 
-> If you re-run the configuration, Grafana will automatically reload the plugin.
+> If you re-run the configuration, Grafana automatically reloads the plugin.
 
 ### Notes
 
 - All logs are printed in the plugin's `stdout` rather than in Grafana logs.
-- If the backend plugin doesn't serve requests after turning off debug mode, you can force reset the standalone mode. To do so, delete the files `dist/standalone.txt` and `dist/pid.txt` alongside the executable file, and then restart Grafana.
-- We currently do not support debugging backend plugins running inside Docker.
+- If the backend plugin doesn't serve requests after you turn off debug mode, you can force a reset to the standalone mode. To do so, delete the files `dist/standalone.txt`, `dist/pid.txt`, and the executable file, and then restart Grafana.
+- Grafana doesn't support debugging backend plugins running inside Docker. But this is a [planned enhancement](https://github.com/grafana/grafana-plugin-sdk-go/issues/685).

docs/sources/developers/plugins/extend-the-grafana-ui-with-links.md

@@ -1,46 +1,58 @@
 ---
-title: Extend the Grafana UI with links
-description: Learn how to add links to the Grafana user interface from an App plugin
+title: Use extensions to add links to app plugins
+description: Learn how to add links to the Grafana user interface from an app plugin
 ---
 
-# Extend the Grafana UI with links
+# Use extensions to add links to app plugins
 
-Use the Plugin extensions API with your Grafana App plugins to add links to the Grafana UI. Doing so allows you to direct users to your plugins pages from various "extension points" within the Grafana application.
+You can use the Plugin extensions API with your Grafana app plugins to add links to the Grafana UI. This feature lets you send users to your plugin's pages from other spots in the Grafana application.
 
-For a plugin to successfully register links it must:
+## Before you begin
 
-- Be an App plugin.
-- Be [preloaded]({{< relref "./metadata" >}}).
-- Be installed and enabled.
+Be sure your plugin meets the following requirements before proceeding:
+
+- It must be an app plugin.
+- It must be preloaded (by setting the [preload property]({{< relref "./metadata" >}}) to `true` in the `plugin.json`
+- It must be installed and enabled.
 
 ## Available extension points within Grafana
 
-An extension point is a location within the Grafana application UI where a plugin can insert links. All extension points within Grafana start with `grafana/`. The following extension point ids are available:
+An _extension point_ is a location within the Grafana UI where a plugin can insert links. The IDs of all extension points within Grafana start with `grafana/`. For example, you can use the following extension point ID:
 
-- `grafana/dashboard/panel/menu`: all panel menu dropdowns found in dashboards
+- `grafana/dashboard/panel/menu`: extension point for all panel dropdown menus in dashboards
 
-## Add a link extension within Grafana
+## Add a link extension within a Grafana dashboard panel menu
 
-Here's how you can add a link to the dashboard panel menus in Grafana via your plugin:
+To add a link extension within a Grafana dashboard panel menu, complete the following steps:
 
-Define the link extension in your plugin's `module.ts` file. First, define a new instance of the `AppPlugin` class by using the `configureExtensionLink` method. This method takes an object that describes your link extension, including a `title` property for the link text, a `extensionPointId` that tells Grafana where the link should appear, and a `path` for the user to navigate to your plugin.
+1. Define the link extension in your plugin's `module.ts` file.
+
+1. Define a new instance of the `AppPlugin` class by using the `configureExtensionLink` method. This method requires:
+   - an object that describes your link extension, including a `title` property for the link text
+   - an `extensionPointId` method that tells Grafana where the link should appear
+   - a `path` for the user to go to your plugin
 
 ```typescript
 new AppPlugin().configureExtensionLink({
   title: 'Go to basic app',
-  description: 'Will navigate the user to the basic app',
+  description: 'Will send the user to the basic app',
   extensionPointId: 'grafana/dashboard/panel/menu',
   path: '/a/myorg-basic-app/one', // Must start with "/a/<PLUGIN_ID>/"
 });
 ```
 
-That's it! Your link will be displayed in dashboard panel menus. When the user clicks the link, they will be navigated to the path you defined earlier.
+Your link will now appear in dashboard panel menus. When the user clicks the link, they will be sent to the path you defined earlier.
 
-_Note: Each plugin is limited to a maximum of two links per extension point._
+{{% admonition type="note" %}} Each plugin is limited to a maximum of two links per extension point.{{%
+/admonition %}}
 
 ## Add a link extension using context within Grafana
 
-The above example works for simple cases however you may want to act on information from the panel the user is navigating from. This can be achieved by making use of the `configure` property which takes a function and returns an object that consists of a `title` property for the link text, a `path` to navigate the user to your plugin. Alternatively this function may return `undefined` if there's a need to hide the link for certain scenarios.
+The above example works for simple cases. However, you may want to act on information from the app's panel from which the user is navigating.
+
+To do this, use the `configure` property on the object that is passed to `configureExtensionLink()`. This property takes a function and returns an object that consists of a `title` property for the link text and a `path` to send the user to your plugin.
+
+Alternatively, if you need to hide the link for certain scenarios, define the function to return _undefined_:
 
 ```typescript
 new AppPlugin().configureExtensionLink({
@@ -71,20 +83,21 @@ new AppPlugin().configureExtensionLink({
 });
 ```
 
-The above example demonstrates how to return a different link `path` based on which plugin the dashboard panel is using. If the clicked-upon panel is neither a timeseries nor a piechart panel, then the configure function returns `undefined` and the link isn't rendered.
+The above example demonstrates how to return a different `path` based on which plugin the dashboard panel is using. If the clicked-upon panel is neither a time series nor a pie chart panel, then the `configure()` function returns _undefined_. When this happens, Grafana doesn't render the link.
 
-_Note: The context passed to the `configure` function is bound by the `extensionPointId` the link is inserted into. Different extension points contain different contexts._
+{{% admonition type="note" %}} The context passed to the `configure()` function is bound by the `extensionPointId` into which you insert the link. Different extension points contain different contexts.{{%
+/admonition %}}
 
-## Add an onClick event handler to a link
+## Add an event handler to a link
 
-Link extensions provide the means to direct users to a plugin page via href links within the Grafana UI. They can also trigger onClick events to perform dynamic actions when clicked.
+Link extensions give you the means to direct users to a plugin page via href links within the Grafana UI. You can also use them to trigger `onClick` events to perform dynamic actions when clicked.
 
-Here's how you can add an onClick handler to a link in the dashboard panel menus of Grafana via your plugin:
+To add an event handler to a link in a panel menu, complete the following steps:
 
 1. Define the link extension in the plugin's `module.ts` file.
-2. Create a new instance of the `AppPlugin` class, again using the `configureExtensionLink` method. This time we add an `onClick` property which takes a function. This function receives the click `event` plus, an object consisting of the `context` and an `openModal` function.
+1. Create a new instance of the `AppPlugin` class, again using the `configureExtensionLink` method. This time, add an `onClick` property which takes a function. This function receives the click event and an object consisting of the `context` and an `openModal` function.
 
-In the following example, we open a modal.
+In the following example, we open a dialog.
 
 ```typescript
 new AppPlugin().configureExtensionLink({
@@ -95,7 +108,7 @@ new AppPlugin().configureExtensionLink({
   onClick: (event, { context, openModal }) => {
     event.preventDefault();
     openModal({
-      title: 'My plugin modal',
+      title: 'My plugin dialog',
       body: ({ onDismiss }) => <SampleModal onDismiss={onDismiss} pluginId={context?.pluginId} />,
     });
   },
@@ -109,11 +122,11 @@ type Props = {
 const SampleModal = ({ onDismiss, pluginId }: Props) => {
   return (
     <VerticalGroup spacing="sm">
-      <p>This modal was opened via the plugin extensions API.</p>
+      <p>This dialog was opened via the plugin extensions API.</p>
       <p>The panel is using a {pluginId} plugin to display data.</p>
     </VerticalGroup>
   );
 };
 ```
 
-The plugin extensions API is a powerful feature for you to insert links into the UI of Grafana applications that send users to plugin features or trigger actions based on where the user clicked. This feature can also be used for [cross plugin linking]({{< relref "./cross-plugin-linking" >}}).
+As you can see, the plugin extensions API enables you to insert links into the UI of Grafana applications that send users to plugin features or trigger actions based on where the user clicked. The plugins extension API can also be used for [cross-plugin linking]({{< relref "./cross-plugin-linking" >}}).

docs/sources/developers/plugins/get-started-with-plugins/_index.md

@@ -0,0 +1,12 @@
+---
+description: Get started guide
+title: Get started with plugins
+---
+
+# Get started with Grafana plugins
+
+This section contains guidance for building plugins.
+
+- [Get started with creating a plugin](https://grafana.github.io/plugin-tools/docs/getting-started)
+- [Types of Grafana plugins](https://grafana.com/docs/grafana/latest/administration/plugin-management/)
+- [Set up your development environment](https://grafana.github.io/plugin-tools/docs/docker)

docs/sources/developers/plugins/introduction-to-plugin-development/_index.md

@@ -0,0 +1,13 @@
+---
+description: Conceptual topics for plugin development
+title: Introduction to plugin development
+---
+
+# Introduction to Grafana plugin development
+
+This section contains topics related to the key concepts for Grafana plugin development.
+
+- [Backend plugins]({{< relref "../backend/" >}})
+  - [Grafana plugin SDK for Go]({{< relref "../backend/grafana-plugin-sdk-for-go.md" >}})
+  - [Plugin protocol]({{< relref "../backend/plugin-protocol.md" >}})
+- [Data frames]({{< relref "data-frames.md">}})

docs/sources/developers/plugins/migration-guide/v9.x-v10.x/_index.md

@@ -1,26 +0,0 @@
----
-description: Guide for migrating plugins from Grafana v9.x to v10.x
-keywords:
-  - grafana
-  - plugins
-  - migration
-  - plugin
-  - documentation
-title: Migrating plugins from Grafana 9.x to 10.x
-menutitle: v9.x to v10.x
-weight: 1900
----
-
-# Migrating plugins from Grafana version 9.x to 10.x
-
-## Verifying plugin behaviour with React 18
-
-Grafana 10 includes our upgrade to React 18 and use of the new React client rendering API. These changes were delivered to the core `grafana` repo with [PR 64428](https://github.com/grafana/grafana/pull/64428).
-
-Whilst this brings us many significant benefits, there's a potential for this to impact the way your plugin works. In particular, there could be unintended side effects caused by the changes around improving consistency with `useEffect` timings and automatic batching of state updates.
-
-Recommended actions:
-
-- Review the React 18 [upgrade docs](https://react.dev/blog/2022/03/08/react-18-upgrade-guide)
-- Test your plugins against one of the latest [grafana-dev docker images](https://hub.docker.com/r/grafana/grafana-dev/tags?page=1) (for example, [this one](https://hub.docker.com/layers/grafana/grafana-dev/10.0.0-111404pre/images/sha256-ac78acf54b44bd2ce7e68b796b1df47030da7f35e53b02bc3eec3f4de05f780f?context=explore))
-- Add a comment to the [forum discussion](https://community.grafana.com/t/grafana-10-is-upgrading-to-react-18/86051) if your plugin is impacted in any way. Either to socialise the changes needed for your plugin or to reach out and ask for help yourself.