[Alerting v2][Serverless]: Docs for initial public release #5528
Draft
nastasha-solomon wants to merge 47 commits intomainfrom
Draft
[Alerting v2][Serverless]: Docs for initial public release #5528nastasha-solomon wants to merge 47 commits intomainfrom
nastasha-solomon wants to merge 47 commits intomainfrom
Conversation
<!-- Thank you for contributing to the Elastic Docs! 🎉 Use this template to help us efficiently review your contribution. --> ## Summary <!-- Describe what your PR changes or improves. If your PR fixes an issue, link it here. If your PR does not fix an issue, describe the reason you are making the change. --> Fixes elastic/docs-content-internal#919. First draft of v2 alerting docs. ## Generative AI disclosure <!-- To help us ensure compliance with the Elastic open source and documentation guidelines, please answer the following: --> 1. Did you use a generative AI (GenAI) tool to assist in creating this contribution? - [x] Yes - [ ] No <!-- 2. If you answered "Yes" to the previous question, please specify the tool(s) and model(s) used (e.g., Google Gemini, OpenAI ChatGPT-4, etc.). Tool(s) and model(s) used: --> Cursor + Claude
Contributor
Vale Linting ResultsSummary: 7 warnings, 32 suggestions found
|
| File | Line | Rule | Message |
|---|---|---|---|
| explore-analyze/alerting/kibana-alerting-v2/alerts/view-and-manage-alerts-v2.md | 70 | Elastic.Spelling | 'Unacknowledge' is a possible misspelling. |
| explore-analyze/alerting/kibana-alerting-v2/alerts/view-and-manage-alerts-v2.md | 72 | Elastic.Spelling | 'Unresolve' is a possible misspelling. |
| explore-analyze/alerting/kibana-alerting-v2/alerts/view-and-manage-alerts-v2.md | 85 | Elastic.BritishSpellings | Use American English spelling 'acknowledgment' instead of British English 'acknowledgement'. |
| explore-analyze/alerting/kibana-alerting-v2/rules/configure-a-rule-v2.md | 97 | Elastic.Spelling | 'timeframes' is a possible misspelling. |
| explore-analyze/track-and-respond.md | 32 | Elastic.EndPuntuaction | Don't end headings with punctuation. |
| explore-analyze/track-and-respond.md | 55 | Elastic.EndPuntuaction | Don't end headings with punctuation. |
| troubleshoot/elasticsearch/mapping-explosion.md | 37 | Elastic.Spelling | 'Javascript' is a possible misspelling. |
💡 Suggestions (32)
| File | Line | Rule | Message |
|---|---|---|---|
| deploy-manage/deploy/cloud-on-k8s/k8s-service-mesh-istio.md | 15 | Elastic.Versions | Use 'or later' instead of 'or newer' when referring to versions. |
| deploy-manage/production-guidance/kibana-task-manager-scaling-considerations.md | 15 | Elastic.HeadingColons | Capitalize ': p'. |
| deploy-manage/users-roles/cluster-or-deployment-auth/quickstart.md | 25 | Elastic.WordChoice | Consider using 'refer to if it's a document, view if it's a UI element' instead of 'see', unless the term is in the UI. |
| explore-analyze/alerting/kibana-alerting-v1/alerting-common-issues-v1.md | 84 | Elastic.WordChoice | Consider using 'can, might' instead of 'may', unless the term is in the UI. |
| explore-analyze/alerting/kibana-alerting-v1/alerting-getting-started-v1.md | 26 | Elastic.WordChoice | Consider using 'refer to if it's a document, view if it's a UI element' instead of 'see', unless the term is in the UI. |
| explore-analyze/alerting/kibana-alerting-v1/alerting-getting-started-v1.md | 30 | Elastic.Wordiness | Consider using 'these' instead of 'all of these'. |
| explore-analyze/alerting/kibana-alerting-v1/alerting-setup-v1.md | 100 | Elastic.WordChoice | Consider using 'deactivate, deselect, hide, turn off' instead of 'disable', unless the term is in the UI. |
| explore-analyze/alerting/kibana-alerting-v1/alerting-setup-v1.md | 104 | Elastic.Repetition | "support" is repeated. |
| explore-analyze/alerting/kibana-alerting-v1/alerting-setup-v1.md | 104 | Elastic.Semicolons | Use semicolons judiciously. |
| explore-analyze/alerting/kibana-alerting-v1/alerting-troubleshooting-v1.md | 35 | Elastic.Wordiness | Consider using 'also' instead of 'In addition'. |
| explore-analyze/alerting/kibana-alerting-v1/create-manage-rules-v1.md | 81 | Elastic.Semicolons | Use semicolons judiciously. |
| explore-analyze/alerting/kibana-alerting-v1/create-manage-rules-v1.md | 153 | Elastic.WordChoice | Consider using 'deactivate, deselect, hide, turn off' instead of 'disable', unless the term is in the UI. |
| explore-analyze/alerting/kibana-alerting-v1/create-manage-rules-v1.md | 155 | Elastic.WordChoice | Consider using 'deactivate, deselect, hide, turn off' instead of 'disable', unless the term is in the UI. |
| explore-analyze/alerting/kibana-alerting-v1/rule-types-v1.md | 16 | Elastic.WordChoice | Consider using 'refer to if it's a document, view if it's a UI element' instead of 'see', unless the term is in the UI. |
| explore-analyze/alerting/kibana-alerting-v1/view-alerts-v1.md | 105 | Elastic.WordChoice | Consider using 'deactivate, deselect, hide, turn off' instead of 'disable', unless the term is in the UI. |
| explore-analyze/alerting/kibana-alerting-v2/notifications/manage-action-policies-v2.md | 8 | Elastic.WordChoice | Consider using 'deactivate, deselect, hide, turn off' instead of 'disable', unless the term is in the UI. |
| explore-analyze/alerting/kibana-alerting-v2/notifications/manage-action-policies-v2.md | 17 | Elastic.WordChoice | Consider using 'deactivate, deselect, hide, turn off' instead of 'disable', unless the term is in the UI. |
| explore-analyze/alerting/kibana-alerting-v2/quick-start-alerting-v2.md | 58 | Elastic.WordChoice | Consider using 'refer to if it's a document, view if it's a UI element' instead of 'see', unless the term is in the UI. |
| explore-analyze/alerting/kibana-alerting-v2/quick-start-alerting-v2.md | 58 | Elastic.WordChoice | Consider using 'refer to if it's a document, view if it's a UI element' instead of 'see', unless the term is in the UI. |
| explore-analyze/alerting/kibana-alerting-v2/rules/view-manage-rules-v2.md | 28 | Elastic.WordChoice | Consider using 'deactivate, deselect, hide, turn off' instead of 'Disable', unless the term is in the UI. |
| explore-analyze/alerting/kibana-alerting-v2/rules/view-manage-rules-v2.md | 30 | Elastic.WordChoice | Consider using 'deactivate, deselect, hide, turn off' instead of 'Disable', unless the term is in the UI. |
| explore-analyze/alerting/watcher/watcher-getting-started.md | 168 | Elastic.Semicolons | Use semicolons judiciously. |
| explore-analyze/alerting/watcher/watcher-getting-started.md | 168 | Elastic.WordChoice | Consider using 'run, start' instead of 'execute', unless the term is in the UI. |
| explore-analyze/alerting/watcher/watcher-getting-started.md | 174 | Elastic.WordChoice | Consider using 'refer to if it's a document, view if it's a UI element' instead of 'See', unless the term is in the UI. |
| explore-analyze/machine-learning/anomaly-detection/ml-configuring-alerts.md | 252 | Elastic.WordChoice | Consider using 'deactivate, deselect, hide, turn off' instead of 'disable', unless the term is in the UI. |
| manage-data/data-store/data-streams/failure-store-recipes.md | 310 | Elastic.Wordiness | Consider using 'because' instead of 'Since'. |
| manage-data/data-store/data-streams/failure-store-recipes.md | 311 | Elastic.WordChoice | Consider using 'efficient, basic' instead of 'simple', unless the term is in the UI. |
| reference/fleet/monitor-elastic-agent.md | 258 | Elastic.WordChoice | Consider using 'refer to if it's a document, view if it's a UI element' instead of 'see', unless the term is in the UI. |
| solutions/security/detect-and-alert/reduce-noise-and-false-positives.md | 69 | Elastic.Wordiness | Consider using 'all' instead of 'all of '. |
| solutions/security/detect-and-alert/using-logsdb-index-mode-with-elastic-security.md | 66 | Elastic.WordChoice | Consider using 'can, might' instead of 'may', unless the term is in the UI. |
| troubleshoot/elasticsearch/mapping-explosion.md | 35 | Elastic.WordChoice | Consider using 'can, might' instead of 'may', unless the term is in the UI. |
| troubleshoot/kibana/alerts.md | 38 | Elastic.Wordiness | Consider using 'also' instead of 'In addition'. |
The Vale linter checks documentation changes against the Elastic Docs style guide.
To use Vale locally or report issues, refer to Elastic style guide for Vale.
Update internal links to use -v1 suffixed filenames after the alerting directory restructure (create-manage-rules-v1.md, view-alerts-v1.md, alerting-setup-v1.md). Made-with: Cursor
Contributor
Maps alerting v2 doc pages to Kibana implementation PRs and codebase watch paths. Used by Docs Patrol External to detect code changes that require documentation updates. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Resolve toc.yml and redirects.yml: keep kibana-alerting-v1 paths and incorporate query-alerts from main as query-alerts-v1.md with redirects. Made-with: Cursor
The fixes fall into two categories: blocking errors (wrong information that must be corrected before publishing) and incomplete sections (additive work needed).
mikecote
reviewed
Mar 24, 2026
mikecote
reviewed
Mar 24, 2026
| | `resolve` | Episode or alert resolved | | ||
| | `unmatched` | No notification policy matched the episode, so no workflow ran for it under those policies | | ||
|
|
||
| The `untag` action type is not used. Tagging is recorded with the `tag` action type. |
Member
Author
There was a problem hiding this comment.
@adcoelho I don't have access project for testing right now and I'm not entirely sure what elastic/kibana#258643 does, so I need your help confirming that the untag action type is not recorded in the action.type field. If it's not recorded or an accepted value for the action.type field, I'll need to remove this line.
Suggested change
| The `untag` action type is not used. Tagging is recorded with the `tag` action type. |
<!-- Thank you for contributing to the Elastic Docs! 🎉 Use this template to help us efficiently review your contribution. --> ## Summary <!-- Describe what your PR changes or improves. If your PR fixes an issue, link it here. If your PR does not fix an issue, describe the reason you are making the change. --> Adds conceptual content and renames files for alerting v2 ## Generative AI disclosure <!-- To help us ensure compliance with the Elastic open source and documentation guidelines, please answer the following: --> 1. Did you use a generative AI (GenAI) tool to assist in creating this contribution? - [x] Yes - [ ] No <!-- 2. If you answered "Yes" to the previous question, please specify the tool(s) and model(s) used (e.g., Google Gemini, OpenAI ChatGPT-4, etc.). Tool(s) and model(s) used: --> Cursor + Claude
<!-- Thank you for contributing to the Elastic Docs! 🎉 Use this template to help us efficiently review your contribution. --> ## Summary <!-- Describe what your PR changes or improves. If your PR fixes an issue, link it here. If your PR does not fix an issue, describe the reason you are making the change. --> Adds quickstart guide and improves setup and orientation pages ## Generative AI disclosure <!-- To help us ensure compliance with the Elastic open source and documentation guidelines, please answer the following: --> 1. Did you use a generative AI (GenAI) tool to assist in creating this contribution? - [x] Yes - [ ] No <!-- 2. If you answered "Yes" to the previous question, please specify the tool(s) and model(s) used (e.g., Google Gemini, OpenAI ChatGPT-4, etc.). Tool(s) and model(s) used: --> Cursor + Claude
<!-- Thank you for contributing to the Elastic Docs! 🎉 Use this template to help us efficiently review your contribution. --> ## Summary <!-- Describe what your PR changes or improves. If your PR fixes an issue, link it here. If your PR does not fix an issue, describe the reason you are making the change. --> Adds more to dispatcher docs. Also adds annotations for areas that will need additional verification and cleans up redirects file. ## Generative AI disclosure <!-- To help us ensure compliance with the Elastic open source and documentation guidelines, please answer the following: --> 1. Did you use a generative AI (GenAI) tool to assist in creating this contribution? - [x] Yes - [ ] No <!-- 2. If you answered "Yes" to the previous question, please specify the tool(s) and model(s) used (e.g., Google Gemini, OpenAI ChatGPT-4, etc.). Tool(s) and model(s) used: --> Cursor + Claude
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR contains the alerting v2 documentation scoped for the tech preview release to serverless, fixing https://github.com/elastic/docs-content-internal/issues/919. It makes several major changes:
What's included
kibana-alerting-v1/path. A new "Choose an alerting system" comparison page helps users navigate between them.What's intentionally out of scope [STILL BEING DECIDED]
Procedural content tied to unfinalized UI (rule builder, Discover entry point, privileges page) is deferred. Pages with [CONTENT NEEDED: UI] annotations hold the procedure gap and will be filled in a follow-up PR as the UI stabilizes. M2 content that's been deferred and will be published following the initial release to serverless.
How to read the annotations
[CONTENT NEEDED: UI]- Blocked on UI finalization; skip during review[CONTENT NEEDED for M2]- Drafted for M1, will need updating when M2 ships; reviewers should check correctness of surrounding content[CONTENT NEEDED](no qualifier) - Open design question that needs a decision before publishGenerative AI disclosure
Reviews needed
This PR needs an editorial review, a technical review, and code owner reviews. Instructions for each are below.
What to skip: Any section marked
[CONTENT NEEDED]is intentionally incomplete pending UI finalization or technical confirmation.✏️ Editorial reviewer
Given the size of this PR, please focus your review on the new v2 content. A full line-by-line read of all 25 pages isn't expected. Instead, please prioritize the pages users will hit first and the issues most likely to affect clarity or correctness.
Highest priority:
choose-an-alerting-system.md- This page frames the entire v1/v2 story. Check that the comparison is neutral, accurate, and helps users make a clear decision.quick-start-alerting-v2.md- The first page most users will follow hands-on. Check for clarity, logical flow, and complete steps.alerts-v2.md,rules-v2.md,notifications-v2.md: These are conceptual pages that introduce new mental models. Check that terminology is used consistently, the framing is goal-oriented (rather than implementation-oriented), and that the content is easy to understand.🔧 Technical reviewer
Please focus your review on accuracy of facts, names, and structure only. For example, please verify that field names, values, and descriptions in reference material is accurate and matches the the current implementation. When reviewing conceptual material, please check that definitions are technically accurate and reflect the current engineering design.
👤 Code owner reviewers
This is a large PR. A full review of every file isn't expected — focus on whether the changes in your area are correct and won't mislead users.
@elastic/experience-docs and @elastic/developer-docs - Please review the primary new content:
explore-analyze/alerting-overview.mdandexplore-analyze/alerting/choose-an-alerting-system.md: New orientation and v1 vs. v2 comparison pagesexplore-analyze/toc.yml: TOC restructured to accommodate the v1/v2 splitsolutions/observability/**(18 files) andsolutions/security/detect-and-alert/**(5 files): Cross-references updated;view-alerts.mdhas a more substantive update (+6 -6) — verify intent@elastic/docs - Please review the infrastructure files:
redirects.yml: ~140 new redirect entries added, please spot-check that source paths cover all previously published alerting URLs and that destination paths are correctdocset.yml: New section registered (+4 -1)reference/glossary/index.md: Glossary entries updatedCross-reference updates only - Please verify the updated links point to the correct destination for your area:
deploy-manage/**(12 files),manage-data/data-store/data-streams/failure-store-recipes.mdreference/fleet/alerting-rule-templates.md,reference/fleet/monitor-elastic-agent.mdget-started/evaluate-elastic.md,get-started/the-stack.mdPreviews - 📁 New v2 content
explore-analyze/alerting/kibana-alerting-v2.mdexplore-analyze/alerting-overview.mdexplore-analyze/alerting/choose-an-alerting-system.mdSetup
kibana-alerting-v2/quick-start-alerting-v2.mdkibana-alerting-v2/setup-alerting-v2.mdkibana-alerting-v2/alerting-v2-privileges.mdCreate and manage rules
kibana-alerting-v2/rules-v2.mdkibana-alerting-v2/rules/author-rules-v2.mdkibana-alerting-v2/rules/esql-query-patterns-v2.mdkibana-alerting-v2/rules/create-rule-from-rule-builder-v2.mdkibana-alerting-v2/rules/create-rule-from-discover-v2.mdkibana-alerting-v2/rules/create-rule-with-yaml-v2.mdkibana-alerting-v2/rules/yaml-rule-schema-reference-v2.mdkibana-alerting-v2/rules/configure-a-rule-v2.mdkibana-alerting-v2/rules/view-manage-rules-v2.mdkibana-alerting-v2/rules/rule-event-field-reference-v2.mdView and manage alerts
kibana-alerting-v2/alerts-v2.mdkibana-alerting-v2/alerts/view-and-manage-alerts-v2.mdkibana-alerting-v2/alerts/alert-states-and-fields-reference-v2.mdkibana-alerting-v2/alerts/query-alerts-and-signals-in-discover-v2.mdWorkflows and action policies
kibana-alerting-v2/workflows-alerting-v2.mdkibana-alerting-v2/notifications-v2.mdkibana-alerting-v2/notifications/create-configure-action-policy-v2.mdkibana-alerting-v2/notifications/action-policy-reference-v2.mdkibana-alerting-v2/notifications/manage-action-policies-v2.md