From 22b9669d34db2c26828d3dc2c48dd139b7e2ed9f Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Thu, 29 May 2025 20:37:57 -0700 Subject: [PATCH] [DOCS] Add missing descriptions for metrics.alert.threshold rule (#213181) --- oas_docs/output/kibana.serverless.yaml | 43 +++++++++++++ oas_docs/output/kibana.yaml | 43 +++++++++++++ .../rule_params/metric_threshold/v1.ts | 62 ++++++++++++++++--- ...arams_property_infra_metric_threshold.yaml | 59 +++++++++++++++++- 4 files changed, 198 insertions(+), 9 deletions(-) diff --git a/oas_docs/output/kibana.serverless.yaml b/oas_docs/output/kibana.serverless.yaml index 38940dd7baa3..21a673a7126e 100644 --- a/oas_docs/output/kibana.serverless.yaml +++ b/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: diff --git a/oas_docs/output/kibana.yaml b/oas_docs/output/kibana.yaml index 7adf845f370e..ed188ebe3db4 100644 --- a/oas_docs/output/kibana.yaml +++ b/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: diff --git a/src/platform/packages/shared/response-ops/rule_params/metric_threshold/v1.ts b/src/platform/packages/shared/response-ops/rule_params/metric_threshold/v1.ts index 8c1790cc1623..bb98628278a5 100644 --- a/src/platform/packages/shared/response-ops/rule_params/metric_threshold/v1.ts +++ b/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(), - timeSize: schema.number(), - warningThreshold: schema.maybe(schema.arrayOf(schema.number())), + timeUnit: schema.string({ + meta: { + 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()), - alertOnGroupDisappear: schema.maybe(schema.boolean()), + alertOnNoData: schema.maybe( + 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' } ); diff --git a/x-pack/solutions/observability/plugins/infra/server/lib/alerting/docs/params_property_infra_metric_threshold.yaml b/x-pack/solutions/observability/plugins/infra/server/lib/alerting/docs/params_property_infra_metric_threshold.yaml index 08094832bfc5..bd1675a4182d 100644 --- a/x-pack/solutions/observability/plugins/infra/server/lib/alerting/docs/params_property_infra_metric_threshold.yaml +++ b/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 \ No newline at end of file + 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. \ No newline at end of file