[Alerting v2][Serverless & 9.5]: Docs for initial public release (M2)#5528
Closed
nastasha-solomon wants to merge 61 commits into
Closed
[Alerting v2][Serverless & 9.5]: Docs for initial public release (M2)#5528nastasha-solomon wants to merge 61 commits into
nastasha-solomon wants to merge 61 commits into
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: 11 warnings, 24 suggestions found
|
| File | Line | Rule | Message |
|---|---|---|---|
| explore-analyze/alerting-overview.md | 2 | Elastic.MappedPages | mapped_pages should only be added or updated in rare scenarios. Talk with your local technical writer before pushing changes to this key. |
| explore-analyze/alerting/kibana-alerting-v2/alerts/view-and-manage-alerts-v2.md | 46 | Elastic.DontUse | Don't use 'just'. |
| explore-analyze/alerting/kibana-alerting-v2/alerts/view-and-manage-alerts-v2.md | 103 | Elastic.Spelling | 'Unacknowledge' is a possible misspelling. |
| explore-analyze/alerting/kibana-alerting-v2/alerts/view-and-manage-alerts-v2.md | 105 | Elastic.Spelling | 'Unresolve' is a possible misspelling. |
| explore-analyze/alerting/kibana-alerting-v2/alerts/view-and-manage-alerts-v2.md | 119 | 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/alerting/kibana-alerting-v2/rules/esql-query-patterns-v2.md | 85 | Elastic.DirectionalLanguage | Don't use directional language. Use 'in the preceding element' instead of 'in the example above'. |
| explore-analyze/alerting/watcher/enable-watcher.md | 24 | Elastic.MenuArrows | Use '→' to separate menu items, not '' or '='. Example: Select Manage index → Add lifecycle policy. |
| 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 (24)
| 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'. |
| 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 | 30 | Elastic.Wordiness | Consider using 'these' instead of 'all of these'. |
| 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/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.md | 88 | Elastic.Wordiness | Consider using 'between' instead of 'in between'. |
| 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/rules/view-manage-rules-v2.md | 25 | 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 | 31 | 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 | 42 | 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 | 44 | 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/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 | 311 | Elastic.WordChoice | Consider using 'efficient, basic' instead of 'simple', 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
…ntent into alerting-v2-docs
| | `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. |
mikecote
reviewed
May 7, 2026
| | `@timestamp` | date | When the action was recorded. | | ||
| | `episode.id` | keyword | Target episode. | | ||
| | `rule.id` | keyword | Rule that owns the episode. | | ||
| | `action.type` | keyword | The action type, for example: <br>- `acknowledge`: User acknowledged the alert.<br>- `snooze`: Notifications snoozed for a period.<br>- `tag`: Tag applied to the alert.<br>- `fire`: Notification or escalation fired for the episode.<br>- `unmatched`: No action policy matched the episode, so no workflow ran for it under these policies. <br><br> For the full set of action types and UI behavior, refer to [Alert actions](view-and-manage-alerts-v2.md#alert-actions-v2). | |
Contributor
There was a problem hiding this comment.
Suggested change
| | `action.type` | keyword | The action type, for example: <br>- `acknowledge`: User acknowledged the alert.<br>- `snooze`: Notifications snoozed for a period.<br>- `tag`: Tag applied to the alert.<br>- `fire`: Notification or escalation fired for the episode.<br>- `unmatched`: No action policy matched the episode, so no workflow ran for it under these policies. <br><br> For the full set of action types and UI behavior, refer to [Alert actions](view-and-manage-alerts-v2.md#alert-actions-v2). | | |
| | `action.type` | keyword | The action type, for example: <br>- `ack`: User acknowledged the alert.<br>- `snooze`: Notifications snoozed for a period.<br>- `tag`: Tag applied to the alert.<br>- `fire`: Notification or escalation fired for the episode.<br>- `unmatched`: No action policy matched the episode, so no workflow ran for it under these policies. <br><br> For the full set of action types and UI behavior, refer to [Alert actions](view-and-manage-alerts-v2.md#alert-actions-v2). | |
| | `@timestamp` | date | When the action was recorded. | | ||
| | `episode.id` | keyword | Target episode. | | ||
| | `rule.id` | keyword | Rule that owns the episode. | | ||
| | `action.type` | keyword | The action type, for example: <br>- `acknowledge`: User acknowledged the alert.<br>- `snooze`: Notifications snoozed for a period.<br>- `tag`: Tag applied to the alert.<br>- `fire`: Notification or escalation fired for the episode.<br>- `unmatched`: No action policy matched the episode, so no workflow ran for it under these policies. <br><br> For the full set of action types and UI behavior, refer to [Alert actions](view-and-manage-alerts-v2.md#alert-actions-v2). | |
Contributor
There was a problem hiding this comment.
For the full set of action types and UI behavior, refer to Alert actions.
Reading the section within view-and-manage-alerts-v2 redirects me here to get the full list of actions.
For reference, we have: ack, unack, snooze, unsnooze, tag, assign, activate, deactivate and for the dispatcher actions fire, unmatched, suppress and notified. @kdelemme can verify.
|
|
||
| ### Derivative aggregation [derivative-aggregation-v2] | ||
|
|
||
| {{esql}} does not have a `DERIVATIVE` function. In the {{es}} aggregations API, a derivative pipeline aggregation calculates the rate of change between consecutive time buckets (for example, "how fast is this counter increasing per minute?"). There is no equivalent in {{esql}} today. |
Contributor
There was a problem hiding this comment.
This was referenced May 8, 2026
jasonrhodes
reviewed
May 11, 2026
tiamliu
reviewed
May 12, 2026
tiamliu
left a comment
tiamliu
left a comment
There was a problem hiding this comment.
really nicely organized and comprehensive. Thanks @nastasha-solomon
| ## Elastic Cloud email service | ||
|
|
||
| {{ecloud}} provides a built-in email service used by the preconfigured [email connector](kibana://reference/connectors-kibana/email-action-type.md), available in both {{ech}} deployments and {{serverless-full}} projects. This service can be used to send [alert](/explore-analyze/alerting/alerts.md) notifications and is also supported in {{ech}} by [Watcher](/explore-analyze/alerting/watcher/enable-watcher.md). | ||
| {{ecloud}} provides a built-in email service used by the preconfigured [email connector](kibana://reference/connectors-kibana/email-action-type.md), available in both {{ech}} deployments and {{serverless-full}} projects. This service can be used to send [alert](/explore-analyze/alerting/kibana-alerting-v1.md) notifications and is also supported in {{ech}} by [Watcher](/explore-analyze/alerting/watcher/enable-watcher.md). |
There was a problem hiding this comment.
yes but not directly. It would be indirectly via workflow - > connectors
| serverless: preview | ||
| products: | ||
| - id: kibana | ||
| description: "Reference for {{alerting-v2}} episode status, `.rule-events` row status, and `.alert-actions` document fields." |
There was a problem hiding this comment.
Do we have definitions somewhere in the doc for these new alerting v2 concepts?
Member
Author
There was a problem hiding this comment.
Which concept definitions are you looking for?
| |---|---| | ||
| | `breached` | Condition met for this evaluation row. | | ||
| | `recovered` | Recovery path satisfied for this evaluation row. | | ||
| | `no_data` | No-data handling produced a no-data style outcome for this evaluation. | |
There was a problem hiding this comment.
@mikecote Did we decide to add 'no_data' status for rule_events?
| **Action policy** | ||
| : How you control who gets notified, when, and how often. You configure a matcher to filter which alerts it applies to, how alerts should be grouped, and which workflow should send the message. One action policy can apply to alerts from multiple rules. To learn more, refer to [Notifications](kibana-alerting-v2/notifications-v2.md). | ||
|
|
||
| **Alert** |
There was a problem hiding this comment.
this definition is incorrect. We do not have "alert" per se in alerting v2
| **{{esql}}** | ||
| : The query language every rule uses to search your data. To learn more, refer to the [{{esql}} reference](elasticsearch://reference/query-languages/esql.md). | ||
|
|
||
| **Notification** |
| children: | ||
| - file: alerting/kibana-alerting-v2/notifications/create-configure-action-policy-v2.md | ||
| - file: alerting/kibana-alerting-v2/notifications/action-policy-reference-v2.md | ||
| - file: alerting/kibana-alerting-v2/notifications/manage-action-policies-v2.md |
|
|
||
| ## Compare at a glance | ||
|
|
||
| | | Kibana alerting v1 | {{alerting-v2}} | Watcher | |
There was a problem hiding this comment.
this is good and valuable information. I feel like we should expand on this a little more , also highlighting what is available in each and what isn't
Co-authored-by: Mike Côté <mikecote@users.noreply.github.com>
…nage-alerts-v2.md
nastasha-solomon
changed the title
Member
Author
|
This PR has grown too large for effective review. It has 161 files, 50+ open comments, and several months of merge commits have made it difficult to track what's changed and what still needs attention. I'm closing this PR and replacing it with a set of smaller, focused PRs, each covering a logical section of the experimental alerting documentation. This will make it easier to review content in context, address open comments one area at a time, and merge incrementally as each section is ready. Planned PRs
What happens to open commentsAll open and unresolved comments from this PR have been captured and mapped to the relevant new PR here. They will be addressed as part of the review process for each branch. Nothing is being dropped. Other changes in this restructure
|
This was referenced May 15, 2026
nastasha-solomon
added a commit
that referenced
this pull request
May 28, 2026
… alerting pages (#6526) ## Summary Contributes to elastic/docs-content-internal#919. Updates five existing Kibana alerting pages in `alerting/alerts/` to consistently use "Kibana alerting" as the primary term, per the alerting naming guidelines: - `alerts.md`: rename H1 to "Kibana alerting", add opening paragraph establishing the system identity, add cross-reference to experimental alerting features - `alerting-getting-started.md`: rename H1 to "Getting started with Kibana alerting", update first sentence - `alerting-setup.md`: rename H1 to "Set up Kibana alerting", add anchor sentence - `create-manage-rules.md`: rename H1 to include "Kibana alerting" - `view-alerts.md`: rename H1 to include "Kibana alerting", update intro sentence **Why**: The naming guidelines establish "Kibana alerting" as the primary term for the existing alerting system to distinguish it from the experimental alerting features. Every page should identify its system in the first paragraph so search engines and AI retrieval can surface the right content. This PR is independent and can be merged on its own. It is part of the broader series replacing [PR #5528](#5528). ## Test plan - [ ] Confirm no "Kibana alerting v1" in modified files - [ ] Verify the cross-reference in `alerts.md` to `kibana-alerting-experimental.md` is correct (resolves once PR #6521 is merged) - [ ] Check H1 changes don't break any existing anchor links (H1 anchors not changed) 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
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
6 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