From cdacfd6f7941eb80815a40e882f2be2da9eb3372 Mon Sep 17 00:00:00 2001
From: Pepe Cano <825430+ppcano@users.noreply.github.com>
Date: Fri, 13 Jun 2025 11:12:06 +0200
Subject: [PATCH] ui(alerting): Add `NeedHelp` section for the `Missing series
 evaluations to resolve` setting (#105456)

* ui(alerting): Add NeedHelpInfo UI for `Missing series evaluations` setting

* Run `make i18n-extract`

* fix URL linke
---
 .../rule-editor/GrafanaEvaluationBehavior.tsx | 68 ++++++++++++++-----
 .../components/rule-viewer/tabs/Details.tsx   |  2 +-
 public/locales/en-US/grafana.json             | 11 ++-
 3 files changed, 61 insertions(+), 20 deletions(-)

diff --git a/public/app/features/alerting/unified/components/rule-editor/GrafanaEvaluationBehavior.tsx b/public/app/features/alerting/unified/components/rule-editor/GrafanaEvaluationBehavior.tsx
index 1aed92a59c4..38dda76f142 100644
--- a/public/app/features/alerting/unified/components/rule-editor/GrafanaEvaluationBehavior.tsx
+++ b/public/app/features/alerting/unified/components/rule-editor/GrafanaEvaluationBehavior.tsx
@@ -371,30 +371,62 @@ export function GrafanaEvaluationBehaviorStep({
                 label={t('alerting.alert.missing-series-resolve', 'Missing series evaluations to resolve')}
                 description={t(
                   'alerting.alert.description-missing-series-evaluations',
-                  'How many consecutive evaluation intervals with no data for a dimension must pass before the alert state is considered stale and automatically resolved. If no value is provided, the value will default to 2.'
+                  'The number of consecutive evaluation intervals a dimension must be missing before the alert instance becomes stale, and is then automatically resolved and evicted. Defaults to 2 if empty.'
                 )}
                 invalid={!!errors.missingSeriesEvalsToResolve?.message}
                 error={errors.missingSeriesEvalsToResolve?.message}
                 className={styles.inlineField}
                 htmlFor="missing-series-resolve"
               >
-                <Input
-                  placeholder={t(
-                    'alerting.grafana-evaluation-behavior-step.missing-series-resolve-placeholder',
-                    'Default: 2'
-                  )}
-                  id="missing-series-resolve"
-                  {...register('missingSeriesEvalsToResolve', {
-                    pattern: {
-                      value: /^\d+$/,
-                      message: t(
-                        'alerting.grafana-evaluation-behavior-step.message.must-be-a-positive-integer',
-                        'Must be a positive integer.'
-                      ),
-                    },
-                  })}
-                  width={21}
-                />
+                <Stack direction="row" gap={0.5} alignItems="center">
+                  <Input
+                    placeholder={t(
+                      'alerting.grafana-evaluation-behavior-step.missing-series-resolve-placeholder',
+                      'Default: 2'
+                    )}
+                    id="missing-series-resolve"
+                    {...register('missingSeriesEvalsToResolve', {
+                      pattern: {
+                        value: /^\d+$/,
+                        message: t(
+                          'alerting.grafana-evaluation-behavior-step.message.must-be-a-positive-integer',
+                          'Must be a positive integer.'
+                        ),
+                      },
+                    })}
+                    width={21}
+                  />
+                  <NeedHelpInfo
+                    contentText={
+                      <>
+                        <p>
+                          {t(
+                            'alerting.alert-missing-evaluations-to-stale.help-info.text1',
+                            'An alert instance is considered stale if the alert rule query returns data, but the specific dimension (or series) for that alert instance is missing for several consecutive evaluation intervals.'
+                          )}
+                        </p>
+                        <p>
+                          {t(
+                            'alerting.alert-missing-evaluations-to-stale.help-info.text2',
+                            'A stale alert instance is resolved and then evicted.'
+                          )}
+                        </p>
+                        {t(
+                          'alerting.alert-missing-evaluations-to-stale.help-info.text3',
+                          'This setting defines how many consecutive evaluation intervals must pass without data before an alert instance is considered stale. Defaults to 2 if empty.'
+                        )}
+                      </>
+                    }
+                    externalLink={
+                      'https://grafana.com/docs/grafana/latest/alerting/fundamentals/alert-rule-evaluation/stale-alert-instances/'
+                    }
+                    linkText={t(
+                      'alerting.alert-missing-evaluations-to-stale.help-info.link-text',
+                      `Read more about stale alert instances`
+                    )}
+                    title={t('alerting.alert-missing-evaluations-to-stale.help-info.title', 'Stale alert instances')}
+                  />
+                </Stack>
               </Field>
             </>
           )}
diff --git a/public/app/features/alerting/unified/components/rule-viewer/tabs/Details.tsx b/public/app/features/alerting/unified/components/rule-viewer/tabs/Details.tsx
index 9c73991d5ad..bf807f01bd3 100644
--- a/public/app/features/alerting/unified/components/rule-viewer/tabs/Details.tsx
+++ b/public/app/features/alerting/unified/components/rule-viewer/tabs/Details.tsx
@@ -165,7 +165,7 @@ export const Details = ({ rule }: DetailsProps) => {
                 value={missingSeriesEvalsToResolve}
                 tooltipValue={t(
                   'alerting.alert.description-missing-series-evaluations',
-                  'How many consecutive evaluation intervals with no data for a dimension must pass before the alert state is considered stale and automatically resolved. If no value is provided, the value will default to 2.'
+                  'The number of consecutive evaluation intervals a dimension must be missing before the alert instance becomes stale, and is then automatically resolved and evicted. Defaults to 2 if empty.'
                 )}
               />
             )}
diff --git a/public/locales/en-US/grafana.json b/public/locales/en-US/grafana.json
index 1b44960eedc..d1d7dd616c4 100644
--- a/public/locales/en-US/grafana.json
+++ b/public/locales/en-US/grafana.json
@@ -352,7 +352,7 @@
     "alert": {
       "alert-state": "Alert state",
       "annotations": "Annotations",
-      "description-missing-series-evaluations": "How many consecutive evaluation intervals with no data for a dimension must pass before the alert state is considered stale and automatically resolved. If no value is provided, the value will default to 2.",
+      "description-missing-series-evaluations": "The number of consecutive evaluation intervals a dimension must be missing before the alert instance becomes stale, and is then automatically resolved and evicted. Defaults to 2 if empty.",
       "evaluation": "Evaluation",
       "evaluation-paused": "Alert evaluation currently paused",
       "evaluation-paused-description": "Notifications for this rule will not fire and no alert instances will be created until the rule is un-paused.",
@@ -450,6 +450,15 @@
       "silence-notifications": "Silence notifications",
       "with-modifications": "With modifications"
     },
+    "alert-missing-evaluations-to-stale": {
+      "help-info": {
+        "link-text": "Read more about stale alert instances",
+        "text1": "An alert instance is considered stale if the alert rule query returns data, but the specific dimension (or series) for that alert instance is missing for several consecutive evaluation intervals.",
+        "text2": "A stale alert instance is resolved and then evicted.",
+        "text3": "This setting defines how many consecutive evaluation intervals must pass without data before an alert instance is considered stale. Defaults to 2 if empty.",
+        "title": "Stale alert instances"
+      }
+    },
     "alert-recording-rule-form": {
       "evaluation-behaviour": {
         "description": {