diff --git a/docs/detections/about-rules.asciidoc b/docs/detections/about-rules.asciidoc index b241b82013..81710bf359 100644 --- a/docs/detections/about-rules.asciidoc +++ b/docs/detections/about-rules.asciidoc @@ -59,6 +59,8 @@ When you create a rule, you must either specify the {es} index pattens for which NOTE: To access data views, ensure you have the {kibana-ref}/data-views.html#data-views-read-only-access[required permissions]. +IMPORTANT: System indices, such as the alert indices, contain important configuration and internal data; do not change their mappings. Changes can lead to rule execution and alert indexing failures. Use <> instead, which allow you to add fields to existing alert and event documents. + [float] [[about-notifications]] === Notifications diff --git a/docs/detections/query-alert-indices.asciidoc b/docs/detections/query-alert-indices.asciidoc index 07d8018ff8..5a61f38836 100644 --- a/docs/detections/query-alert-indices.asciidoc +++ b/docs/detections/query-alert-indices.asciidoc @@ -2,6 +2,8 @@ == Query alert indices This page explains how you should query alert indices, for example, when building rule queries, custom dashboards, or visualizations. For more information about alert event field definitions, review the <>. +IMPORTANT: System indices, such as the alert indices, contain important configuration and internal data; do not change their mappings. Changes can lead to rule execution and alert indexing failures. Use <> instead, which allow you to add fields to existing alert and event documents. + [discrete] === Alert index aliases We recommend querying the following index aliases: diff --git a/docs/reference/alert-schema.asciidoc b/docs/reference/alert-schema.asciidoc index a4d27d1faf..337a13e72b 100644 --- a/docs/reference/alert-schema.asciidoc +++ b/docs/reference/alert-schema.asciidoc @@ -9,7 +9,12 @@ {elastic-sec} stores alerts that have been generated by detection rules in hidden {es} indices. In 8.x versions, the index pattern is `.alerts-security.alerts-`. In 7.x versions, the index pattern was `.siem-signals-`, and some field names were different. The following table includes the current names and cross-references the legacy field names. -NOTE: Users are advised NOT to use the `_source` field in alert documents, but rather to use the `fields` option in the search API to programmatically obtain the list of fields used in these documents. Learn more about {ref}/search-fields.html[retrieving selected fields from a search]. +[IMPORTANT] +==== + +* System indices, such as the alert indices, contain important configuration and internal data; do not change their mappings. Changes can lead to rule execution and alert indexing failures. Use <> instead, which allow you to add fields to existing alert and event documents. +* We recommend to NOT use the `_source` field in alert documents, but rather the `fields` option in the search API to programmatically obtain the list of fields used in these documents. Learn more about {ref}/search-fields.html[retrieving selected fields from a search]. +==== NOTE: The non-ECS fields listed below are beta and subject to change.