[DOCS] Add missing descriptions for metrics.alert.threshold rule (#213181)

oas_docs/output/kibana.serverless.yaml

@@ -73015,6 +73015,8 @@ components:
                     type: array
                     items:
                       type: number
+                    description: |
+                      The threshold value that is used with the `comparator`. If the `comparator` is `between`, you must specify the boundary values.
                   comparator:
                     type: string
                     enum:
@@ -73024,14 +73026,27 @@ components:
                       - '>='
                       - between
                       - outside
+                    description: |
+                      The comparison function for the threshold. For example, "is above", "is above or equals", "is below", "is below or equals", "is between", and "outside".
                   timeUnit:
                     type: string
+                    enum:
+                      - s
+                      - m
+                      - h
+                      - d
+                    description: |
+                      The type of units for the time window: seconds, minutes, hours, or days.
                   timeSize:
                     type: number
+                    description: |
+                      The size of the time window (in `timeUnit` units), which determines how far back to search for documents. Generally it should be a value higher than the rule check interval to avoid gaps in detection.
                   warningThreshold:
                     type: array
                     items:
                       type: number
+                    description: |
+                      The threshold value that is used with the `warningComparator`. If the `warningComparator` is `between`, you must specify the boundary values.
                   warningComparator:
                     type: string
                     enum:
@@ -73074,8 +73089,17 @@ components:
                       - outside
                   timeUnit:
                     type: string
+                    enum:
+                      - s
+                      - m
+                      - h
+                      - d
+                    description: |
+                      The type of units for the time window: seconds, minutes, hours, or days.
                   timeSize:
                     type: number
+                    description: |
+                      The size of the time window (in `timeUnit` units), which determines how far back to search for documents. Generally it should be a value higher than the rule check interval to avoid gaps in detection.
                   warningThreshold:
                     type: array
                     items:
@@ -73111,8 +73135,17 @@ components:
                       - outside
                   timeUnit:
                     type: string
+                    enum:
+                      - s
+                      - m
+                      - h
+                      - d
+                    description: |
+                      The type of units for the time window: seconds, minutes, hours, or days.
                   timeSize:
                     type: number
+                    description: |
+                      The size of the time window (in `timeUnit` units), which determines how far back to search for documents. Generally it should be a value higher than the rule check interval to avoid gaps in detection.
                   warningThreshold:
                     type: array
                     items:
@@ -73146,6 +73179,8 @@ components:
                                 - max
                                 - min
                                 - cardinality
+                              description: |
+                                An aggregation to gather data for the rule. For example, find the average, highest or lowest value of a numeric field. Or use a cardinality aggregation to find the approximate number of unique values in a field. 
                             field:
                               type: string
                         - type: object
@@ -73168,14 +73203,22 @@ components:
             - type: array
               items:
                 type: string
+          description: |
+            Create an alert for every unique value of the specified fields. For example, you can create a rule per host or every mount point of each host.
+            IMPORTANT: If you include the same field in both the `filterQuery` and `groupBy`, you might receive fewer results than you expect. For example, if you filter by `cloud.region: us-east`, grouping by `cloud.region` will have no effect because the filter query can match only one region.
         filterQuery:
           type: string
+          description: |
+            A query that limits the scope of the rule. The rule evaluates only metric data that matches the query.
         sourceId:
           type: string
         alertOnNoData:
           type: boolean
+          description: If true, an alert occurs if the metrics do not report any data over the expected period or if the query fails.
         alertOnGroupDisappear:
           type: boolean
+          description: |
+            If true, an alert occurs if a group that previously reported metrics does not report them again over the expected time period. This check is not recommended for dynamically scaling infrastructures that might rapidly start and stop nodes automatically.
     params_property_slo_burn_rate:
       properties:
         sloId:

oas_docs/output/kibana.yaml

@@ -82922,6 +82922,8 @@ components:
                     type: array
                     items:
                       type: number
+                    description: |
+                      The threshold value that is used with the `comparator`. If the `comparator` is `between`, you must specify the boundary values.
                   comparator:
                     type: string
                     enum:
@@ -82931,14 +82933,27 @@ components:
                       - '>='
                       - between
                       - outside
+                    description: |
+                      The comparison function for the threshold. For example, "is above", "is above or equals", "is below", "is below or equals", "is between", and "outside".
                   timeUnit:
                     type: string
+                    enum:
+                      - s
+                      - m
+                      - h
+                      - d
+                    description: |
+                      The type of units for the time window: seconds, minutes, hours, or days.
                   timeSize:
                     type: number
+                    description: |
+                      The size of the time window (in `timeUnit` units), which determines how far back to search for documents. Generally it should be a value higher than the rule check interval to avoid gaps in detection.
                   warningThreshold:
                     type: array
                     items:
                       type: number
+                    description: |
+                      The threshold value that is used with the `warningComparator`. If the `warningComparator` is `between`, you must specify the boundary values.
                   warningComparator:
                     type: string
                     enum:
@@ -82981,8 +82996,17 @@ components:
                       - outside
                   timeUnit:
                     type: string
+                    enum:
+                      - s
+                      - m
+                      - h
+                      - d
+                    description: |
+                      The type of units for the time window: seconds, minutes, hours, or days.
                   timeSize:
                     type: number
+                    description: |
+                      The size of the time window (in `timeUnit` units), which determines how far back to search for documents. Generally it should be a value higher than the rule check interval to avoid gaps in detection.
                   warningThreshold:
                     type: array
                     items:
@@ -83018,8 +83042,17 @@ components:
                       - outside
                   timeUnit:
                     type: string
+                    enum:
+                      - s
+                      - m
+                      - h
+                      - d
+                    description: |
+                      The type of units for the time window: seconds, minutes, hours, or days.
                   timeSize:
                     type: number
+                    description: |
+                      The size of the time window (in `timeUnit` units), which determines how far back to search for documents. Generally it should be a value higher than the rule check interval to avoid gaps in detection.
                   warningThreshold:
                     type: array
                     items:
@@ -83053,6 +83086,8 @@ components:
                                 - max
                                 - min
                                 - cardinality
+                              description: |
+                                An aggregation to gather data for the rule. For example, find the average, highest or lowest value of a numeric field. Or use a cardinality aggregation to find the approximate number of unique values in a field. 
                             field:
                               type: string
                         - type: object
@@ -83075,14 +83110,22 @@ components:
             - type: array
               items:
                 type: string
+          description: |
+            Create an alert for every unique value of the specified fields. For example, you can create a rule per host or every mount point of each host.
+            IMPORTANT: If you include the same field in both the `filterQuery` and `groupBy`, you might receive fewer results than you expect. For example, if you filter by `cloud.region: us-east`, grouping by `cloud.region` will have no effect because the filter query can match only one region.
         filterQuery:
           type: string
+          description: |
+            A query that limits the scope of the rule. The rule evaluates only metric data that matches the query.
         sourceId:
           type: string
         alertOnNoData:
           type: boolean
+          description: If true, an alert occurs if the metrics do not report any data over the expected period or if the query fails.
         alertOnGroupDisappear:
           type: boolean
+          description: |
+            If true, an alert occurs if a group that previously reported metrics does not report them again over the expected time period. This check is not recommended for dynamically scaling infrastructures that might rapidly start and stop nodes automatically.
     params_property_slo_burn_rate:
       properties:
         sloId:

src/platform/packages/shared/response-ops/rule_params/metric_threshold/v1.ts

@@ -32,11 +32,34 @@ const METRIC_EXPLORER_AGGREGATIONS = [
 const comparator = Object.values({ ...COMPARATORS, ...LEGACY_COMPARATORS });
 
 const baseCriterion = {
-  threshold: schema.arrayOf(schema.number()),
+  threshold: schema.arrayOf(schema.number(), {
+    meta: {
+      description:
+        'The threshold value that is used with the `comparator`. If the `comparator` is `between`, you must specify the boundary values.',
+    },
+  }),
   comparator: oneOfLiterals(comparator),
-  timeUnit: schema.string(),
+  timeUnit: schema.string({
-  timeSize: schema.number(),
+    meta: {
-  warningThreshold: schema.maybe(schema.arrayOf(schema.number())),
+      description: 'The type of units for the time window: seconds, minutes, hours, or days.',
+    },
+  }),
+  timeSize: schema.number({
+    meta: {
+      description:
+        'The size of the time window (in `timeUnit` units), which determines how far back to search for documents. Generally it should be a value higher than the rule check interval to avoid gaps in detection.',
+    },
+  }),
+  warningThreshold: schema.maybe(
+    schema.arrayOf(
+      schema.number({
+        meta: {
+          description:
+            'The threshold value that is used with the `warningComparator`. If the `warningComparator` is `between`, you must specify the boundary values.',
+        },
+      })
+    )
+  ),
   warningComparator: schema.maybe(oneOfLiterals(comparator)),
 };
 
@@ -85,15 +108,40 @@ const customCriterion = schema.object({
 export const metricThresholdRuleParamsSchema = schema.object(
   {
     criteria: schema.arrayOf(schema.oneOf([countCriterion, nonCountCriterion, customCriterion])),
-    groupBy: schema.maybe(schema.oneOf([schema.string(), schema.arrayOf(schema.string())])),
+    groupBy: schema.maybe(
+      schema.oneOf([schema.string(), schema.arrayOf(schema.string())], {
+        meta: {
+          description:
+            'Create an alert for every unique value of the specified fields. For example, you can create a rule per host or every mount point of each host. IMPORTANT: If you include the same field in both the `filterQuery` and `groupBy`, you might receive fewer results than you expect. For example, if you filter by `cloud.region: us-east`, grouping by `cloud.region` will have no effect because the filter query can match only one region.',
+        },
+      })
+    ),
     filterQuery: schema.maybe(
       schema.string({
         validate: validateIsStringElasticsearchJSONFilter,
+        meta: {
+          description:
+            'A query that limits the scope of the rule. The rule evaluates only metric data that matches the query.',
+        },
       })
     ),
     sourceId: schema.string(),
-    alertOnNoData: schema.maybe(schema.boolean()),
+    alertOnNoData: schema.maybe(
-    alertOnGroupDisappear: schema.maybe(schema.boolean()),
+      schema.boolean({
+        meta: {
+          description:
+            'If true, an alert occurs if the metrics do not report any data over the expected period or if the query fails.',
+        },
+      })
+    ),
+    alertOnGroupDisappear: schema.maybe(
+      schema.boolean({
+        meta: {
+          description:
+            'If true, an alert occurs if a group that previously reported metrics does not report them again over the expected time period. This check is not recommended for dynamically scaling infrastructures that might rapidly start and stop nodes automatically.',
+        },
+      })
+    ),
   },
   { unknowns: 'allow' }
 );

x-pack/solutions/observability/plugins/infra/server/lib/alerting/docs/params_property_infra_metric_threshold.yaml

@@ -12,6 +12,9 @@ properties:
               type: array
               items:
                 type: number
+              description: >
+                The threshold value that is used with the `comparator`.
+                If the `comparator` is `between`, you must specify the boundary values.
             comparator:
               type: string
               enum:
@@ -21,14 +24,30 @@ properties:
                 - ">="
                 - "between"
                 - "outside"
+              description: >
+                The comparison function for the threshold.
+                For example, "is above", "is above or equals", "is below", "is below or equals", "is between", and "outside".
             timeUnit:
               type: string
+              enum:
+                - s
+                - m
+                - h
+                - d
+              description: >
+                The type of units for the time window: seconds, minutes, hours, or days.
             timeSize:
               type: number
+              description: >
+                 The size of the time window (in `timeUnit` units), which determines how far back to search for documents.
+                 Generally it should be a value higher than the rule check interval to avoid gaps in detection.
             warningThreshold:
               type: array
               items:
                 type: number
+              description: >
+                The threshold value that is used with the `warningComparator`.
+                If the `warningComparator` is `between`, you must specify the boundary values.
             warningComparator:
               type: string
               enum:
@@ -53,7 +72,6 @@ properties:
                 - "p95"
                 - "p99"
                 - "custom"
-
         - title: count criterion
           type: object
           properties:
@@ -72,8 +90,18 @@ properties:
                 - "outside"
             timeUnit:
               type: string
+              enum:
+                - s
+                - m
+                - h
+                - d
+              description: >
+                The type of units for the time window: seconds, minutes, hours, or days.
             timeSize:
               type: number
+              description: >
+                 The size of the time window (in `timeUnit` units), which determines how far back to search for documents.
+                 Generally it should be a value higher than the rule check interval to avoid gaps in detection.
             warningThreshold:
               type: array
               items:
@@ -110,8 +138,18 @@ properties:
                 - "outside"
             timeUnit:
               type: string
+              enum:
+                - s
+                - m
+                - h
+                - d
+              description: >
+                The type of units for the time window: seconds, minutes, hours, or days.
             timeSize:
               type: number
+              description: >
+                 The size of the time window (in `timeUnit` units), which determines how far back to search for documents.
+                 Generally it should be a value higher than the rule check interval to avoid gaps in detection.
             warningThreshold:
               type: array
               items:
@@ -145,6 +183,10 @@ properties:
                           - "max"
                           - "min"
                           - "cardinality"
+                        description: >
+                          An aggregation to gather data for the rule.
+                          For example, find the average, highest or lowest value of a numeric field.
+                          Or use a cardinality aggregation to find the approximate number of unique values in a field. 
                       field:
                         type: string
                   - type: object
@@ -167,11 +209,24 @@ properties:
       - type: array
         items:
           type: string
+    description: >
+      Create an alert for every unique value of the specified fields.
+      For example, you can create a rule per host or every mount point of each host.
+
+      IMPORTANT: If you include the same field in both the `filterQuery` and `groupBy`, you might receive fewer results than you expect.
+      For example, if you filter by `cloud.region: us-east`, grouping by `cloud.region` will have no effect because the filter query can match only one region.
   filterQuery:
     type: string
+    description: >
+      A query that limits the scope of the rule.
+      The rule evaluates only metric data that matches the query.
   sourceId:
     type: string
   alertOnNoData:
     type: boolean
+    description: If true, an alert occurs if the metrics do not report any data over the expected period or if the query fails.
   alertOnGroupDisappear:
     type: boolean
+    description: >
+      If true, an alert occurs if a group that previously reported metrics does not report them again over the expected time period.
+      This check is not recommended for dynamically scaling infrastructures that might rapidly start and stop nodes automatically.