248 lines
8.3 KiB
Plaintext
248 lines
8.3 KiB
Plaintext
[role="xpack"]
|
|
[[actions-slack]]
|
|
=== Slack Action
|
|
|
|
Use the `slack` action to send messages to a https://slack.com/[Slack]
|
|
team's channels or users. To send Slack messages, you need to
|
|
<<configuring-slack,configure at least one Slack account>> in
|
|
`elasticsearch.yml`.
|
|
|
|
[[configuring-slack-actions]]
|
|
==== Configuring Slack actions
|
|
|
|
You configure Slack actions in the `actions` array. Action-specific attributes
|
|
are specified using the `slack` keyword.
|
|
|
|
The following snippet shows a simple slack action definition:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
"actions" : {
|
|
"notify-slack" : {
|
|
"transform" : { ... },
|
|
"throttle_period" : "5m",
|
|
"slack" : {
|
|
"message" : {
|
|
"to" : [ "#admins", "@chief-admin" ], <1>
|
|
"text" : "Encountered {{ctx.payload.hits.total.value}} errors in the last 5 minutes (facepalm)" <2>
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// NOTCONSOLE
|
|
<1> The channels and users you want to send the message to.
|
|
<2> The content of the message.
|
|
|
|
|
|
[[formatting-slack-messages]]
|
|
==== Using attachments to format Slack messages
|
|
|
|
In addition to sending simple text-based messages, you can use the Slack
|
|
https://api.slack.com/docs/attachments[attachment] mechanism to send formatted
|
|
messages. {watcher} leverages Slack attachments to enable you to dynamically
|
|
populate templated messages from the execution context payload.
|
|
|
|
The following snippet shows a standard message attachment:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
"actions" : {
|
|
"notify-slack" : {
|
|
"throttle_period" : "5m",
|
|
"slack" : {
|
|
"account" : "team1",
|
|
"message" : {
|
|
"from" : "watcher",
|
|
"to" : [ "#admins", "@chief-admin" ],
|
|
"text" : "System X Monitoring",
|
|
"attachments" : [
|
|
{
|
|
"title" : "Errors Found",
|
|
"text" : "Encountered {{ctx.payload.hits.total.value}} errors in the last 5 minutes (facepalm)",
|
|
"color" : "danger"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// NOTCONSOLE
|
|
|
|
[[slack-dynamic-attachment]]
|
|
|
|
To define an attachment template that is dynamically populated from the payload,
|
|
you specify `dynamic_attachments` in the watch action. For example, a dynamic
|
|
attachment could reference histogram buckets in the payload and build an
|
|
attachment per bucket.
|
|
|
|
In the following example, the watch input executes a search with a date histogram
|
|
aggregation and the Slack action:
|
|
|
|
. Transforms the payload to a list where each item in the list holds the month,
|
|
the user count for that month, and the color that represents the sentiment
|
|
associated with that count (danger or bad).
|
|
|
|
. Defines an attachment template that references items in the list generated by
|
|
the transform.
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
"input" : {
|
|
"search" : {
|
|
"request" : {
|
|
"body" : {
|
|
"aggs" : {
|
|
"users_per_month" : {
|
|
"date_histogram" : {
|
|
"field" : "@timestamp",
|
|
"interval" : "month"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
...
|
|
"actions" : {
|
|
"notify-slack" : {
|
|
"throttle_period" : "5m",
|
|
"transform" : {
|
|
"script" : {
|
|
"source" : "['items': ctx.payload.aggregations.users_per_month.buckets.collect(bucket -> ['count': bucket.doc_count, 'name': bucket.key_as_string, 'color': bucket.doc_count < 100 ? 'danger' : 'good'])]",
|
|
"lang" : "painless"
|
|
}
|
|
},
|
|
"slack" : {
|
|
"account" : "team1",
|
|
"message" : {
|
|
"from" : "watcher",
|
|
"to" : [ "#admins", "@chief-admin" ],
|
|
"text" : "System X Monitoring",
|
|
"dynamic_attachments" : {
|
|
"list_path" : "ctx.payload.items" <1>
|
|
"attachment_template" : {
|
|
"title" : "{{month}}", <2>
|
|
"text" : "Users Count: {{count}}",
|
|
"color" : "{{color}}"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// NOTCONSOLE
|
|
<1> The list generated by the action's transform.
|
|
<2> The parameter placeholders refer to attributes in each item of the list
|
|
generated by the transform.
|
|
|
|
[[slack-action-attributes]]
|
|
==== Slack action attributes
|
|
|
|
[cols=",^,", options="header"]
|
|
|======
|
|
| Name |Required | Description
|
|
|
|
| `message.from` | no | The sender name to display in the Slack message.
|
|
Overrides the incoming webhook's configured name.
|
|
|
|
| `message.to` | yes | The channels and users you want to send the message
|
|
to. Channel names must start with `#` and user names
|
|
must start with `@`. Accepts a string value or an
|
|
array of string values.
|
|
|
|
| `message.icon` | no | The icon to display in the Slack messages. Overrides
|
|
the incoming webhook's configured icon. Accepts a
|
|
public URL to an image.
|
|
|
|
| `message.text` | yes | The message content.
|
|
|
|
| `message.attachments` | no | Slack message attachments. Message attachments enable
|
|
you to create more richly-formatted messages. Specified
|
|
array as defined in the
|
|
https://api.slack.com/docs/attachments[Slack attachments documentation].
|
|
|
|
| `message.dynamic_attachments` | no | Slack message attachments that can be populated
|
|
dynamically based on the current watch payload. For
|
|
more information, see
|
|
<<slack-dynamic-attachment>>.
|
|
|
|
| `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`)
|
|
|======
|
|
|
|
[[configuring-slack]]
|
|
==== Configuring Slack Accounts
|
|
|
|
You configure the accounts {watcher} can use to communicate with Slack in the
|
|
`xpack.notification.slack` namespace in `elasticsearch.yml`.
|
|
|
|
You need a https://api.slack.com/incoming-webhooks[Slack webhook URL] to
|
|
configure a Slack account. To create a webhook
|
|
URL, set up an an _Incoming Webhook Integration_ through the Slack console:
|
|
|
|
. Log in to http://slack.com[slack.com] as a team administrator.
|
|
. Go to https://my.slack.com/services/new/incoming-webhook.
|
|
. Select a default channel for the integration.
|
|
+
|
|
image::images/slack-add-webhook-integration.jpg[]
|
|
. Click *Add Incoming Webhook Integration*.
|
|
. Copy the generated webhook URL so you can paste it into your Slack account
|
|
configuration in `elasticsearch.yml`.
|
|
+
|
|
image::images/slack-copy-webhook-url.jpg[]
|
|
|
|
To configure a Slack account, at a minimum you need to specify the account
|
|
name and webhook URL in the {es} keystore (see {ref}/secure-settings.html[secure settings]):
|
|
|
|
[source,shell]
|
|
--------------------------------------------------
|
|
bin/elasticsearch-keystore add xpack.notification.slack.account.monitoring.secure_url
|
|
--------------------------------------------------
|
|
|
|
[WARNING]
|
|
======
|
|
You can no longer configure Slack accounts using `elasticsearch.yml` settings.
|
|
Please use {es}'s secure <<secure-settings,keystore>> method instead.
|
|
======
|
|
|
|
You can specify defaults for the
|
|
<<slack-account-attributes,Slack notification attributes>>:
|
|
|
|
[source,yaml]
|
|
--------------------------------------------------
|
|
xpack.notification.slack:
|
|
account:
|
|
monitoring:
|
|
message_defaults:
|
|
from: x-pack
|
|
to: notifications
|
|
icon: http://example.com/images/watcher-icon.jpg
|
|
attachment:
|
|
fallback: "X-Pack Notification"
|
|
color: "#36a64f"
|
|
title: "X-Pack Notification"
|
|
title_link: "https://www.elastic.co/guide/en/x-pack/current/index.html"
|
|
text: "One of your watches generated this notification."
|
|
mrkdwn_in: "pretext, text"
|
|
--------------------------------------------------
|
|
|
|
If you configure multiple Slack accounts, you either need to configure a default
|
|
account or specify which account the notification should be sent with in the
|
|
<<actions-slack,`slack`>> action.
|
|
|
|
[source,yaml]
|
|
--------------------------------------------------
|
|
xpack.notification.slack:
|
|
default_account: team1
|
|
account:
|
|
team1:
|
|
...
|
|
team2:
|
|
...
|
|
--------------------------------------------------
|