Skip to content

Commit df76ebc

Browse files
ymao1kibanamachinegchaps
authored
[Alerting][Docs] Adding template for documenting alert and action types (#92830) (#93348)
* Alert type template * Action type template * Cleanup * Cleanup * Removing callout list * Cleanup * Apply suggestions from code review Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Adding title to actions page * PR fixes * PR fixes * PR fixes * PR fixes Co-authored-by: Kibana Machine <42973632+kibanamachine@users.noreply.github.com> Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> Co-authored-by: Kibana Machine <42973632+kibanamachine@users.noreply.github.com> Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com>
1 parent 3338b75 commit df76ebc

19 files changed

Lines changed: 335 additions & 377 deletions

‎docs/action-type-template.asciidoc‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
[[<ACTION-TYPE>-action-type]]
2+
=== <ACTION-TYPE> action
3+
++++
4+
<titleabbrev><ACTION-TYPE></titleabbrev>
5+
++++
6+
7+
Include a short description of the action type.
8+
9+
[float]
10+
[[<ACTION-TYPE>-connector-configuration]]
11+
==== Connector configuration
12+
13+
<ACTION-TYPE> connectors have the following configuration properties.
14+
15+
////
16+
List of user-facing connector configurations. This should align with the fields available in the Create connector flyout form for this action type.
17+
////
18+
19+
Property1:: A short description of this property.
20+
Property2:: A short description of this property with format hints. This can be specified in `this specific format`.
21+
22+
[float]
23+
[[Preconfigured-<ACTION-TYPE>-configuration]]
24+
==== Preconfigured action type
25+
26+
////
27+
Example preconfigured format for this action type
28+
////
29+
30+
[source,text]
31+
--
32+
my-<ACTION-TYPE>:
33+
name: preconfigured-<ACTION-TYPE>-action-type
34+
actionTypeId: .<ACTION-TYPE>
35+
config:
36+
property1: value1
37+
property2: value2
38+
secrets:
39+
property3: value3
40+
--
41+
42+
[float]
43+
[[<ACTION-TYPE>-connector-config-properties]]
44+
////
45+
List of properties from the ConfigSchema and SecretsSchema for this action type.
46+
////
47+
Config defines information for the action type.
48+
49+
`property1`:: A short description of this property.
50+
`property2`:: A short descriptionn of this property.
51+
52+
Secrets defines sensitive information for the action type.
53+
54+
`property3`:: A short descriptionn of this property.
55+
56+
[float]
57+
[[<ACTION-TYPE>-action-configuration]]
58+
==== Action configuration
59+
60+
<ACTION-TYPE> actions have the following configuration properties.
61+
62+
////
63+
List of user-facing action configurations. This should align with the fields available in the Action section of the Create/Update alert flyout.
64+
////
65+
66+
Property1:: A short description of this property.
67+
Property2:: A short description of this property with format hints. This can be specified in `this specific format`.
68+
69+
////
70+
Optional - additional configuration details here
71+
[[configuring-<ACTION-TYPE>]]
72+
==== Configure <ACTION-TYPE>
73+
////

‎docs/alert-type-template.asciidoc‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
[[alert-type-<ALERT TYPE>]]
2+
=== <ALERT TYPE>
3+
4+
Include a short description of the alert type.
5+
6+
[float]
7+
==== Create the alert
8+
9+
Fill in the <<defining-alerts-general-details, alert details>>, then select *<ALERT TYPE>*.
10+
11+
[float]
12+
==== Define the conditions
13+
14+
Define properties to detect the condition.
15+
16+
////
17+
Optional, include a screenshot
18+
[role="screenshot"]
19+
image::user/alerting/images/alert-types-<ALERT TYPE>-conditions.png[Conditions for <ALERT TYPE> alert type]
20+
////
21+
22+
Condition1:: This is a condition the user must define.
23+
Condition2:: This is another condition the user must define.
24+
25+
[float]
26+
==== Add action variables
27+
28+
<<defining-alerts-actions-details, Add an action>> to run when the alert condition is met. The following variables are specific to the <ALERT TYPE> alert. You can also specify <<defining-alerts-actions-variables, variables common to all alerts>>.
29+
30+
`context.variableA`:: A short description of the context variable defined by the alert type.
31+
`context.variableB`:: A short description of the context variable defined by the alert type with an example. Example: `this is what variableB outputs`.
32+
33+
////
34+
Optional, include a step-by-step example for creating this alert
35+
[float]
36+
==== Example
37+
38+
In this section, you will use the {kib} <<add-sample-data, weblog sample dataset>> to setup and tune the conditions on an <ALERT TYPE> alert. For this example, we want to detect when <DESCRIBE THE CONDITIONS>.
39+
////

‎docs/user/alerting/action-types/email.asciidoc‎

Lines changed: 20 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
[role="xpack"]
22
[[email-action-type]]
33
=== Email action
4+
++++
5+
<titleabbrev>Email</titleabbrev>
6+
++++
47

58
The email action type uses the SMTP protocol to send mail message, using an integration of https://nodemailer.com/[Nodemailer]. Email message text is sent as both plain text and html text.
69

@@ -10,14 +13,15 @@ NOTE: For emails to have a footer with a link back to {kib}, set the <<server-pu
1013
[[email-connector-configuration]]
1114
==== Connector configuration
1215

13-
Email connectors have the following configuration properties:
16+
Email connectors have the following configuration properties.
1417

1518
Name:: The name of the connector. The name is used to identify a connector in the management UI connector listing, or in the connector list when configuring an action.
1619
Sender:: The from address for all emails sent with this connector. This can be specified in `user@host-name` format or as `"human name <user@host-name>"` format. See the https://nodemailer.com/message/addresses/[Nodemailer address documentation] for more information.
1720
Host:: Host name of the service provider. If you are using the <<action-settings, `xpack.actions.allowedHosts`>> setting, make sure this hostname is added to the allowed hosts.
1821
Port:: The port to connect to on the service provider.
1922
Secure:: If true, the connection will use TLS when connecting to the service provider. Refer to the https://nodemailer.com/smtp/#tls-options[Nodemailer TLS documentation] for more information. If not true, the connection will initially connect over TCP, then attempt to switch to TLS via the SMTP STARTTLS command.
20-
User:: Username for login type authentication.
23+
Require authentication:: If true, a username and password for login type authentication must be provided.
24+
Username:: Username for login type authentication.
2125
Password:: Password for login type authentication.
2226

2327
[float]
@@ -39,56 +43,33 @@ Password:: Password for login type authentication.
3943
password: passwordkeystorevalue
4044
--
4145

42-
[[email-connector-config-properties]]
43-
**`config`** defines the action type specific to the configuration and contains the following properties:
46+
Config defines information for the action type.
4447

45-
[cols="2*<"]
46-
|===
48+
`service`:: The name of a https://nodemailer.com/smtp/well-known/[well-known email service provider]. If `service` is provided, `host`, `port`, and `secure` properties are ignored. For more information on the `gmail` service value, see the https://nodemailer.com/usage/using-gmail/[Nodemailer Gmail documentation].
49+
`from`:: An email address that corresponds to *Sender*.
50+
`host`:: A string that corresponds to *Host*.
51+
`port`:: A number that corresponds to *Port*.
52+
`secure`:: A boolean that corresponds to *Secure*.
53+
`hasAuth`:: A boolean that corresponds to *Requires authentication*. If `true`, this connector will require values for `user` and `password` inside the secrets configuration. Defaults to `true`.
4754

48-
| `service`
49-
| The name of a https://nodemailer.com/smtp/well-known/[well-known email service provider]. If `service` is provided, `host`, `port`, and `secure` properties are ignored. For more information on the `gmail` service value, see the (https://nodemailer.com/usage/using-gmail/)[Nodemailer Gmail documentation].
55+
Secrets defines sensitive information for the action type.
5056

51-
| `from`
52-
| An email address that corresponds to *Sender*.
57+
`user`:: A string that corresponds to *Username*. Required if `hasAuth` is set to `true`.
58+
`password`:: A string that corresponds to *Password*. Should be stored in the <<creating-keystore, {kib} keystore>>. Required if `hasAuth` is set to `true`.
5359

54-
| `host`
55-
| A string that corresponds to *Host*.
56-
57-
| `port`
58-
| A number that corresponds to *Port*.
59-
60-
| `secure`
61-
| A boolean that corresponds to *Secure*.
62-
63-
| `hasAuth`
64-
| If `true`, this connector will require values for `user` and `password` inside the secrets configuration. Defaults to `true`.
65-
66-
|===
67-
68-
**`secrets`** defines sensitive information for the action type and contains the following properties:
69-
70-
[cols="2*<"]
71-
|===
72-
73-
| `user`
74-
| A string that corresponds to *User*. Required if `hasAuth` is set to `true`.
75-
76-
| `password`
77-
| A string that corresponds to *Password*. Should be stored in the <<creating-keystore, {kib} keystore>>. Required if `hasAuth` is set to `true`.
78-
79-
|===
8060

61+
[float]
8162
[[email-action-configuration]]
8263
==== Action configuration
8364

84-
Email actions have the following configuration properties:
65+
Email actions have the following configuration properties.
8566

86-
To, CC, BCC:: Each is a list of addresses. Addresses can be specified in `user@host-name` format, or in `name <user@host-name>` format. One of To, CC, or BCC must contain an entry.
67+
To, CC, BCC:: Each item is a list of addresses. Addresses can be specified in `user@host-name` format, or in `name <user@host-name>` format. One of To, CC, or BCC must contain an entry.
8768
Subject:: The subject line of the email.
8869
Message:: The message text of the email. Markdown format is supported.
8970

9071
[[configuring-email]]
91-
==== Configuring email accounts
72+
==== Configuring email accounts for well-known services
9273

9374
The email action can send email using many popular SMTP email services.
9475

‎docs/user/alerting/action-types/index.asciidoc‎

Lines changed: 13 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,17 @@
11
[role="xpack"]
22
[[index-action-type]]
33
=== Index action
4+
++++
5+
<titleabbrev>Index</titleabbrev>
6+
++++
47

58
The index action type will index a document into {es}. See also the {ref}/indices-create-index.html[create index API].
69

710
[float]
811
[[index-connector-configuration]]
912
==== Connector configuration
1013

11-
Index connectors have the following configuration properties:
14+
Index connectors have the following configuration properties.
1215

1316
Name:: The name of the connector. The name is used to identify a connector in the management UI connector listing, or in the connector list when configuring an action.
1417
Index:: The {es} index to be written to.
@@ -30,32 +33,24 @@ Execution time field:: This field will be automatically set to the time the ale
3033
executionTimeField: somedate
3134
--
3235

33-
[[index-connector-config-properties]]
34-
**`config`** defines the action type specific to the configuration and contains the following properties:
35-
36-
[cols="2*<"]
37-
|===
38-
39-
|`index`
40-
| A string that corresponds to *Index*.
41-
42-
|`refresh`
43-
| A boolean that corresponds to *Refresh*. Defaults to `false`.
44-
45-
|`executionTimeField`
46-
| A string that corresponds to *Execution time field*.
47-
48-
|===
36+
Config defines information for the action type.
4937

38+
`index`:: A string that corresponds to *Index*.
39+
`refresh`:: A boolean that corresponds to *Refresh*. Defaults to `false`.
40+
`executionTimeField`:: A string that corresponds to *Execution time field*.
5041

5142
[float]
5243
[[index-action-configuration]]
5344
==== Action configuration
5445

55-
Index actions have the following properties:
46+
Index actions have the following properties.
5647

5748
Document:: The document to index in JSON format.
5849

50+
[float]
51+
[[index-action-example]]
52+
==== Example
53+
5954
Example of the index document for Index Threshold alert:
6055

6156
[source,text]

‎docs/user/alerting/action-types/jira.asciidoc‎

Lines changed: 13 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,17 @@
11
[role="xpack"]
22
[[jira-action-type]]
33
=== Jira action
4+
++++
5+
<titleabbrev>Jira</titleabbrev>
6+
++++
47

58
The Jira action type uses the https://developer.atlassian.com/cloud/jira/platform/rest/v2/[REST API v2] to create Jira issues.
69

710
[float]
811
[[jira-connector-configuration]]
912
==== Connector configuration
1013

11-
Jira connectors have the following configuration properties:
14+
Jira connectors have the following configuration properties.
1215

1316
Name:: The name of the connector. The name is used to identify a connector in the **Stack Management** UI connector listing, and in the connector list when configuring an action.
1417
URL:: Jira instance URL.
@@ -33,37 +36,21 @@ API token (or password):: Jira API authentication token (or password) for HTTP
3336
apiToken: tokenkeystorevalue
3437
--
3538

36-
[[jira-connector-config-properties]]
37-
**`config`** defines the action type specific to the configuration and contains the following properties:
39+
Config defines information for the action type.
3840

39-
[cols="2*<"]
40-
|===
41+
`apiUrl`:: An address that corresponds to *URL*.
42+
`projectKey`:: A key that corresponds to *Project Key*.
4143

42-
| `apiUrl`
43-
| An address that corresponds to *URL*.
44+
Secrets defines sensitive information for the action type.
4445

45-
| `projectKey`
46-
| A key that corresponds to *Project Key*.
47-
48-
|===
49-
50-
**`secrets`** defines sensitive information for the action type and contains the following properties:
51-
52-
[cols="2*<"]
53-
|===
54-
55-
| `email`
56-
| A string that corresponds to *Email*.
57-
58-
| `apiToken`
59-
| A string that corresponds to *API Token*. Should be stored in the <<creating-keystore, {kib} keystore>>.
60-
61-
|===
46+
`email`:: A string that corresponds to *Email*.
47+
`apiToken`:: A string that corresponds to *API Token*. Should be stored in the <<creating-keystore, {kib} keystore>>.
6248

49+
[float]
6350
[[jira-action-configuration]]
6451
==== Action configuration
6552

66-
Jira actions have the following configuration properties:
53+
Jira actions have the following configuration properties.
6754

6855
Issue type:: The type of the issue.
6956
Priority:: The priority of the incident.
@@ -74,6 +61,6 @@ Parent:: The ID or key of the parent issue. Only for `Subtask` issue types.
7461
Additional comments:: Additional information for the client, such as how to troubleshoot the issue.
7562

7663
[[configuring-jira]]
77-
==== Configuring and testing Jira
64+
==== Configure Jira
7865

7966
Jira offers free https://www.atlassian.com/software/jira/free[Instances], which you can use to test incidents.

0 commit comments

Comments
 (0)