Skip to content

Commit

Permalink
[Alerting][Docs] Adding template for documenting alert and action typ…
Browse files Browse the repository at this point in the history 
…es (elastic#92830)

* 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>
# Conflicts:
#	docs/user/alerting/defining-alerts.asciidoc
  • Loading branch information
@ymao1
ymao1 committed Mar 2, 2021
1 parent 2f0212f commit bdb8b6c
Show file tree
Hide file tree
Showing 19 changed files with 335 additions and 397 deletions.
73 changes: 73 additions & 0 deletions docs/action-type-template.asciidoc
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
[[<ACTION-TYPE>-action-type]]
=== <ACTION-TYPE> action
++++
<titleabbrev><ACTION-TYPE></titleabbrev>
++++

Include a short description of the action type.

[float]
[[<ACTION-TYPE>-connector-configuration]]
==== Connector configuration

<ACTION-TYPE> connectors have the following configuration properties.

////
List of user-facing connector configurations. This should align with the fields available in the Create connector flyout form for this action type.
////

Property1:: A short description of this property.
Property2:: A short description of this property with format hints. This can be specified in `this specific format`.

[float]
[[Preconfigured-<ACTION-TYPE>-configuration]]
==== Preconfigured action type

////
Example preconfigured format for this action type
////

[source,text]
--
my-<ACTION-TYPE>:
name: preconfigured-<ACTION-TYPE>-action-type
actionTypeId: .<ACTION-TYPE>
config:
property1: value1
property2: value2
secrets:
property3: value3
--

[float]
[[<ACTION-TYPE>-connector-config-properties]]
////
List of properties from the ConfigSchema and SecretsSchema for this action type.
////
Config defines information for the action type.

`property1`:: A short description of this property.
`property2`:: A short descriptionn of this property.

Secrets defines sensitive information for the action type.

`property3`:: A short descriptionn of this property.

[float]
[[<ACTION-TYPE>-action-configuration]]
==== Action configuration

<ACTION-TYPE> actions have the following configuration properties.

////
List of user-facing action configurations. This should align with the fields available in the Action section of the Create/Update alert flyout.
////

Property1:: A short description of this property.
Property2:: A short description of this property with format hints. This can be specified in `this specific format`.

////
Optional - additional configuration details here
[[configuring-<ACTION-TYPE>]]
==== Configure <ACTION-TYPE>
////
39 changes: 39 additions & 0 deletions docs/alert-type-template.asciidoc
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
[[alert-type-<ALERT TYPE>]]
=== <ALERT TYPE>

Include a short description of the alert type.

[float]
==== Create the alert

Fill in the <<defining-alerts-general-details, alert details>>, then select *<ALERT TYPE>*.

[float]
==== Define the conditions

Define properties to detect the condition.

////
Optional, include a screenshot
[role="screenshot"]
image::user/alerting/images/alert-types-<ALERT TYPE>-conditions.png[Conditions for <ALERT TYPE> alert type]
////

Condition1:: This is a condition the user must define.
Condition2:: This is another condition the user must define.

[float]
==== Add action variables

<<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>>.

`context.variableA`:: A short description of the context variable defined by the alert type.
`context.variableB`:: A short description of the context variable defined by the alert type with an example. Example: `this is what variableB outputs`.

////
Optional, include a step-by-step example for creating this alert
[float]
==== Example
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>.
////
59 changes: 20 additions & 39 deletions docs/user/alerting/action-types/email.asciidoc
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
[role="xpack"]
[[email-action-type]]
=== Email action
++++
<titleabbrev>Email</titleabbrev>
++++

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.

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

Email connectors have the following configuration properties:
Email connectors have the following configuration properties.

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.
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.
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.
Port:: The port to connect to on the service provider.
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.
User:: Username for login type authentication.
Require authentication:: If true, a username and password for login type authentication must be provided.
Username:: Username for login type authentication.
Password:: Password for login type authentication.

[float]
Expand All @@ -39,56 +43,33 @@ Password:: Password for login type authentication.
password: passwordkeystorevalue
--

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

[cols="2*<"]
|===
`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].
`from`:: An email address that corresponds to *Sender*.
`host`:: A string that corresponds to *Host*.
`port`:: A number that corresponds to *Port*.
`secure`:: A boolean that corresponds to *Secure*.
`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`.

| `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].
Secrets defines sensitive information for the action type.

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

| `host`
| A string that corresponds to *Host*.

| `port`
| A number that corresponds to *Port*.

| `secure`
| A boolean that corresponds to *Secure*.

| `hasAuth`
| If `true`, this connector will require values for `user` and `password` inside the secrets configuration. Defaults to `true`.

|===

**`secrets`** defines sensitive information for the action type and contains the following properties:

[cols="2*<"]
|===

| `user`
| A string that corresponds to *User*. Required if `hasAuth` is set to `true`.

| `password`
| A string that corresponds to *Password*. Should be stored in the <<creating-keystore, {kib} keystore>>. Required if `hasAuth` is set to `true`.

|===

[float]
[[email-action-configuration]]
==== Action configuration

Email actions have the following configuration properties:
Email actions have the following configuration properties.

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.
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.
Subject:: The subject line of the email.
Message:: The message text of the email. Markdown format is supported.

[[configuring-email]]
==== Configuring email accounts
==== Configuring email accounts for well-known services

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

Expand Down
31 changes: 13 additions & 18 deletions docs/user/alerting/action-types/index.asciidoc
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,17 @@
[role="xpack"]
[[index-action-type]]
=== Index action
++++
<titleabbrev>Index</titleabbrev>
++++

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

[float]
[[index-connector-configuration]]
==== Connector configuration

Index connectors have the following configuration properties:
Index connectors have the following configuration properties.

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.
Index:: The {es} index to be written to.
Expand All @@ -30,32 +33,24 @@ Execution time field:: This field will be automatically set to the time the ale
executionTimeField: somedate
--

[[index-connector-config-properties]]
**`config`** defines the action type specific to the configuration and contains the following properties:

[cols="2*<"]
|===

|`index`
| A string that corresponds to *Index*.

|`refresh`
| A boolean that corresponds to *Refresh*. Defaults to `false`.

|`executionTimeField`
| A string that corresponds to *Execution time field*.

|===
Config defines information for the action type.

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

[float]
[[index-action-configuration]]
==== Action configuration

Index actions have the following properties:
Index actions have the following properties.

Document:: The document to index in JSON format.

[float]
[[index-action-example]]
==== Example

Example of the index document for Index Threshold alert:

[source,text]
Expand Down
39 changes: 13 additions & 26 deletions docs/user/alerting/action-types/jira.asciidoc
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,17 @@
[role="xpack"]
[[jira-action-type]]
=== Jira action
++++
<titleabbrev>Jira</titleabbrev>
++++

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

[float]
[[jira-connector-configuration]]
==== Connector configuration

Jira connectors have the following configuration properties:
Jira connectors have the following configuration properties.

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.
URL:: Jira instance URL.
Expand All @@ -33,37 +36,21 @@ API token (or password):: Jira API authentication token (or password) for HTTP
apiToken: tokenkeystorevalue
--

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

[cols="2*<"]
|===
`apiUrl`:: An address that corresponds to *URL*.
`projectKey`:: A key that corresponds to *Project Key*.

| `apiUrl`
| An address that corresponds to *URL*.
Secrets defines sensitive information for the action type.

| `projectKey`
| A key that corresponds to *Project Key*.

|===

**`secrets`** defines sensitive information for the action type and contains the following properties:

[cols="2*<"]
|===

| `email`
| A string that corresponds to *Email*.

| `apiToken`
| A string that corresponds to *API Token*. Should be stored in the <<creating-keystore, {kib} keystore>>.

|===
`email`:: A string that corresponds to *Email*.
`apiToken`:: A string that corresponds to *API Token*. Should be stored in the <<creating-keystore, {kib} keystore>>.

[float]
[[jira-action-configuration]]
==== Action configuration

Jira actions have the following configuration properties:
Jira actions have the following configuration properties.

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

[[configuring-jira]]
==== Configuring and testing Jira
==== Configure Jira

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

0 comments on commit bdb8b6c

Please sign in to comment.