|
2 | 2 | [[action-types]] |
3 | 3 | == Action and connector types |
4 | 4 |
|
5 | | -{kib} provides the following types of actions: |
| 5 | +Actions are Kibana services or integrations with third-party systems that run as background tasks on the Kibana server when alert conditions are met. {kib} provides the following types of actions: |
6 | 6 |
|
7 | | -* <<email-action-type, Email>> |
8 | | -* <<index-action-type, Index>> |
9 | | -* <<pagerduty-action-type, PagerDuty>> |
10 | | -* <<server-log-action-type, ServerLog>> |
11 | | -* <<slack-action-type, Slack>> |
12 | | -* <<webhook-action-type, Webhook>> |
| 7 | +[cols="2"] |
| 8 | +|=== |
13 | 9 |
|
14 | | -This section describes how to configure connectors and actions for each type. |
| 10 | +a| <<email-action-type, Email>> |
15 | 11 |
|
16 | | -[NOTE] |
17 | | -============================================== |
18 | | -Some action types are paid commercial features, while others are free. |
19 | | -For a comparison of the Elastic license levels, |
20 | | -see https://www.elastic.co/subscriptions[the subscription page]. |
21 | | -============================================== |
22 | | - |
23 | | -[float] |
24 | | -[[email-action-type]] |
25 | | -=== Email |
26 | | - |
27 | | -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. |
28 | | - |
29 | | -[float] |
30 | | -[[email-connector-configuration]] |
31 | | -==== Connector configuration |
32 | | - |
33 | | -Email connectors have the following configuration properties: |
34 | | - |
35 | | -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. |
36 | | -Sender:: The from address for all emails sent with this connector, specified in `user@host-name` format. |
37 | | -Host:: Host name of the service provider. If you are using the <<action-settings, `xpack.actions.whitelistedHosts`>> setting, make sure this hostname is whitelisted. |
38 | | -Port:: The port to connect to on the service provider. |
39 | | -Secure:: If true the connection will use TLS when connecting to the service provider. See https://nodemailer.com/smtp/#tls-options[nodemailer TLS documentation] for more information. |
40 | | -Username:: username for 'login' type authentication. |
41 | | -Password:: password for 'login' type authentication. |
42 | | - |
43 | | -[float] |
44 | | -[[email-action-configuration]] |
45 | | -==== Action configuration |
46 | | - |
47 | | -Email actions have the following configuration properties: |
48 | | - |
49 | | -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. |
50 | | -Subject:: The subject line of the email. |
51 | | -Message:: The message text of the email. Markdown format is supported. |
52 | | - |
53 | | -[float] |
54 | | -[[index-action-type]] |
55 | | -=== Index |
56 | | - |
57 | | -The index action type will index a document into {es}. |
58 | | - |
59 | | -[float] |
60 | | -[[index-connector-configuration]] |
61 | | -==== Connector configuration |
62 | | - |
63 | | -Index connectors have the following configuration properties: |
64 | | - |
65 | | -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. |
66 | | -Index:: The {es} index to be written to. |
67 | | -Refresh:: Setting for the {ref}/docs-refresh.html[refresh] policy for the write request. |
68 | | -Execution time field:: This field will be automatically set to the time the alert condition was detected. |
69 | | - |
70 | | -[float] |
71 | | -[[index-action-configuration]] |
72 | | -==== Action configuration |
73 | | - |
74 | | -Index actions have the following properties: |
75 | | - |
76 | | -Document:: The document to index in json format. |
77 | | - |
78 | | -[float] |
79 | | -[[pagerduty-action-type]] |
80 | | -=== PagerDuty |
81 | | - |
82 | | -The PagerDuty action type uses the https://v2.developer.pagerduty.com/docs/events-api-v2[v2 Events API] to trigger, acknowledge, and resolve PagerDuty alerts. |
83 | | - |
84 | | -[float] |
85 | | -[[pagerduty-connector-configuration]] |
86 | | -==== Connector configuration |
| 12 | +| Send email from your server. |
87 | 13 |
|
88 | | -PagerDuty connectors have the following configuration properties: |
| 14 | +a| <<index-action-type, Index>> |
89 | 15 |
|
90 | | -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. |
91 | | -API URL:: An optional PagerDuty event URL. Defaults to `https://events.pagerduty.com/v2/enqueue`. If you are using the <<action-settings, `xpack.actions.whitelistedHosts`>> setting, make sure the hostname is whitelisted. |
92 | | -Routing Key:: A 32 character PagerDuty Integration Key for an integration on a service or on a global ruleset. |
| 16 | +| Index data into Elasticsearch. |
93 | 17 |
|
94 | | -[float] |
95 | | -[[pagerduty-action-configuration]] |
96 | | -==== Action configuration |
| 18 | +a| <<pagerduty-action-type, PagerDuty>> |
97 | 19 |
|
98 | | -PagerDuty actions have the following properties: |
| 20 | +| Send an event in PagerDuty. |
99 | 21 |
|
100 | | -Severity:: The perceived severity of on the affected system. This can be one of `Critical`, `Error`, `Warning` or `Info`(default). |
101 | | -Event action:: One of `Trigger` (default), `Resolve`, or `Acknowledge`. See https://v2.developer.pagerduty.com/docs/events-api-v2#event-action[event action] for more details. |
102 | | -Dedup Key:: All actions sharing this key will be associated with the same PagerDuty alert. This value is used to correlate trigger and resolution. This value is *optional*, and if unset defaults to `action:<action saved object id>`. The maximum length is *255* characters. See https://v2.developer.pagerduty.com/docs/events-api-v2#alert-de-duplication[alert deduplication] for details. |
103 | | -Timestamp:: An *optional* https://v2.developer.pagerduty.com/v2/docs/types#datetime[ISO-8601 format date-time], indicating the time the event was detected or generated. |
104 | | -Component:: An *optional* value indicating the component of the source machine that is responsible for the event, for example `mysql` or `eth0`. |
105 | | -Group:: An *optional* value indicating the logical grouping of components of a service, for example `app-stack`. |
106 | | -Source:: An *optional* value indicating the affected system, preferably a hostname or fully qualified domain name. Defaults to the {kib} saved object id of the action. |
107 | | -Summary:: An *optional* text summary of the event, defaults to `No summary provided`. The maximum length is 1024 characters. |
108 | | -Class:: An *optional* value indicating the class/type of the event, for example `ping failure` or `cpu load`. |
| 22 | +a| <<server-log-action-type, ServerLog>> |
109 | 23 |
|
110 | | -For more details on these properties, see https://v2.developer.pagerduty.com/v2/docs/send-an-event-events-api-v2[PagerDuty v2 event parameters]. |
| 24 | +| Add a message to a Kibana log. |
111 | 25 |
|
112 | | -[float] |
113 | | -[[server-log-action-type]] |
114 | | -=== Server log |
| 26 | +a| <<slack-action-type, Slack>> |
115 | 27 |
|
116 | | -This action type writes and entry to the {kib} server log. |
| 28 | +| Send a message to a Slack channel or user. |
117 | 29 |
|
118 | | -[float] |
119 | | -[[server-log-connector-configuration]] |
120 | | -==== Connector configuration |
| 30 | +a| <<webhook-action-type, Webhook>> |
121 | 31 |
|
122 | | -Server log connectors have the following configuration properties: |
| 32 | +| Send a request to a web service. |
| 33 | +|=== |
123 | 34 |
|
124 | | -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. |
125 | | - |
126 | | -[float] |
127 | | -[[server-log-action-configuration]] |
128 | | -==== Action configuration |
129 | | - |
130 | | -Server log actions have the following properties: |
131 | | - |
132 | | -Message:: The message to log. |
133 | | - |
134 | | -[float] |
135 | | -[[slack-action-type]] |
136 | | -=== Slack |
137 | | - |
138 | | -The Slack action type uses https://api.slack.com/incoming-webhooks[Slack Incoming Webhooks]. |
139 | | - |
140 | | -[float] |
141 | | -[[slack-connector-configuration]] |
142 | | -==== Connector configuration |
143 | | - |
144 | | -Slack connectors have the following configuration properties: |
145 | | - |
146 | | -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. |
147 | | -Webhook URL:: The URL of the incoming webhook. See https://api.slack.com/messaging/webhooks#getting_started[Slack Incoming Webhooks] for instructions on generating this URL. If you are using the <<action-settings, `xpack.actions.whitelistedHosts`>> setting, make sure the hostname is whitelisted. |
148 | | - |
149 | | -[float] |
150 | | -[[slack-action-configuration]] |
151 | | -==== Action configuration |
152 | | - |
153 | | -Slack actions have the following properties: |
154 | | - |
155 | | -Message:: The message text, converted to the `text` field in the Webhook JSON payload. Currently only the text field is supported. Markdown, images, and other advanced formatting are not yet supported. |
156 | | - |
157 | | -[float] |
158 | | -[[webhook-action-type]] |
159 | | -=== Webhook |
160 | | - |
161 | | -The Webhook action type uses https://github.com/axios/axios[axios] to send a POST or PUT request to a web service. |
162 | | - |
163 | | -[float] |
164 | | -[[webhook-connector-configuration]] |
165 | | -==== Connector configuration |
166 | | - |
167 | | -Webhook connectors have the following configuration properties: |
168 | | - |
169 | | -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. |
170 | | -URL:: The request URL. If you are using the <<action-settings, `xpack.actions.whitelistedHosts`>> setting, make sure the hostname is whitelisted. |
171 | | -Method:: HTTP request method, either `post`(default) or `put`. |
172 | | -Headers:: A set of key-value pairs sent as headers with the request |
173 | | -User:: An optional username. If set, HTTP basic authentication is used. Currently only basic authentication is supported. |
174 | | -Password:: An optional password. If set, HTTP basic authentication is used. Currently only basic authentication is supported. |
175 | | - |
176 | | -[float] |
177 | | -[[webhook-action-configuration]] |
178 | | -==== Action configuration |
179 | | - |
180 | | -Webhook actions have the following properties: |
| 35 | +[NOTE] |
| 36 | +============================================== |
| 37 | +Some action types are paid commercial features, while others are free. |
| 38 | +For a comparison of the Elastic subscription levels, |
| 39 | +see https://www.elastic.co/subscriptions[the subscription page]. |
| 40 | +============================================== |
181 | 41 |
|
182 | | -Body:: A json payload sent to the request URL. |
| 42 | +include::action-types/email.asciidoc[] |
| 43 | +include::action-types/index.asciidoc[] |
| 44 | +include::action-types/pagerduty.asciidoc[] |
| 45 | +include::action-types/server-log.asciidoc[] |
| 46 | +include::action-types/slack.asciidoc[] |
| 47 | +include::action-types/webhook.asciidoc[] |
0 commit comments