From b830f93eb2792d747810bc871e54a751c350127e Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Tue, 23 Jan 2024 10:03:30 -0800 Subject: [PATCH] [OAS] Adds alerts data to get rule types API (#170702) (cherry picked from commit d3c51c45ebca2c4423b7a888fa14221bfa68ef58) --- docs/api/alerting/list_rule_types.asciidoc | 6 +- .../alerting/docs/openapi/bundled.json | 122 +++++++++++++++++- .../alerting/docs/openapi/bundled.yaml | 100 ++++++++++++++ .../schemas/fieldmap_properties.yaml | 47 +++++++ .../s@{spaceid}@api@alerting@rule_types.yaml | 59 +++++++++ 5 files changed, 330 insertions(+), 4 deletions(-) create mode 100644 x-pack/plugins/alerting/docs/openapi/components/schemas/fieldmap_properties.yaml diff --git a/docs/api/alerting/list_rule_types.asciidoc b/docs/api/alerting/list_rule_types.asciidoc index 05324e9b9a026..e7a7c1ad14063 100644 --- a/docs/api/alerting/list_rule_types.asciidoc +++ b/docs/api/alerting/list_rule_types.asciidoc @@ -63,7 +63,8 @@ context and state in action parameter templates, and a short human readable description. When you create a rule in {kib}, it uses this information to prompt you for these variables in action parameter editors. -// `alerts`:: TBD +`alerts`:: +(object) Details about alerts as data documents for this rule type, including any custom mappings. `authorized_consumers`:: (object) The list of the plugins IDs that have access to the rule type. @@ -82,7 +83,8 @@ action. (boolean) Indicates whether the rule type is enabled or disabled based on the subscription. -// `has_alerts_mappings`:: TBD +`has_alerts_mappings`:: +(boolean) Indicates whether the rule type has custom mappings for the alert data. // `has_fields_for_a_a_d`:: TBD diff --git a/x-pack/plugins/alerting/docs/openapi/bundled.json b/x-pack/plugins/alerting/docs/openapi/bundled.json index 8688c79a8122b..d5ac492cf5e85 100644 --- a/x-pack/plugins/alerting/docs/openapi/bundled.json +++ b/x-pack/plugins/alerting/docs/openapi/bundled.json @@ -895,7 +895,68 @@ } }, "alerts": { - "type": "object" + "type": "object", + "description": "Details for writing alerts as data documents for this rule type.\n", + "properties": { + "context": { + "type": "string", + "description": "The namespace for this rule type.\n", + "enum": [ + "ml.anomaly-detection", + "observability.apm", + "observability.logs", + "observability.metrics", + "observability.slo", + "observability.threshold", + "observability.uptime", + "security", + "stack" + ] + }, + "dynamic": { + "type": "string", + "description": "Indicates whether new fields are added dynamically.", + "enum": [ + "false", + "runtime", + "strict", + "true" + ] + }, + "isSpaceAware": { + "type": "boolean", + "description": "Indicates whether the alerts are space-aware. If true, space-specific alert indices are used.\n" + }, + "mappings": { + "type": "object", + "properties": { + "fieldMap": { + "type": "object", + "description": "Mapping information for each field supported in alerts as data documents for this rule type. For more information about mapping parameters, refer to the Elasticsearch documentation.\n", + "additionalProperties": { + "$ref": "#/components/schemas/fieldmap_properties" + } + } + } + }, + "secondaryAlias": { + "type": "string", + "description": "A secondary alias. It is typically used to support the signals alias for detection rules.\n" + }, + "shouldWrite": { + "type": "boolean", + "description": "Indicates whether the rule should write out alerts as data.\n" + }, + "useEcs": { + "type": "boolean", + "description": "Indicates whether to include the ECS component template for the alerts.\n" + }, + "useLegacyAlerts": { + "type": "boolean", + "default": false, + "description": "Indicates whether to include the legacy component template for the alerts.\n" + } + } }, "authorized_consumers": { "description": "The list of the plugins IDs that have access to the rule type.", @@ -1046,7 +1107,8 @@ "type": "boolean" }, "has_alerts_mappings": { - "type": "boolean" + "type": "boolean", + "description": "Indicates whether the rule type has custom mappings for the alert data." }, "has_fields_for_a_a_d": { "type": "boolean" @@ -6777,6 +6839,62 @@ } } }, + "fieldmap_properties": { + "title": "Field map objects in the get rule types response", + "type": "object", + "properties": { + "array": { + "type": "boolean", + "description": "Indicates whether the field is an array." + }, + "dynamic": { + "type": "boolean", + "description": "Indicates whether it is a dynamic field mapping." + }, + "format": { + "type": "string", + "description": "Indicates the format of the field. For example, if the `type` is `date_range`, the `format` can be `epoch_millis||strict_date_optional_time`.\n" + }, + "ignore_above": { + "type": "integer", + "description": "Specifies the maximum length of a string field. Longer strings are not indexed or stored." + }, + "index": { + "type": "boolean", + "description": "Indicates whether field values are indexed." + }, + "path": { + "type": "string", + "description": "TBD" + }, + "properties": { + "type": "object", + "description": "Details about the object properties. This property is applicable when `type` is `object`.\n", + "additionalProperties": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "The data type for each object property." + } + } + } + }, + "required": { + "type": "boolean", + "description": "Indicates whether the field is required." + }, + "scaling_factor": { + "type": "integer", + "description": "The scaling factor to use when encoding values. This property is applicable when `type` is `scaled_float`. Values will be multiplied by this factor at index time and rounded to the closest long value. \n" + }, + "type": { + "type": "string", + "description": "Specifies the data type for the field.", + "example": "scaled_float" + } + } + }, "400_response": { "title": "Bad request", "type": "object", diff --git a/x-pack/plugins/alerting/docs/openapi/bundled.yaml b/x-pack/plugins/alerting/docs/openapi/bundled.yaml index 83fec9274220a..55e189251e086 100644 --- a/x-pack/plugins/alerting/docs/openapi/bundled.yaml +++ b/x-pack/plugins/alerting/docs/openapi/bundled.yaml @@ -569,6 +569,61 @@ paths: type: string alerts: type: object + description: | + Details for writing alerts as data documents for this rule type. + properties: + context: + type: string + description: | + The namespace for this rule type. + enum: + - ml.anomaly-detection + - observability.apm + - observability.logs + - observability.metrics + - observability.slo + - observability.threshold + - observability.uptime + - security + - stack + dynamic: + type: string + description: Indicates whether new fields are added dynamically. + enum: + - 'false' + - runtime + - strict + - 'true' + isSpaceAware: + type: boolean + description: | + Indicates whether the alerts are space-aware. If true, space-specific alert indices are used. + mappings: + type: object + properties: + fieldMap: + type: object + description: | + Mapping information for each field supported in alerts as data documents for this rule type. For more information about mapping parameters, refer to the Elasticsearch documentation. + additionalProperties: + $ref: '#/components/schemas/fieldmap_properties' + secondaryAlias: + type: string + description: | + A secondary alias. It is typically used to support the signals alias for detection rules. + shouldWrite: + type: boolean + description: | + Indicates whether the rule should write out alerts as data. + useEcs: + type: boolean + description: | + Indicates whether to include the ECS component template for the alerts. + useLegacyAlerts: + type: boolean + default: false + description: | + Indicates whether to include the legacy component template for the alerts. authorized_consumers: description: The list of the plugins IDs that have access to the rule type. type: object @@ -668,6 +723,7 @@ paths: type: boolean has_alerts_mappings: type: boolean + description: Indicates whether the rule type has custom mappings for the alert data. has_fields_for_a_a_d: type: boolean id: @@ -4647,6 +4703,50 @@ components: $ref: '#/components/schemas/tags' throttle: $ref: '#/components/schemas/throttle' + fieldmap_properties: + title: Field map objects in the get rule types response + type: object + properties: + array: + type: boolean + description: Indicates whether the field is an array. + dynamic: + type: boolean + description: Indicates whether it is a dynamic field mapping. + format: + type: string + description: | + Indicates the format of the field. For example, if the `type` is `date_range`, the `format` can be `epoch_millis||strict_date_optional_time`. + ignore_above: + type: integer + description: Specifies the maximum length of a string field. Longer strings are not indexed or stored. + index: + type: boolean + description: Indicates whether field values are indexed. + path: + type: string + description: TBD + properties: + type: object + description: | + Details about the object properties. This property is applicable when `type` is `object`. + additionalProperties: + type: object + properties: + type: + type: string + description: The data type for each object property. + required: + type: boolean + description: Indicates whether the field is required. + scaling_factor: + type: integer + description: | + The scaling factor to use when encoding values. This property is applicable when `type` is `scaled_float`. Values will be multiplied by this factor at index time and rounded to the closest long value. + type: + type: string + description: Specifies the data type for the field. + example: scaled_float 400_response: title: Bad request type: object diff --git a/x-pack/plugins/alerting/docs/openapi/components/schemas/fieldmap_properties.yaml b/x-pack/plugins/alerting/docs/openapi/components/schemas/fieldmap_properties.yaml new file mode 100644 index 0000000000000..49a53090a6a6a --- /dev/null +++ b/x-pack/plugins/alerting/docs/openapi/components/schemas/fieldmap_properties.yaml @@ -0,0 +1,47 @@ +title: Field map objects in the get rule types response +type: object +properties: + array: + type: boolean + description: Indicates whether the field is an array. + dynamic: + type: boolean + description: Indicates whether it is a dynamic field mapping. + format: + type: string + description: > + Indicates the format of the field. + For example, if the `type` is `date_range`, the `format` can be `epoch_millis||strict_date_optional_time`. + ignore_above: + type: integer + description: Specifies the maximum length of a string field. Longer strings are not indexed or stored. + index: + type: boolean + description: Indicates whether field values are indexed. + path: + type: string + description: TBD + properties: + type: object + description: > + Details about the object properties. + This property is applicable when `type` is `object`. + additionalProperties: + type: object + properties: + type: + type: string + description: The data type for each object property. + required: + type: boolean + description: Indicates whether the field is required. + scaling_factor: + type: integer + description: > + The scaling factor to use when encoding values. + This property is applicable when `type` is `scaled_float`. + Values will be multiplied by this factor at index time and rounded to the closest long value. + type: + type: string + description: Specifies the data type for the field. + example: scaled_float \ No newline at end of file diff --git a/x-pack/plugins/alerting/docs/openapi/paths/s@{spaceid}@api@alerting@rule_types.yaml b/x-pack/plugins/alerting/docs/openapi/paths/s@{spaceid}@api@alerting@rule_types.yaml index 41ec2aeadbe34..36542211cb318 100644 --- a/x-pack/plugins/alerting/docs/openapi/paths/s@{spaceid}@api@alerting@rule_types.yaml +++ b/x-pack/plugins/alerting/docs/openapi/paths/s@{spaceid}@api@alerting@rule_types.yaml @@ -76,6 +76,64 @@ get: type: string alerts: type: object + description: > + Details for writing alerts as data documents for this rule type. + properties: + context: + type: string + description: > + The namespace for this rule type. + enum: + - ml.anomaly-detection + - observability.apm + - observability.logs + - observability.metrics + - observability.slo + - observability.threshold + - observability.uptime + - security + - stack + dynamic: + type: string + description: Indicates whether new fields are added dynamically. + enum: + - "false" + - "runtime" + - "strict" + - "true" + isSpaceAware: + type: boolean + description: > + Indicates whether the alerts are space-aware. + If true, space-specific alert indices are used. + mappings: + type: object + properties: + fieldMap: + type: object + description: > + Mapping information for each field supported in alerts as data documents for this rule type. + For more information about mapping parameters, refer to the Elasticsearch documentation. + additionalProperties: + $ref: '../components/schemas/fieldmap_properties.yaml' + secondaryAlias: + type: string + description: > + A secondary alias. + It is typically used to support the signals alias for detection rules. + shouldWrite: + type: boolean + description: > + Indicates whether the rule should write out alerts as data. + useEcs: + type: boolean + description: > + Indicates whether to include the ECS component template for the alerts. + useLegacyAlerts: + type: boolean + default: false + description: > + Indicates whether to include the legacy component template for the alerts. authorized_consumers: description: The list of the plugins IDs that have access to the rule type. type: object @@ -175,6 +233,7 @@ get: type: boolean has_alerts_mappings: type: boolean + description: Indicates whether the rule type has custom mappings for the alert data. has_fields_for_a_a_d: type: boolean id: