Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Alerting user interface documentation and guide #60256

Merged
merged 16 commits into from
Mar 27, 2020
Merged

Alerting user interface documentation and guide #60256

merged 16 commits into from
Mar 27, 2020

Conversation

peterschretlen
Copy link
Contributor

@peterschretlen peterschretlen commented Mar 16, 2020 •
edited
Loading

Summary

Fixes #54986 adding the following sections to the Kibana guide:

  • Management UI docs
  • Alerting user guide

Because we may change our API signatures in 7.8, I have left out API documentation for now.

Checklist

  • Documentation was added for features that require explanation or tutorials

@peterschretlen peterschretlen changed the title Alerting/docs77 Alerting user interface documentation and guide Mar 16, 2020
@peterschretlen peterschretlen marked this pull request as ready for review March 23, 2020 05:13
@peterschretlen peterschretlen requested review from gchaps and a team March 23, 2020 05:15
@peterschretlen peterschretlen added v7.7.0 v8.0.0 Team:ResponseOps Label for the ResponseOps team (formerly the Cases and Alerting teams) labels Mar 23, 2020
@elasticmachine
Copy link
Contributor

Pinging @elastic/kibana-alerting-services (Team:Alerting Services)

@peterschretlen peterschretlen added the release_note:skip Skip the PR/issue when compiling release notes label Mar 23, 2020
mikecote
mikecote approved these changes Mar 26, 2020
View reviewed changes
Copy link
Contributor

@mikecote mikecote left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! Really appreciate you putting this together, it looks really awesome! Just had 2 small comments.

docs/user/management.asciidoc Outdated Show resolved Hide resolved
docs/user/alerting/index.asciidoc Show resolved Hide resolved
@peterschretlen peterschretlen requested review from lcawl and removed request for gchaps March 26, 2020 13:43
@peterschretlen
Copy link
Contributor Author

@lcawl would you be able to do a review of the alerting management docs and user guide in place of @gchaps ?

@KOTungseth
Copy link
Contributor

@peterschretlen I can review the docs.

KOTungseth
KOTungseth reviewed Mar 26, 2020
View reviewed changes
Copy link
Contributor

@KOTungseth KOTungseth left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I mainly reviewed for consistency and accessibility, but if there is anything else you want me to pay special attention to, please let me know. And thank you for this PR!

docs/management/alerting/alert-details.asciidoc Outdated
@@ -0,0 +1,34 @@
[role="xpack"]
[[alert-details]]
=== Alert Details
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Details > details

docs/management/alerting/alert-details.asciidoc Outdated
[role="screenshot"]
image::images/alerts-details-instances-active.png[Alert details page with three alert instances]

In the example above, an alert detects when a site serves more than a threshold number of bytes in a 24 hour period. The *alert details* view show that three sites are above the threshold. These are called *alert instances* - occurrences of the condition being detected - and the instance name, status, time of detection, and duration of the condition are shown in this view.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To meet accessibility standards, we are removing all instances of above from the docs. I would change this first sentence to:

Alerts detect when a site...

docs/management/alerting/alert-details.asciidoc Outdated
[role="screenshot"]
image::images/alerts-details-instances-active.png[Alert details page with three alert instances]

In the example above, an alert detects when a site serves more than a threshold number of bytes in a 24 hour period. The *alert details* view show that three sites are above the threshold. These are called *alert instances* - occurrences of the condition being detected - and the instance name, status, time of detection, and duration of the condition are shown in this view.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since users are already on the Alert details page, I would change the second sentence to:

In this example, three sites are above the threshold.

docs/management/alerting/alert-details.asciidoc Outdated
[role="screenshot"]
image::images/alerts-details-instances-active.png[Alert details page with three alert instances]

In the example above, an alert detects when a site serves more than a threshold number of bytes in a 24 hour period. The *alert details* view show that three sites are above the threshold. These are called *alert instances* - occurrences of the condition being detected - and the instance name, status, time of detection, and duration of the condition are shown in this view.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

*alert instances* > alert instances

docs/management/alerting/alert-details.asciidoc Outdated
[role="screenshot"]
image::images/alerts-details-instance-muting.png[Muting an alert instance]

Alert instances will come and go from the list depending on whether they meet the alert conditions or not - unless they are muted. If a muted instance no longer meets the alert conditions, it will appear as "inactive" in the list. This prevents an instance from triggering actions if it reappears in the future.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"inactive" > inactive

docs/user/alerting/alerting-scale-performance.asciidoc Outdated

{kib} alerting run both alert checks and actions as persistent background tasks. This has two major benefits:

* *Persistence*: all task state and scheduling is stored in elasticsearch, so if {kib} is restarted, alerts and actions will pick up where they left off.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

elasticsearch > {es}

docs/user/alerting/alerting-scale-performance.asciidoc Outdated

{kib} background tasks are managed by:

. polling an {es} task index for overdue tasks at 3 second intervals.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

polling > Polling

docs/user/alerting/alerting-scale-performance.asciidoc
[float]
=== Running background alert checks and actions

{kib} background tasks are managed by:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be a bulleted list instead of a numbered list.

docs/user/alerting/alerting-scale-performance.asciidoc Outdated
{kib} background tasks are managed by:

. polling an {es} task index for overdue tasks at 3 second intervals.
. tasks are then claiming them by updating them in the {es} index, using optimistic concurrency control to prevent conflicts. Each {kib} instance can run a maximum of 10 concurrent tasks, so a maximum of 10 tasks are claimed each interval.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

tasks > Tasks

docs/user/alerting/alerting-scale-performance.asciidoc Outdated

. polling an {es} task index for overdue tasks at 3 second intervals.
. tasks are then claiming them by updating them in the {es} index, using optimistic concurrency control to prevent conflicts. Each {kib} instance can run a maximum of 10 concurrent tasks, so a maximum of 10 tasks are claimed each interval.
. tasks are run on the {kib} server.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

tasks > Tasks

@peterschretlen
Copy link
Contributor Author

@KOTungseth thank you for reviewing, I've made those updates. I think that should be good in terms of review, @mikecote has reviewed the content.

I do expect there may be some follow-up work to update things like screenshots as there a few bugs being fixed, but I think we'll open separate PRs for those.

@peterschretlen peterschretlen merged commit 4e7c681 into elastic:master Mar 27, 2020
This was referenced Mar 27, 2020
Merged
Merged
peterschretlen pushed a commit to peterschretlen/kibana that referenced this pull request Mar 27, 2020
Alerting user interface documentation and guide (elastic#60256)
d86ccae
peterschretlen pushed a commit to peterschretlen/kibana that referenced this pull request Mar 27, 2020
Alerting user interface documentation and guide (elastic#60256)
b1ce19a
@mikecote mikecote mentioned this pull request Apr 2, 2020
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@KOTungseth KOTungseth KOTungseth left review comments

@mikecote mikecote mikecote approved these changes

@lcawl lcawl Awaiting requested review from lcawl

Assignees
No one assigned
Labels
release_note:skip Skip the PR/issue when compiling release notes Team:ResponseOps Label for the ResponseOps team (formerly the Cases and Alerting teams) v7.7.0 v8.0.0
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

User interface documentation and guide
4 participants
@peterschretlen @elasticmachine @KOTungseth @mikecote