maxmustermann/kibana
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Add developer docs for built-in pagerduty and webhook actions. Add TOC. (#55352)

Browse source
This commit is contained in:
Peter Schretlen 2020-01-23 17:00:14 -05:00 committed by GitHub
parent 6fcf3f0005
commit e39ef65c4c
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 227 additions and 45 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

62
x-pack/legacy/plugins/alerting/README.md
View file

@ -6,6 +6,38 @@ The Kibana alerting plugin provides a common place to set up alerts. You can:
- List the types of registered alerts
- Perform CRUD actions on alerts
----
Table of Contents
- [Kibana alerting](#kibana-alerting)
- [Terminology](#terminology)
- [Usage](#usage)
- [Limitations](#limitations)
- [Alert types](#alert-types)
- [Methods](#methods)
- [Executor](#executor)
- [Example](#example)
- [RESTful API](#restful-api)
- [`POST /api/alert`: Create alert](#post-apialert-create-alert)
- [`DELETE /api/alert/{id}`: Delete alert](#delete-apialertid-delete-alert)
- [`GET /api/alert/_find`: Find alerts](#get-apialertfind-find-alerts)
- [`GET /api/alert/{id}`: Get alert](#get-apialertid-get-alert)
- [`GET /api/alert/types`: List alert types](#get-apialerttypes-list-alert-types)
- [`PUT /api/alert/{id}`: Update alert](#put-apialertid-update-alert)
- [`POST /api/alert/{id}/_enable`: Enable an alert](#post-apialertidenable-enable-an-alert)
- [`POST /api/alert/{id}/_disable`: Disable an alert](#post-apialertiddisable-disable-an-alert)
- [`POST /api/alert/{id}/_mute_all`: Mute all alert instances](#post-apialertidmuteall-mute-all-alert-instances)
- [`POST /api/alert/{alertId}/alert_instance/{alertInstanceId}/_mute`: Mute alert instance](#post-apialertalertidalertinstancealertinstanceidmute-mute-alert-instance)
- [`POST /api/alert/{id}/_unmute_all`: Unmute all alert instances](#post-apialertidunmuteall-unmute-all-alert-instances)
- [`POST /api/alert/{alertId}/alert_instance/{alertInstanceId}/_unmute`: Unmute an alert instance](#post-apialertalertidalertinstancealertinstanceidunmute-unmute-an-alert-instance)
- [`POST /api/alert/{id}/_update_api_key`: Update alert API key](#post-apialertidupdateapikey-update-alert-api-key)
- [Schedule Formats](#schedule-formats)
- [Alert instance factory](#alert-instance-factory)
- [Templating actions](#templating-actions)
- [Examples](#examples)
## Terminology
**Alert Type**: A function that takes parameters and executes actions to alert instances.
@ -205,7 +237,7 @@ server.plugins.alerting.setup.registerType({
Using an alert type requires you to create an alert that will contain parameters and actions for a given alert type. See below for CRUD operations using the API.
#### `POST /api/alert`: Create alert
### `POST /api/alert`: Create alert
Payload:
@ -219,7 +251,7 @@ Payload:
|params|The parameters to pass in to the alert type executor `params` value. This will also validate against the alert type params validator if defined.|object|
|actions|Array of the following:<br> - `group` (string): We support grouping actions in the scenario of escalations or different types of alert instances. If you don't need this, feel free to use `default` as a value.<br>- `id` (string): The id of the action saved object to execute.<br>- `params` (object): The map to the `params` the action type will receive. In order to help apply context to strings, we handle them as mustache templates and pass in a default set of context. (see templating actions).|array|
#### `DELETE /api/alert/{id}`: Delete alert
### `DELETE /api/alert/{id}`: Delete alert
Params:
@ -227,13 +259,13 @@ Params:
|---|---|---|
|id|The id of the alert you're trying to delete.|string|
#### `GET /api/alert/_find`: Find alerts
### `GET /api/alert/_find`: Find alerts
Params:
See the saved objects API documentation for find. All the properties are the same except you cannot pass in `type`.
#### `GET /api/alert/{id}`: Get alert
### `GET /api/alert/{id}`: Get alert
Params:
@ -241,11 +273,11 @@ Params:
|---|---|---|
|id|The id of the alert you're trying to get.|string|
#### `GET /api/alert/types`: List alert types
### `GET /api/alert/types`: List alert types
No parameters.
#### `PUT /api/alert/{id}`: Update alert
### `PUT /api/alert/{id}`: Update alert
Params:
@ -263,7 +295,7 @@ Payload:
|params|The parameters to pass in to the alert type executor `params` value. This will also validate against the alert type params validator if defined.|object|
|actions|Array of the following:<br> - `group` (string): We support grouping actions in the scenario of escalations or different types of alert instances. If you don't need this, feel free to use `default` as a value.<br>- `id` (string): The id of the action saved object to execute.<br>- `params` (object): There map to the `params` the action type will receive. In order to help apply context to strings, we handle them as mustache templates and pass in a default set of context. (see templating actions).|array|
#### `POST /api/alert/{id}/_enable`: Enable an alert
### `POST /api/alert/{id}/_enable`: Enable an alert
Params:
@ -271,7 +303,7 @@ Params:
|---|---|---|
|id|The id of the alert you're trying to enable.|string|
#### `POST /api/alert/{id}/_disable`: Disable an alert
### `POST /api/alert/{id}/_disable`: Disable an alert
Params:
@ -279,7 +311,7 @@ Params:
|---|---|---|
|id|The id of the alert you're trying to disable.|string|
#### `POST /api/alert/{id}/_mute_all`: Mute all alert instances
### `POST /api/alert/{id}/_mute_all`: Mute all alert instances
Params:
@ -287,7 +319,7 @@ Params:
|---|---|---|
|id|The id of the alert you're trying to mute all alert instances for.|string|
#### `POST /api/alert/{alertId}/alert_instance/{alertInstanceId}/_mute`: Mute alert instance
### `POST /api/alert/{alertId}/alert_instance/{alertInstanceId}/_mute`: Mute alert instance
Params:
@ -296,7 +328,7 @@ Params:
|alertId|The id of the alert you're trying to mute an instance for.|string|
|alertInstanceId|The instance id of the alert instance you're trying to mute.|string|
#### `POST /api/alert/{id}/_unmute_all`: Unmute all alert instances
### `POST /api/alert/{id}/_unmute_all`: Unmute all alert instances
Params:
@ -304,7 +336,7 @@ Params:
|---|---|---|
|id|The id of the alert you're trying to unmute all alert instances for.|string|
#### `POST /api/alert/{alertId}/alert_instance/{alertInstanceId}/_unmute`: Unmute an alert instance
### `POST /api/alert/{alertId}/alert_instance/{alertInstanceId}/_unmute`: Unmute an alert instance
Params:
@ -313,13 +345,13 @@ Params:
|alertId|The id of the alert you're trying to unmute an instance for.|string|
|alertInstanceId|The instance id of the alert instance you're trying to unmute.|string|
#### `POST /api/alert/{id}/_update_api_key`: Update alert API key
### `POST /api/alert/{id}/_update_api_key`: Update alert API key
|Property|Description|Type|
|---|---|---|
|id|The id of the alert you're trying to update the API key for. System will use user in request context to generate an API key for.|string|
##### Schedule Formats
## Schedule Formats
A schedule is structured such that the key specifies the format you wish to use and its value specifies the schedule.
We currently support the _Interval format_ which specifies the interval in seconds, minutes, hours or days at which the alert should execute.
@ -347,7 +379,7 @@ There needs to be a way to map alert context into action parameters. For this, w
When an alert instance executes, the first argument is the `group` of actions to execute and the second is the context the alert exposes to templates. We iterate through each action params attributes recursively and render templates if they are a string. Templates have access to the `context` (provided by second argument of `.scheduleActions(...)` on an alert instance) and the alert instance's `state` (provided by the most recent `replaceState` call on an alert instance) as well as `alertId` and `alertInstanceId`.
### Examples
## Examples
The following code would be within an alert type. As you can see `cpuUsage ` will replace the state of the alert instance and `server` is the context for the alert instance to execute. The difference between the two is `cpuUsage ` will be accessible at the next execution.

210
x-pack/plugins/actions/README.md
View file

@ -1,4 +1,4 @@
# Kibana actions
# Kibana Actions
The Kibana actions plugin provides a framework to create executable actions. You can:
@ -10,6 +10,60 @@ The Kibana actions plugin provides a framework to create executable actions. You
- Execute an action, passing it a parameter object.
- Perform CRUD operations on actions.
-----
Table of Contents
- [Kibana Actions](#kibana-actions)
- [Terminology](#terminology)
- [Usage](#usage)
- [Kibana Actions Configuration](#kibana-actions-configuration)
- [Configuration Options](#configuration-options)
- [Whitelisting Built-in Action Types](#whitelisting-built-in-action-types)
- [Configuration Utilities](#configuration-utilities)
- [Action types](#action-types)
- [Methods](#methods)
- [Executor](#executor)
- [Example](#example)
- [RESTful API](#restful-api)
- [`POST /api/action`: Create action](#post-apiaction-create-action)
- [`DELETE /api/action/{id}`: Delete action](#delete-apiactionid-delete-action)
- [`GET /api/action/_find`: Find actions](#get-apiactionfind-find-actions)
- [`GET /api/action/{id}`: Get action](#get-apiactionid-get-action)
- [`GET /api/action/types`: List action types](#get-apiactiontypes-list-action-types)
- [`PUT /api/action/{id}`: Update action](#put-apiactionid-update-action)
- [`POST /api/action/{id}/_execute`: Execute action](#post-apiactionidexecute-execute-action)
- [Firing actions](#firing-actions)
- [Example](#example-1)
- [Built-in Action Types](#built-in-action-types)
- [Server log](#server-log)
- [`config`](#config)
- [`secrets`](#secrets)
- [`params`](#params)
- [Email](#email)
- [`config`](#config-1)
- [`secrets`](#secrets-1)
- [`params`](#params-1)
- [Slack](#slack)
- [`config`](#config-2)
- [`secrets`](#secrets-2)
- [`params`](#params-2)
- [Index](#index)
- [`config`](#config-3)
- [`secrets`](#secrets-3)
- [`params`](#params-3)
- [Webhook](#webhook)
- [`config`](#config-4)
- [`secrets`](#secrets-4)
- [`params`](#params-4)
- [PagerDuty](#pagerduty)
- [`config`](#config-5)
- [`secrets`](#secrets-5)
- [`params`](#params-5)
- [Command Line Utility](#command-line-utility)
## Terminology
**Action Type**: A programatically defined integration with another service, with an expected set of configuration and parameters properties, typically defined with a schema. Plugins can add new
@ -99,7 +153,7 @@ The built-in email action type provides a good example of creating an action typ
Using an action type requires an action to be created that will contain and encrypt configuration for a given action type. See below for CRUD operations using the API.
#### `POST /api/action`: Create action
### `POST /api/action`: Create action
Payload:
@ -110,7 +164,7 @@ Payload:
|config|The configuration the action type expects. See related action type to see what attributes are expected. This will also validate against the action type if config validation is defined.|object|
|secrets|The secrets the action type expects. See related action type to see what attributes are expected. This will also validate against the action type if secrets validation is defined.|object|
#### `DELETE /api/action/{id}`: Delete action
### `DELETE /api/action/{id}`: Delete action
Params:
@ -118,13 +172,13 @@ Params:
|---|---|---|
|id|The id of the action you're trying to delete.|string|
#### `GET /api/action/_find`: Find actions
### `GET /api/action/_find`: Find actions
Params:
See the [saved objects API documentation for find](https://www.elastic.co/guide/en/kibana/master/saved-objects-api-find.html). All the properties are the same except that you cannot pass in `type`.
#### `GET /api/action/{id}`: Get action
### `GET /api/action/{id}`: Get action
Params:
@ -132,11 +186,11 @@ Params:
|---|---|---|
|id|The id of the action you're trying to get.|string|
#### `GET /api/action/types`: List action types
### `GET /api/action/types`: List action types
No parameters.
#### `PUT /api/action/{id}`: Update action
### `PUT /api/action/{id}`: Update action
Params:
@ -152,7 +206,7 @@ Payload:
|config|The configuration the action type expects. See related action type to see what attributes are expected. This will also validate against the action type if config validation is defined.|object|
|secrets|The secrets the action type expects. See related action type to see what attributes are expected. This will also validate against the action type if secrets validation is defined.|object|
#### `POST /api/action/{id}/_execute`: Execute action
### `POST /api/action/{id}/_execute`: Execute action
Params:
@ -181,7 +235,7 @@ The following table describes the properties of the `options` object.
|spaceId|The space id the action is within.|string|
|apiKey|The Elasticsearch API key to use for context. (Note: only required and used when security is enabled).|string|
### Example
## Example
This example makes action `3c5b2bd4-5424-4e4b-8cf5-c0a58c762cc5` send an email. The action plugin will load the saved object and find what action type to call with `params`.
@ -202,33 +256,45 @@ server.plugins.actions.execute({
Kibana ships with a set of built-in action types:
- server log: logs messages to the Kibana log using `server.log()`
- email: send an email
- slack: post a message to a slack channel
- index: index document(s) into elasticsearch
|Type|Id|Description|
|---|---|---|
|[Server log](#server-log)|`.log`|Logs messages to the Kibana log using `server.log()`|
|[Email](#email)|`.email`|Sends an email using SMTP|
|[Slack](#slack)|`.slack`|Posts a message to a slack channel|
|[Index](#index)|`.index`|Indexes document(s) into Elasticsearch|
|[Webhook](#webhook)|`.webhook`|Send a payload to a web service using HTTP POST or PUT|
|[PagerDuty](#pagerduty)|`.pagerduty`|Trigger, resolve, or acknowlege an incident to a PagerDuty service|
## server log, action id: `.log`
----
## Server log
ID: `.log`
The params properties are modelled after the arguments to the [Hapi.server.log()](https://hapijs.com/api#-serverlogtags-data-timestamp) function.
#### config properties
### `config`
|Property|Description|Type|
|---|---|---|
|-|This action has no config properties.|-|
This action has no `config` properties.
#### params properties
### `secrets`
This action type has no `secrets` properties.
### `params`
|Property|Description|Type|
|---|---|---|
|message|The message to log.|string|
|tags|Tags associated with the message to log.|string[] _(optional)_|
## email, action id: `.email`
----
## Email
ID: `.email`
This action type uses [nodemailer](https://nodemailer.com/about/) to send emails.
#### config properties
### `config`
Either the property `service` must be provided, or the `host` and `port` properties must be provided. If `service` is provided, `host`, `port` and `secure` are ignored. For more information on the `gmail` service value specifically, see the [nodemailer gmail documentation](https://nodemailer.com/usage/using-gmail/).
@ -242,11 +308,16 @@ The `from` field can be specified as in typical `"user@host-name"` format, or as
|host|host name of the service provider|string _(optional)_|
|port|port number of the service provider|number _(optional)_|
|secure|whether to use TLS with the service provider|boolean _(optional)_|
|user|userid to use with the service provider|string|
|password|password to use with the service provider|string|
|from|the from address for all emails sent with this action type|string|
#### params properties
### `secrets`
|Property|Description|Type|
|---|---|---|
|user|userid to use with the service provider|string|
|password|password to use with the service provider|string|
### `params`
There must be at least one entry in the `to`, `cc` and `bcc` arrays.
@ -262,34 +333,49 @@ The `to`, `cc`, and `bcc` array entries can be in the same format as the `from`
|subject|the subject line of the email|string|
|message|the message text|string|
## slack, action id: `.slack`
----
## Slack
ID: `.slack`
This action type interfaces with the [Slack Incoming Webhooks feature](https://api.slack.com/incoming-webhooks). Currently the params property `message` will be used as the `text` property of the Slack incoming message. Additional function may be provided later.
#### config properties
### `config`
This action type has no `config` properties.
### `secrets`
|Property|Description|Type|
|---|---|---|
|webhookUrl|the url of the Slack incoming webhook|string|
#### params properties
### `params`
|Property|Description|Type|
|---|---|---|
|message|the message text|string|
----
## index, action id: `.index`
## Index
ID: `.index`
The config and params properties are modelled after the [Watcher Index Action](https://www.elastic.co/guide/en/elasticsearch/reference/master/actions-index.html). The index can be set in the config or params, and if set in config, then the index set in the params will be ignored.
#### config properties
### `config`
|Property|Description|Type|
|---|---|---|
|index|The Elasticsearch index to index into.|string _(optional)_|
#### params properties
### `secrets`
This action type has no `secrets` properties.
### `params`
|Property|Description|Type|
|---|---|---|
@ -299,6 +385,70 @@ The config and params properties are modelled after the [Watcher Index Action](h
|refresh|Setting of the refresh policy for the write request|boolean _(optional)_|
|body|The documument body/bodies to index.|object or object[]|
----
## Webhook
ID: `.webhook`
The webhook action uses [axios](https://github.com/axios/axios) to send a POST or PUT request to a web service.
### `config`
|Property|Description|Type|
|---|---|---|
|url|Request URL|string|
|method|HTTP request method, either `post`_(default)_ or `put`|string _(optional)_|
|headers|Key-value pairs of the headers to send with the request|object, keys and values are strings _(optional)_|
### `secrets`
|Property|Description|Type|
|---|---|---|
|user|Username for HTTP Basic authentication|string|
|password|Password for HTTP Basic authentication|string|
### `params`
|Property|Description|Type|
|---|---|---|
|body|The HTTP request body|string _(optional)_|
----
## PagerDuty
ID: `.pagerduty`
The PagerDuty action uses the [V2 Events API](https://v2.developer.pagerduty.com/docs/events-api-v2) to trigger, acknowlege, and resolve PagerDuty alerts.
### `config`
|Property|Description|Type|
|---|---|---|
|apiUrl|PagerDuty event URL. Defaults to `https://events.pagerduty.com/v2/enqueue`|string _(optional)_|
### `secrets`
|Property|Description|Type|
|---|---|---|
|routingKey|This is the 32 character PagerDuty Integration Key for an integration on a service or on a global ruleset.|string|
### `params`
|Property|Description|Type|
|---|---|---|
|eventAction|One of `trigger` _(default)_, `resolve`, or `acknowlege`. See [event action](https://v2.developer.pagerduty.com/docs/events-api-v2#event-action) for more details.| string _(optional)_|
|dedupKey|All actions sharing this key will be associated with the same PagerDuty alert. Used to correlate trigger and resolution. Defaults to `action:<action id>`. The maximum length is **255** characters. See [alert deduplication](https://v2.developer.pagerduty.com/docs/events-api-v2#alert-de-duplication) for details. | string _(optional)_|
|summary|A text summary of the event, defaults to `No summary provided`. The maximum length is **1024** characters. | string _(optional)_|
|source|The affected system, preferably a hostname or fully qualified domain name. Defaults to `Kibana Action <action id>`.| string _(optional)_|
|severity|The perceived severity of on the affected system. This can be one of `critical`, `error`, `warning` or `info`_(default)_.| string _(optional)_|
|timestamp|An [ISO-8601 format date-time](https://v2.developer.pagerduty.com/v2/docs/types#datetime), indicating the time the event was detected or generated.| string _(optional)_|
|component|The component of the source machine that is responsible for the event, for example `mysql` or `eth0`.| string _(optional)_|
|group|Logical grouping of components of a service, for example `app-stack`.| string _(optional)_|
|class|The class/type of the event, for example `ping failure` or `cpu load`.| string _(optional)_|
For more details see [PagerDuty v2 event parameters](https://v2.developer.pagerduty.com/v2/docs/send-an-event-events-api-v2).
# Command Line Utility
The [`kbn-action`](https://github.com/pmuellr/kbn-action) tool can be used to send HTTP requests to the Actions plugin. For instance, to create a Slack action from the `.slack` Action Type, use the following command: