[Alerting][Docs] Moving alerting setup to its own page #101323

ymao1 · 2021-06-03T19:23:04Z

Summary

1/3 PRs to address some alerting docs changes suggested by @gchaps. Summary of all proposed changes described here

This PR pulls out the Alerting setup and prerequisites section into its own page. Also some minor changes to the titles in the main Alerting page.

Docs preview:

Main alerting page: https://kibana_101323.docs-preview.app.elstc.co/guide/en/kibana/master/alerting-getting-started.html
Alerting setup page: https://kibana_101323.docs-preview.app.elstc.co/guide/en/kibana/master/alerting-setup.html

ymao1 · 2021-06-04T12:20:43Z

docs/user/alerting/alerting-getting-started.asciidoc

@@ -92,22 +92,6 @@ Using the server monitoring example, each server with average CPU > 0.9 is track

 image::images/alerts.svg[{kib} tracks each detected condition as an alert and takes action on each alert]

-[float]


Moved to the Defining rules page, to be closer to where the setup for this concept is.

ymao1 · 2021-06-04T12:20:53Z

docs/user/alerting/alerting-getting-started.asciidoc

@@ -150,65 +134,4 @@ Functionally, {kib} alerting differs in that:
 At a higher level, {kib} alerting allows rich integrations across use cases like <<xpack-apm,*APM*>>, <<metrics-app,*Metrics*>>, <<xpack-siem,*Security*>>, and <<uptime-app,*Uptime*>>.
 Pre-packaged *rule types* simplify setup and hide the details of complex, domain-specific detections, while providing a consistent interface across {kib}.

-[float]


Moved to its own page

A few comments on Alerting overview page:

This paragraph needs some work. The list needs to be written paralle. Can the condition and schedule have different times?

For example, when monitoring a set of servers, a rule might check for average CPU usage > 0.9 on each server for the last two minutes (condition), checked every minute (schedule), sending a warning email message via SMTP with subject CPU on {{server}} is high (action).

javascript function > Javascript function

Items in a bulleted list should start with caps (for example, "The connector you type"

Suggest removing the prequisites section at the end of the file.

@gchaps Addressed your comments in this commit: 74c50df

I changed the paragraph to be a list...is that clearer? The condition and schedule can have different times.

The Alerting prerequisites section is there temporarily for cross doc link compatibility. Once this PR is merged, I can make a PR to update the observability doc that links to the prerequisites section, and then I will do a cleanup PR here to remove it.

ymao1 · 2021-06-04T15:45:46Z

docs/redirects.asciidoc

@@ -308,3 +308,7 @@ This content has moved. Refer to <<discover-view-surrounding-documents>>.

 This content has moved. Refer to <<string-field-formatters>>.

+[role="exclude",id="alerting-setup-prerequisites"]


@gchaps I added a section to redirects but am still failing CI.

INFO:build_docs:Bad cross-document links: 11:42:23 INFO:build_docs: /tmp/docsbuild/target_repo/html/en/observability/master/create-alerts.html contains broken links to: 11:42:23 INFO:build_docs: - en/kibana/master/alerting-getting-started.html#alerting-setup-prerequisites

Any ideas?

Unfortunately, redirects don't work for section-level links from other books. We'll need to open a PR on the observability-docs repo to fix that link.

@lcawl Thanks! What is the order of operations here? Should I submit the PR and get it merged first then open a PR in that repo?

I think the simplest method (to avoid a chicken-and-egg scenario) might be:
(1) leave the anchor in its existing location (but with the text removed) and refrain from creating the redirect page for now. This should hopefully pass the build checks.
(2) open a PR in observability-docs to update the link to use the new page.
(3) open a PR in kibana to remove the lingering anchor (at this point you shouldn't need a redirects page entry, but I guess it doesn't hurt).

If you want my help with any of those changes or I haven't explained this sufficiently, just let me know!

@lcawl That makes sense, thank you!

…ing/restructure-docs-1

ymao1 · 2021-06-04T23:56:48Z

docs/user/alerting/alerting-getting-started.asciidoc

-[[alerting-security]]
-== Security
+== Prerequisites
+<<alerting-prerequisites, Alerting prerequisites>> 


I had to leave this anchor link in here for now because there are observability docs that link to it. Once this PR is merged, I will create a PR to update the link in the Obs docs, and then create another PR in Kibaba to remove this link. Unfortunately @lcawl I wasn't able to just have an empty anchor link so I left in a header and a link to the new page.

Yay! Looks like the docs build was successful:

16:25:20 INFO:build_docs:All cross-document links OK

elasticmachine · 2021-06-04T23:57:06Z

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

ymao1 · 2021-06-07T12:13:54Z

@elasticmachine merge upstream

YulNaumenko

LGTM!

gchaps · 2021-06-07T18:25:08Z

docs/user/alerting/alerting-getting-started.asciidoc

@@ -150,65 +134,4 @@ Functionally, {kib} alerting differs in that:
 At a higher level, {kib} alerting allows rich integrations across use cases like <<xpack-apm,*APM*>>, <<metrics-app,*Metrics*>>, <<xpack-siem,*Security*>>, and <<uptime-app,*Uptime*>>.
 Pre-packaged *rule types* simplify setup and hide the details of complex, domain-specific detections, while providing a consistent interface across {kib}.

-[float]


A few comments on Alerting overview page:

This paragraph needs some work. The list needs to be written paralle. Can the condition and schedule have different times?

For example, when monitoring a set of servers, a rule might check for average CPU usage > 0.9 on each server for the last two minutes (condition), checked every minute (schedule), sending a warning email message via SMTP with subject CPU on {{server}} is high (action).

javascript function > Javascript function

Items in a bulleted list should start with caps (for example, "The connector you type"

Suggest removing the prequisites section at the end of the file.

docs/user/alerting/alerting-setup.asciidoc

docs/user/alerting/defining-rules.asciidoc

Co-authored-by: gchaps <[email protected]>

…ing/restructure-docs-1

gchaps

LGTM, with one minor comment

docs/user/alerting/alerting-setup.asciidoc

Co-authored-by: gchaps <[email protected]>

kibanamachine · 2021-06-10T19:05:07Z

💚 Build Succeeded

Metrics [docs]

Page load bundle

Size of the bundles that are downloaded on every page load. Target size is below 100kb

id	before	after	diff
`core`	408.3KB	408.2KB	-16.0B

History

💚 Build #130481 succeeded 076561e
💚 Build #129604 succeeded bdcdd62
💚 Build #129453 succeeded 1a4efd6
💔 Build #129343 failed 6485936
💚 Build #129222 succeeded 1712a65

To update your PR or re-run it, just comment with:
@elasticmachine merge upstream

cc @ymao1

* Restructuring main alerting page. Adding separate setup page * Fixing links * Moving suppressing duplicate notifications section * Adding redirect * Reverting redirect. Adding placeholder link * Adding placeholder text * Apply suggestions from code review Co-authored-by: gchaps <[email protected]> * Setup page PR fixes * Alerting page PR fixes * Update docs/user/alerting/alerting-setup.asciidoc Co-authored-by: gchaps <[email protected]> Co-authored-by: Kibana Machine <[email protected]> Co-authored-by: gchaps <[email protected]>

kibanamachine · 2021-06-10T19:16:55Z

💚 Backport successful

Status	Branch	Result
✅	7.x

This backport PR will be merged automatically after passing CI.

…1949) * Restructuring main alerting page. Adding separate setup page * Fixing links * Moving suppressing duplicate notifications section * Adding redirect * Reverting redirect. Adding placeholder link * Adding placeholder text * Apply suggestions from code review Co-authored-by: gchaps <[email protected]> * Setup page PR fixes * Alerting page PR fixes * Update docs/user/alerting/alerting-setup.asciidoc Co-authored-by: gchaps <[email protected]> Co-authored-by: Kibana Machine <[email protected]> Co-authored-by: gchaps <[email protected]> Co-authored-by: ymao1 <[email protected]> Co-authored-by: gchaps <[email protected]>

* master: (68 commits) skip flaky suite (elastic#94043) skip flaky suite (elastic#102012) [esArchive] Persists updates for management/saved_objects/* (elastic#101992) skip flaky suite (elastic#101449) remove unnecessary hack (elastic#101909) [Exploratory View] Use human readable formats (elastic#101520) [Expressions] Refactor expression functions to use observables underneath (elastic#100409) [esArchives] Persist migrated Kibana archives (elastic#101950) [kbnArchiver] fix save to non-existent file (elastic#101974) [Enterprise Search] Add owner and description properties to kibana.json (elastic#101957) [DOCS] Fixes terminology in Stack Monitoring:Kibana alerts (elastic#101696) [Observability] [Cases] Cases in the observability app (elastic#101487) [Alerting][Docs] Combine rule creation and management pages (elastic#101498) temporarily disable build-buddy [Fleet] Fix fleet server collector in case settings are not set (elastic#101752) [Event Log] Populated rule.* ECS fields for alert events. (elastic#101132) [APM] Fleet support for merging input.config values with other nested properties in the policy input (elastic#101690) Add comments to some alerting plugin public API items (elastic#101551) [Alerting][Docs] Moving alerting setup to its own page (elastic#101323) remove uptime public API, it's not used. (elastic#101799) ...

ymao1 added 3 commits June 3, 2021 15:22

Restructuring main alerting page. Adding separate setup page

d972a4c

Fixing links

2a93e6d

Moving suppressing duplicate notifications section

3ad835d

ymao1 commented Jun 4, 2021

View reviewed changes

ymao1 changed the title ~~Restructuring main alerting page. Adding separate setup page~~ [Alerting][Docs] Moving alerting setup to its own page Jun 4, 2021

Adding redirect

1712a65

ymao1 commented Jun 4, 2021

View reviewed changes

ymao1 linked an issue Jun 4, 2021 that may be closed by this pull request

[Alerting] [Docs] Improve alerting documents formatting and combine managing rules related docs. #97657

Closed

ymao1 added 3 commits June 4, 2021 18:59

Reverting redirect. Adding placeholder link

7c8df3e

Merge branch 'master' of https://github.com/elastic/kibana into alert…

b6c5185

…ing/restructure-docs-1

Adding placeholder text

6485936

ymao1 self-assigned this Jun 4, 2021

ymao1 added docs Feature:Alerting 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.14.0 v8.0.0 labels Jun 4, 2021

ymao1 commented Jun 4, 2021

View reviewed changes

ymao1 marked this pull request as ready for review June 4, 2021 23:57

ymao1 requested review from a team as code owners June 4, 2021 23:57

ymao1 requested a review from gchaps June 4, 2021 23:57

ymao1 mentioned this pull request Jun 4, 2021

[Alerting] [Docs] Improve alerting documents formatting and combine managing rules related docs. #97657

Closed

mshustov approved these changes Jun 5, 2021

View reviewed changes

Merge branch 'master' into alerting/restructure-docs-1

1a4efd6

YulNaumenko approved these changes Jun 7, 2021

View reviewed changes

gchaps reviewed Jun 7, 2021

View reviewed changes

ymao1 and others added 4 commits June 7, 2021 15:17

Apply suggestions from code review

0d1e22a

Co-authored-by: gchaps <[email protected]>

Setup page PR fixes

849d29d

Alerting page PR fixes

74c50df

Merge branch 'master' of https://github.com/elastic/kibana into alert…

bdcdd62

…ing/restructure-docs-1

ymao1 requested a review from gchaps June 8, 2021 23:43

Merging in master

076561e

gchaps approved these changes Jun 10, 2021

View reviewed changes

docs/user/alerting/alerting-setup.asciidoc Outdated Show resolved Hide resolved

Update docs/user/alerting/alerting-setup.asciidoc

76aba7b

Co-authored-by: gchaps <[email protected]>

ymao1 added the auto-backport Deprecated - use backport:version if exact versions are needed label Jun 10, 2021

ymao1 merged commit 5a1f370 into elastic:master Jun 10, 2021

kibanamachine mentioned this pull request Jun 10, 2021

[7.x] [Alerting][Docs] Moving alerting setup to its own page (#101323) #101949

Merged

ymao1 mentioned this pull request Jun 10, 2021

[Docs] Update cross-document links to Kibana Alerting docs elastic/observability-docs#779

Merged

ymao1 mentioned this pull request Jun 14, 2021

[Docs] Update cross-document links to Kibana Alerting docs elastic/elasticsearch#74034

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Alerting][Docs] Moving alerting setup to its own page #101323

[Alerting][Docs] Moving alerting setup to its own page #101323

ymao1 commented Jun 3, 2021 •

edited

Loading

ymao1 Jun 4, 2021

ymao1 Jun 4, 2021

gchaps Jun 7, 2021

ymao1 Jun 7, 2021

ymao1 Jun 4, 2021

lcawl Jun 4, 2021

ymao1 Jun 4, 2021

lcawl Jun 4, 2021

ymao1 Jun 4, 2021

ymao1 Jun 4, 2021

lcawl Jun 5, 2021

elasticmachine commented Jun 4, 2021

ymao1 commented Jun 7, 2021

YulNaumenko left a comment

gchaps Jun 7, 2021

gchaps left a comment

kibanamachine commented Jun 10, 2021

kibanamachine commented Jun 10, 2021

		@@ -92,22 +92,6 @@ Using the server monitoring example, each server with average CPU > 0.9 is track

		image::images/alerts.svg[{kib} tracks each detected condition as an alert and takes action on each alert]

		[float]

		@@ -308,3 +308,7 @@ This content has moved. Refer to <<discover-view-surrounding-documents>>.

		This content has moved. Refer to <<string-field-formatters>>.

		[role="exclude",id="alerting-setup-prerequisites"]

[Alerting][Docs] Moving alerting setup to its own page #101323

[Alerting][Docs] Moving alerting setup to its own page #101323

Conversation

ymao1 commented Jun 3, 2021 • edited Loading

Summary

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

elasticmachine commented Jun 4, 2021

ymao1 commented Jun 7, 2021

YulNaumenko left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gchaps left a comment

Choose a reason for hiding this comment

kibanamachine commented Jun 10, 2021

💚 Build Succeeded

Metrics [docs]

Page load bundle

History

kibanamachine commented Jun 10, 2021

💚 Backport successful

ymao1 commented Jun 3, 2021 •

edited

Loading