192 lines
6.3 KiB
Plaintext
192 lines
6.3 KiB
Plaintext
|
[[actions-pagerduty]]
|
||
|
|
=== PagerDuty Action
|
||
|
|
|
||
|
|
Use the PagerDuty action to create events in https://pagerduty.com/[
|
||
|
|
PagerDuty]. To create PagerDuty events, you must <<configuring-pagerduty,
|
||
|
|
configure at least one PagerDuty account>> in `elasticsearch.yml`.
|
||
|
|
|
||
|
|
[[configuring-pagerduty-actions]]
|
||
|
|
==== Configuring PagerDuty Actions
|
||
|
|
|
||
|
|
You configure PagerDuty actions in the `actions` array. Action-specific attributes
|
||
|
|
are specified using the `pagerduty` keyword.
|
||
|
|
|
||
|
|
The following snippet shows a simple PagerDuty action definition:
|
||
|
|
|
||
|
|
[source,js]
|
||
|
|
--------------------------------------------------
|
||
|
|
"actions" : {
|
||
|
|
"notify-pagerduty" : {
|
||
|
|
"transform" : { ... },
|
||
|
|
"throttle_period" : "5m",
|
||
|
|
"pagerduty" : {
|
||
|
|
"description" : "Main system down, please check!" <1>
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
--------------------------------------------------
|
||
|
|
<1> Description of the message
|
||
|
|
|
||
|
|
|
||
|
|
[[adding-context-and-payloads-to-pagerduty-actions]]
|
||
|
|
==== Adding Meta Information to a PagerDuty Incident
|
||
|
|
|
||
|
|
To give the PagerDuty incident some more context, you can attach the
|
||
|
|
payload as well as an array of contexts to the action.
|
||
|
|
|
||
|
|
[source,js]
|
||
|
|
--------------------------------------------------
|
||
|
|
"actions" : {
|
||
|
|
"notify-pagerduty" : {
|
||
|
|
"throttle_period" : "5m",
|
||
|
|
"pagerduty" : {
|
||
|
|
"account" : "team1",
|
||
|
|
"description" : "Main system down, please check! Happened at {{ctx.execution_time}}"
|
||
|
|
"attach_payload" : true,
|
||
|
|
"client" : "/foo/bar/{{ctx.watch_id}}",
|
||
|
|
"client_url" : "http://www.example.org/",
|
||
|
|
"context" : [
|
||
|
|
{
|
||
|
|
"type": "link",
|
||
|
|
"href": "http://acme.pagerduty.com"
|
||
|
|
},{
|
||
|
|
"type": "link",
|
||
|
|
"href": "http://acme.pagerduty.com",
|
||
|
|
"text": "View the incident on {{ctx.payload.link}}"
|
||
|
|
}
|
||
|
|
]
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
--------------------------------------------------
|
||
|
|
|
||
|
|
|
||
|
|
[[pagerduty-action-attributes]]
|
||
|
|
==== Pagerduty Action Attributes
|
||
|
|
|
||
|
|
[cols=",^,", options="header"]
|
||
|
|
|======
|
||
|
|
| Name |Required | Description
|
||
|
|
| `account` | no | The account to use, falls back to the default one.
|
||
|
|
The account needs a `service_key_api` attribute.
|
||
|
|
|======
|
||
|
|
|
||
|
|
|
||
|
|
[[pagerduty-event-trigger-incident-attributes]]
|
||
|
|
.Pagerduty Event Trigger Incident Attributes
|
||
|
|
[cols=",^,", options="header"]
|
||
|
|
|======
|
||
|
|
| Name |Required | Description
|
||
|
|
|
||
|
|
| `description` | yes | A quick description for this event
|
||
|
|
|
||
|
|
| `event_type` | no | The event type to sent. Must be one of `trigger`,
|
||
|
|
`resolve` or `acknowledge`. Defaults to `trigger`.
|
||
|
|
|
||
|
|
| `incident_key` | no | The incident key on the pagerduty side, also used
|
||
|
|
for de-duplication and allows to resolve or acknowledge
|
||
|
|
incidents.
|
||
|
|
|
||
|
|
| `client` | no | Name of the client triggering the incident, i.e.
|
||
|
|
`Watcher Monitoring`
|
||
|
|
|
||
|
|
| `client_url` | no | A client URL to visit to get more detailed information.
|
||
|
|
|
||
|
|
| `attach_payload` | no | If set to `true` the payload is attached as a detail
|
||
|
|
to the API call. Defaults to `false`.
|
||
|
|
|
||
|
|
| `contexts` | no | An array of objects, that allow you to provide
|
||
|
|
additional links or images in order to provide more
|
||
|
|
context to the trigger.
|
||
|
|
|
||
|
|
| `proxy.host` | no | The proxy host to use (only in combination with `proxy.port`)
|
||
|
|
|
||
|
|
| `proxy.port` | no | The proxy port to use (only in combination with `proxy.host`)
|
||
|
|
|======
|
||
|
|
|
||
|
|
You can configure defaults for the above values for the whole service using the
|
||
|
|
`xpack.notification.pagerduty.event_defaults.*` properties as well as
|
||
|
|
per account using `xpack.notification.pagerduty.account.your_account_name.event_defaults.*`
|
||
|
|
|
||
|
|
NOTE: All of those objects have templating support, so you can use data from the
|
||
|
|
context and the payload as part of all the fields.
|
||
|
|
|
||
|
|
[[pagerduty-event-trigger-context-attributes]]
|
||
|
|
.Pagerduty Event Trigger Context Attributes
|
||
|
|
[cols=",^,", options="header"]
|
||
|
|
|======
|
||
|
|
| Name |Required | Description
|
||
|
|
|
||
|
|
| `type` | yes | One of `link` or `image`.
|
||
|
|
|
||
|
|
| `href` | yes/no | A link to include more information. Must be there if the
|
||
|
|
type is `link`, optional if the type is `image`
|
||
|
|
|
||
|
|
| `src` | no | A src attribute for the `image` type.
|
||
|
|
|======
|
||
|
|
|
||
|
|
[[configuring-pagerduty]]
|
||
|
|
==== Configuring PagerDuty Accounts
|
||
|
|
|
||
|
|
You configure the accounts {watcher} uses to communicate with PagerDuty in
|
||
|
|
the `xpack.notification.pagerduty` namespace in `elasticsearch.yml`.
|
||
|
|
|
||
|
|
To configure a PagerDuty account, you need the API integration key for
|
||
|
|
the PagerDuty service you want to send notifications to. To get the
|
||
|
|
key:
|
||
|
|
|
||
|
|
. Log in to http://pagerduty.com[pagerduty.com] as an account administrator.
|
||
|
|
. Go to **Configuration > Services** and select the PagerDuty service. The
|
||
|
|
service must use the API integration.
|
||
|
|
+
|
||
|
|
image::pagerduty-services.jpg[]
|
||
|
|
|
||
|
|
. Click the **Integrations** tab and copy the API integration key.
|
||
|
|
+
|
||
|
|
image::pagerduty-integrations.jpg[]
|
||
|
|
|
||
|
|
To configure a PagerDuty account in `elasticsearch.yml`, at a minimum you
|
||
|
|
must specify an account name and integration key:
|
||
|
|
|
||
|
|
[source,yaml]
|
||
|
|
--------------------------------------------------
|
||
|
|
xpack.notification.pagerduty:
|
||
|
|
account:
|
||
|
|
my_pagerduty_account:
|
||
|
|
service_api_key: d3b07384d113edec49eaa6238ad5ff0
|
||
|
|
--------------------------------------------------
|
||
|
|
|
||
|
|
You can also specify defaults for the <<pagerduty-event-trigger-incident-attributes,
|
||
|
|
PagerDuty event attributes>>:
|
||
|
|
.
|
||
|
|
|
||
|
|
[source,yaml]
|
||
|
|
--------------------------------------------------
|
||
|
|
xpack.notification.pagerduty:
|
||
|
|
account:
|
||
|
|
my_pagerduty_account:
|
||
|
|
service_api_key: d3b07384d113edec49eaa6238ad5ff0
|
||
|
|
event_defaults:
|
||
|
|
description: "Watch notification"
|
||
|
|
incident_key: "my_incident_key"
|
||
|
|
client: "my_client"
|
||
|
|
client_url: http://www.example.org
|
||
|
|
event_type: trigger
|
||
|
|
attach_payload: true
|
||
|
|
--------------------------------------------------
|
||
|
|
|
||
|
|
If you configure multiple PagerDuty accounts, you either need to set a default
|
||
|
|
account or specify which account the event should be sent with in the
|
||
|
|
<<actions-pagerduty, `pagerduty`>> action.
|
||
|
|
|
||
|
|
[source,yaml]
|
||
|
|
--------------------------------------------------
|
||
|
|
xpack.notification.pagerduty:
|
||
|
|
default_account: team1
|
||
|
|
account:
|
||
|
|
team1:
|
||
|
|
...
|
||
|
|
team2:
|
||
|
|
...
|
||
|
|
--------------------------------------------------
|