honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Watcher Docs: Reworked HipChat and Slack action docs. Closes elastic/elasticsearch#511, elastic/elasticsearch#570. 

Original commit: elastic/x-pack-elasticsearch@1317e8a435
This commit is contained in:
debadair 2015-09-03 14:07:07 -07:00
parent ef4eb981b1
commit a9f93a92aa
14 changed files with 479 additions and 271 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
watcher/docs/administering-watcher.asciidoc
View File

@ -6,16 +6,20 @@ Watcher APIs, get information about Watcher, and monitor watch execution.
include::administering-watcher/configuring-email.asciidoc[]
include::administering-watcher/configuring-hipchat.asciidoc[]
include::administering-watcher/configuring-slack.asciidoc[]
include::administering-watcher/integrating-with-shield.asciidoc[]
include::administering-watcher/integrating-with-logstash.asciidoc[]
include::administering-watcher/configuring-default-throttle-period.asciidoc[]
include::administering-watcher/configuring-default-http-timeouts.asciidoc[]
include::administering-watcher/configuring-default-internal-ops-timeouts.asciidoc[]
include::administering-watcher/integrating-with-shield.asciidoc[]
include::administering-watcher/integrating-with-logstash.asciidoc[]
include::administering-watcher/getting-watcher-statistics.asciidoc[]
include::administering-watcher/monitoring-watch-execution.asciidoc[]

232
watcher/docs/administering-watcher/configuring-hipchat.asciidoc Normal file
View File

@ -0,0 +1,232 @@
[[configuring-hipchat]]
=== Configuring Watcher to Send Messages to HipChat
You can configure Watcher to use the HipChat APIs to send messages to HipChat rooms and users.
Watcher supports both the HipChat v2 and v1 APIs.
[[hipchat-account]]
==== Configuring HipChat Accounts
You configure the accounts Watcher can use to communicate with HipChat in your `elasticsearch.yml`
configuration file. Each account configuration has a unique name and specifies a HipChat API profile
and the authentication information needed to access the APIs. You can also specify message defaults,
such the default message text and color.
Watcher provides three HipChat API profiles:
<<hipchat-api-integration,integration>> :: Sends messages to a specific room using HipChat's
v2 API https://www.hipchat.com/docs/apiv2/method/send_room_notification[Send room notification].
<<hipchat-api-user, user>> :: Sends messages as a particular user through the HipChat v2 API.
Enables you to send messages to arbitrary rooms or users.
<<hipchat-api-v1, v1>> :: Sends messages to rooms using HipChat's v1 API
https://www.hipchat.com/docs/api/method/rooms/message[rooms/message].
NOTE: The `v1` profile is provided because it is simple to set up and the HipChat v1 API is familiar
to many users. However, HipChat has deprecated the v1 API and is encouraging users to migrate to
v2. Both the `integration` and `user` profiles are based on the HipChat v2 API.
If you configure multiple HipChat accounts, you either need to configure a default HipChat account
or specify which account the notification should be sent with in the <<actions-hipchat, hipchat>>
action. You set `default_account` in `watcher.actions.hipchat.service` to specify a default account.
To configure HipChat accounts, set the `watcher.actions.hipchat.service` property in
`elasticsearch.yml`. For example:
[source,yaml]
--------------------------------------------------
watcher.actions.hipchat.service:
default_account: hipchat-account1
account:
hipchat-account1:
profile: v1
auth_token: 3eLB803Nyp7UBmegJwP1rMdUmzk5HqnzJCgflrhv
message_defaults:
color: purple
format: text
hipchat-account2:
profile: integration
auth_token: 3eLB803Nyp7UBmegJwP1rMdUmzk5HqnzJCgflrhv
room: mission-control
message_defaults:
color: gray
format: text
--------------------------------------------------
See the following sections information about using each profile type.
[[hipchat-api-integration]]
===== Using the HipChat Integration Profile
You can use the `integration` profile to send messages to specific rooms. When you set an
account's profile to `integration`, Watcher sends the messages through HipChat's v2
https://www.hipchat.com/docs/apiv2/method/send_room_notification[Send room notification] API.
When you use the `integration` profile, you need to configure a separate HipChat account in
Watcher for each room you want to send messages--the account configuration contains a
room-specific authentication token. Alternatively, you can use the <<hipchat-api-user, `user`>>
or <<hipchat-api-v1, `v1`>> profile to send messages to multiple rooms.
NOTE: The `integration` profile only supports sending messages to rooms, it does not
support sending private messages. To notify a particular HipChat user, create an account
that uses the <<hipchat-api-user, `user`>> profile.
Before you can configure an account that uses the `integration` profile, you need to generate a
room-specific authentication token through the HipChat admin console:
. Log in to http://hipchat.com[hipchat.com] or your HipChat server as a group administrator.
. Go to *Group admin > Rooms*.
. Click the name of the room you want to send messages to.
. Click the *Tokens* link.
. Enter a name for the token in the *Label* field.
+
image::images/hipchat-generate-room-token.jpg[]
. Select the *Send Notification* scope.
. Click *Create*.
. Copy the generated token so you can paste it into your HipChat account configuration in
`elasticsearch.yml`.
+
image::images/hipchat-copy-room-token.jpg[]
To configure a HipChat account that uses the `integration` profile, you must:
. Set the `type` to `integration`.
. Set `room` to the name of the room you want to send messages to.
. Set `auth_token` to the room-specific authentication token.
For example, the following snippet configures an account called `notify-monitoring` that
sends messages to the `monitoring` room.
[source,yaml]
--------------------------------------------------
watcher.actions.hipchat.service:
account:
notify-monitoring:
profile: integration
auth_token: 3eLB803Nyp7UBmegJwP1rMdUmzk5HqnzJCgflrhv
room: monitoring
--------------------------------------------------
You can also specify defaults for the notification messages. For the complete list of attributes,
see <<hipchat-account-attributes, HipChat Account Attributes>>.
[[hipchat-api-user]]
===== Using the HipChat User Profile
You can use the `user` profile to send messages to rooms as well as individual HipChat users.
When you set an account's profile to `user`, Watcher sends messages as a particular user
through the HipChat v2 API.
Before you can configure an account that uses the `user` profile, you need to:
. Add a HipChat user for Watcher. Watcher sends messages via this HipChat user account, so
keep that in mind when setting the user name.
. Create an API token for the Watcher user:
.. Log in to HipChat as the Watcher user.
.. Go to `https://<hipchat-server>/account/api`. For example, `https://www.hipchat.com/account/api`.
.. Confirm the user password.
.. Enter a name for the token in the *Label* field.
+
image::images/hipchat-generate-user-token.jpg[]
. Select the *Send Notification* and *Send Message* scopes.
. Click *Create*.
. Copy the generated token so you can paste it into your HipChat account configuration in
`elasticsearch.yml`.
+
image::images/hipchat-copy-room-token.jpg[]
To configure a HipChat account that uses the `user` profile, you must:
. Set the `type` to `user`.
. Set `user` to the email address associated with the Watcher user.
. Set `auth_token` to the Watcher user's authentication token.
For example, the following snippet configures an account called `notify-monitoring` that
sends messages to the `monitoring` room.
[source,yaml]
--------------------------------------------------
watcher.actions.hipchat.service:
account:
notify-monitoring:
profile: user
user: watcher-user@example.com
auth_token: 3eLB803Nyp7UBmegJwP1rMdUmzk5HqnzJCgflrhv
--------------------------------------------------
You can also specify defaults for the notification messages. For the complete list of attributes,
see <<hipchat-account-attributes, HipChat Account Attributes>>.
[[hipchat-api-v1]]
===== Using the HipChat v1 Profile
You can use the `v1` profile to send messages to particular rooms.
When you set an account's profile to `v1`, Watcher sends the messages through HipChat's v1
https://www.hipchat.com/docs/api/method/rooms/message[rooms/message] API.
WARNING: The `v1` profile uses a deprecated API that is expected to be removed by HipChat in the
future.
The `v1` profile only supports sending messages to rooms, it does not
support sending private messages. To notify a particular HipChat user, create an account
that uses the <<hipchat-api-user, `user`>> profile.
Before you can configure an account that uses the `v1` profile, you need to generate a `v1` API
token:
. Log in to your HipChat server as a group admin.
. Go to `https://<hipchat-server>/admin/api`. For example, `https://hipchat.com/admin/api`.
. Confirm your admin password.
. Select the *Notification* type.
+
image::images/hipchat-generate-v1-token.jpg[]
. Enter a name for the token in the *Label* field.
. Click *Create*.
. Copy the generated token so you can paste it into your HipChat account configuration in
`elasticsearch.yml`.
+
image::images/hipchat-copy-v1-token.jpg[]
To configure a HipChat account that uses the `user` profile, you simply:
. Set the `type` to `v1`.
. Set `auth_token` to the v1 authentication token you generated.
For example, the following snippet configures an account called `notify-monitoring`:
[source,yaml]
--------------------------------------------------
watcher.actions.hipchat.service:
account:
notify-monitoring:
profile: v1
auth_token: 3eLB803Nyp7UBmegJwP1rMdUmzk5HqnzJCgflrhv
--------------------------------------------------
You can also specify defaults for the notification messages. For the complete list of attributes,
see <<hipchat-account-attributes, HipChat Account Attributes>>.
[[hipchat-account-attributes]]
==== HipChat Account Attributes
|======
| Name |Required | Default | Description
| `profile` | yes | - | The HipChat account profile to use:
`integration`, `user`, or `v1`.
| `auth_token` | yes | - | The authentiation token to use to access
the HipChat API.
| `host` | no | api.hipchat.com | The HipChat server hostname.
| `port` | no | 443 | The HipChat server port number.
| `room` | no | _ | The room you want to send messages to.
Must be specified if the `profile` is set
to `integration`. Not valid for the
`user` or `vi` profiles.
| `user ` | no | - | The HipChat user account to use to send
messages. Specified as an email
address. Must be specified if the
`profile` is set to `user`. Not valid for
the `integration` or `v1` profiles.
| `message.format` | no | `html` | The format of the message: `text` or `html`.
| `message.color` | no | `yellow` | The background color of the notification in
the room
| `message.notify` | no | `false` | Indicates whether people in the room should be
actively notified
|======

87
watcher/docs/administering-watcher/configuring-slack.asciidoc Normal file
View File

@ -0,0 +1,87 @@
[[configuring-slack]]
=== Configuring Watcher to Send Messages to Slack
You can configure Watcher to send messages to Slack channels and users.
[[slack-account]]
==== Configuring Slack Accounts
You configure the accounts Watcher can use to communicate with Slack in your `elasticsearch.yml`
configuration file. Each account configuration has a unique name and specifies an
https://api.slack.com/incoming-webhooks[Incoming Webhook
URL] for posting messages to Slack. You can also specify message defaults,
such the sender name and icon.
Before you can configure a Slack account, you need to set up 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/[
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 in Watcher, you set the `watcher.actions.slack.service` property in
`elasticsearch.yml`. You must set the `url` to your incoming webhook integration URL.
You can also specify defaults for the notification messages. For the complete list of attributes,
see <<slack-account-attributes, Slack Account Attributes>>.
For example, the following snippet configures an account called `notify-monitoring` and sets the
default sender name to `Watcher`.
[source,yaml]
--------------------------------------------------
watcher.actions.slack.service:
account:
monitoring:
url: https://hooks.slack.com/services/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
message_default:
from: Watcher
--------------------------------------------------
If you configure multiple Slack accounts, you either need to configure a default Slack account
or specify which account the notification should be sent with in the <<actions-slack, slack>>
action. You set `default_account` in `watcher.actions.slack.service` to specify a default account.
[source,yaml]
--------------------------------------------------
watcher.actions.slack.service:
default_account: team1
account:
team1:
url: https://hooks.slack.com/services/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
message_default:
from: watcher
team2:
url: https://hooks.slack.com/services/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
message_default:
from: watcher
--------------------------------------------------
[[slack-account-attributes]]
==== Slack Account Attributes
|======
| Name |Required | Description
| `url` | yes | The Incoming Webhook URL to use to post
messages to Slack.
| `message_defaults.from` | no | The sender name to display in the
Slack message. Defaults to the watch ID.
| `message_defaults.to ` | no | The default Slack channels or groups you
want to send messages to.
| `message_defaults.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_defaults.text` | no | The default message content.
| `message_defaults.attachment` | no | Default message attachments. Slack message attachments
enable you to create more richly-formatted messages.
Specified as an array as defined in the
https://api.slack.com/docs/attachments[
Slack attachments documentation].
|======

BIN
watcher/docs/images/hipchat-copy-room-token.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 16 KiB

BIN
watcher/docs/images/hipchat-copy-user-token.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 17 KiB

BIN
watcher/docs/images/hipchat-copy-v1-token.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 15 KiB

BIN
watcher/docs/images/hipchat-generate-room-token.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 112 KiB

BIN
watcher/docs/images/hipchat-generate-user-token.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 21 KiB

BIN
watcher/docs/images/hipchat-generate-v1-token.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 14 KiB

BIN
watcher/docs/images/slack-add-webhook-integration.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 32 KiB

BIN
watcher/docs/images/slack-copy-webhook-url.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 13 KiB

2
watcher/docs/reference/actions/email.asciidoc
View File

@ -47,7 +47,7 @@ The following snippet shows a basic email action definition:
| `bcc` | no | - | The email <<email-address,addresses>> of the `bcc` recipients. The `bcc` field can contain Mustache <<templates, templates>> as long as it resolves to a valid email address.
| `reply_to` | no | - | The email <<email-address,addresses>> that will be set on the message's `Reply-To` header. The `reply_to` field can contain Mustache <<templates, templates>> as long as it resolves to a valid email address.
| `subject` | no | - | The subject of the email. The subject can be static text or contain Mustache <<templates, templates>>.
| `body` | no | - | The body of the email. When this field holds a string, it will default to the text body of the email. Set as an object to specify either the text or the html body or both (using the fields bellow)
| `body` | no | - | The body of the email. When this field holds a string, it will default to the text body of the email. Set as an object to specify either the text or the html body or both (using the fields below)
| `body.text` | yes* | - | The plain text body of the email. The body can be static text or contain Mustache <<templates, templates>>.
| `body.html` | yes* | - | The html body of the email. The body can be static text or contain Mustache <<templates, templates>>. This body will be sanitized to remove dangerous content such as scripts. This behavior can be disabled by setting `watcher.actions.email.sanitize_html: false` in elasticsearch.yaml.
| `priority` | no | - | The priority of this email. Valid values are: `lowest`, `low`, `normal`, `high` and `highest`. The priority can contain a Mustache <<templates, template>> as long as it resolves to one of the valid values.

279
watcher/docs/reference/actions/hipchat.asciidoc
View File

@ -1,111 +1,76 @@
[[actions-hipchat]]
==== HipChat Action
A watch <<actions, action>> that can connect to a https://www.hipchat.com[HipChat] server and send
messages to users and rooms of a specific group.
A watch <<actions, action>> that sends messages to https://www.hipchat.com[HipChat]
rooms or users. To use the HipChat action, you need to configure at least one
HipChat account in Watcher. For information about configuring accounts, see <<configuring-hipchat,
Configuring Watcher to Send Notifications to HipChat>>.
[[configuring-hipchat-actions]]
===== Configuring HipChat Actions
You configure hipchat actions in a watch's `actions` array. Action-specific attributes are
specified using the `hipchat` keyword.
You configure HipChat actions in a watch's `actions` array. Action-specific attributes are
specified using the `hipchat` keyword. You must specify the `message` attribute for all
`hipchat` actions. If you omit the `account` attribute, the message is sent
using the default HipChat account configured in `elasticsearch.yml`.
The following snippet shows a simple hipchat action definition:
For example, the following action is configured to send messages using a HipChat account that
uses the <<hipchat-api-integration, integration>> profile. Because this type of account can
only send messages to a particular room, the only required attribute is the message itself.
[source,json]
--------------------------------------------------
"actions" : {
"notify-hipchat" : { <1>
"transform" : { ... }, <2>
"throttle_period" : "5m", <3>
"notify-hipchat" : {
"transform" : { ... },
"throttle_period" : "5m",
"hipchat" : {
"to" : {
"room" : "server-status" <4>
},
"message" : "Encountered {{ctx.payload.hits.total}} errors in the last 5 minutes (facepalm)" <5>
"account" : "integration-account", <1>
"message" : {
"body" : "Encountered {{ctx.payload.hits.total}} errors in the last 5 minutes (facepalm)", <2>
"format" : "text",
"color" : "red",
"notify" : true
}
}
}
}
--------------------------------------------------
<1> The name of a HipChat account configured in `elasticsearch.yml`.
<2> The message you want to send to HipChat.
To send messages with a HipChat account that uses the <<hipchat-api-user, user>> profile, you need
to specify what rooms and users you want to send the message to. For example, the following action
is configured to send messages to the `mission-control` and `devops` rooms
as well as the user `website-admin@example.com`. (To send to multiple users or rooms, specify an
array of strings.)
[source,json]
[source,json]
--------------------------------------------------
"actions" : {
"notify-hipchat" : {
"transform" : { ... },
"throttle_period" : "5m",
"hipchat" : {
"account" : "user-account",
"message" : {
"room" : [ "mission-control", "devops" ],
"user" : "website-admin@example.com",
"body" : "Encountered {{ctx.payload.hits.total}} errors in the last 5 minutes (facepalm)",
"format" : "text",
"color" : "red",
"notify" : true
}
}
}
}
--------------------------------------------------
<1> The id of the action
<2> An optional <<transform, transform>> to transform the payload before executing the `webhook` action
<3> An optional <<actions-ack-throttle, throttle period>> for the action (5 minutes in this example)
<4> The room where the message is sent to
<5> The content of the message.
HipChat provides an extensive set of APIs via which Watcher sends messages to users and rooms. These APIs
are exposed via different integration mechanism. Watcher refers to these as *Profiles*, each can be identified
with its own unique name: `v1`, `integration` and `user`.
Different profiles support different features and require different set of configuration (both on watcher
side and on the HipChat server side).
Before using the `hipchat` action in a watch, Watcher's internal HipChat service needs to be configured. This
Service enable the configuration of multiple HipChat accounts. An HipChat Account defines the following:
* `name` - (required) uniquely identifies the account. HipChat actions may specify the name of the account with which
the messages should be sent.
* `profile` - (required) the profile that is associated with this account, effectively defining what APIs this account uses.
* `auth_token` - (required) the authentication token that is used to execute the HipChat API in the account.
* `host` - (optional) defines the host of the HipChat server. When not defined it fall back on the default host (see bellow)
* `port` - (optional) defines the port of the HipChat server. When not defined it fall back on the default port (see bellow)
* `message_defaults` - (optional) a set of settings to define the default settings of the messages that are sent via this account
* `room` - Some account are bound to a single room (messages that are sent using their associated profiles can only be
sent to a specific room). For those account, this setting defines the room the account is bound to.
Here's an example settings for HipChat service:
[source,yaml]
--------------------------------------------------
watcher.actions.hipchat:
default_account: v1
account:
account1:
profile: v1
auth_token: XXXXXXXXX
message_default:
color: yello
message_format: text
account2:
profile: integration
auth_token: YYYYYYYYY
room: mission-control
message_default:
color: red
message_format: text
--------------------------------------------------
[[hipchat-api-v1]]
===== `v1` Account
WARNING: This account uses a deprecated API and is expected to be removed by HipChat in the future.
The `v1` API was the first API HipChat ever exposed and therefore the most commonly used one. It is also the simplest
one to set up. To create the `v1` API token, please follow the instructions listed on https://www.hipchat.com/docs/api.
NOTE: User private messages are not supported by this API. If private messages is what you are after, please
consider the <<`user`>> API instead.
Once the an API is created, add the following settings in `elasticsearch.yml` file:
The following table lists the available fields when setting up the `hipchat` action for the `v1` API:
[[hipchat-api-v1-action-attributes]]
.v1 API Action Attributes
[options="header"]
|======
| Name |Required | Default | Description
| `from` | no | the watch id | The name that will appear as the sender of the notification
| `room` | yes | - | The room/s that the notification should go to. Accepts a string value or an array of string values.
| `message` | yes | - | The content of the notification message (size is limited by HipChat to 1000 characters)
| `message_format` | no | html* | The format of the message. Possible options are: `text` or `html`
| `color` | no | yellow* | The background color of the notification in the room
| `notify` | no | false | Indicates whether people in the room should be actively notified
|======
Here is an example for how it looks like as part of the action definition:
To send messages with a HipChat account that uses the <<hipchat-api-v1, v1>> profile, you need
to specify what room or rooms you want to send the message to. For example, the following action
is configured to send messages to the `server-status` room. (To send to multiple
rooms, specify an array of strings.)
[source,json]
--------------------------------------------------
@ -116,10 +81,10 @@ Here is an example for how it looks like as part of the action definition:
"hipchat" : {
"account" : "v1-account",
"message" : {
"from" : "watcher",
"from" : "Watcher",
"room" : [ "server-status", "infra-team" ],
"message" : "Encountered {{ctx.payload.hits.total}} errors in the last 5 minutes (facepalm)",
"message_format" : "text",
"body" : "Encountered {{ctx.payload.hits.total}} errors in the last 5 minutes (facepalm)",
"format" : "text",
"color" : "red",
"notify" : true
}
@ -128,108 +93,36 @@ Here is an example for how it looks like as part of the action definition:
}
--------------------------------------------------
[[hipchat-action-attributes]]
===== HipChat Action Attributes
[[hipchat-api-integration]]
===== `integration` Accounts
This profiles uses HipChat https://www.hipchat.com/docs/apiv2/addons[Integrations]. More specifically,
it uses a built-in integration in HipChat that enables external systems to send notifications to a
specific room. To create the `integration` API token:
* For HipChat.com, please follow the "Build your own integration" https://www.hipchat.com/docs/apiv2[instructions]
* For HipChat Server, please follow the "Build your own integration" https://confluence.atlassian.com/hc/administering-hipchat-server/integrations-with-hipchat-server[instructions]
In both cases, the api token can be copied from the listed example (marked in red bellow)
image:images/hipchat-integration-example.png[]
NOTE: This API is the most limited APIs of the three as it only supports sending notifications to a single room and
does not support user private messages. If you are looking for multi-room notifications, please consider either
the <<hipchat-api-v1, `v1`>> or <<hipchat-api-user, `user`>> APIs. Only the latter supports user private
messages.
When creating an account with the `integration` profile, you must configure the `room` setting as part
of the account setting.
The following table lists the available fields when setting up the `hipchat` action an `integration` account:
The following table lists the attributes you can set for `hipchat` actions.
[[hipchat-api-integration-action-attributes]]
.v1 API Action Attributes
[options="header"]
|======
| Name |Required | Default | Description
| `message` | yes | - | The content of the notification message (size is limited by HipChat to 1000 characters)
| `message_format` | no | html* | The format of the message. Possible options are: `text` or `html`
| `color` | no | yellow* | The background color of the notification in the room
| `notify` | no | false | Indicates whether people in the room should be actively notified
| Name |Required | Default | Description
| `account` | no | Default account | The HipChat account to use to send the
message.
| `message.body ` | yes | - | The message content. Can contain up to
1000 characters.
| `message.format` | no | html | The format of the message: `text` or `html`.
| `message.color` | no | yellow | The background color of the notification in the
room: `gray`, `green`, `purple`, `red`, `yellow`.
| `message.notify` | no | false | Indicates whether people in the room should
be actively notified
| `message.from` | no | the watch ID | The name that appears as the notification sender.
Only valid for accounts that use the v1 profile.
| `message.room` | no | - | The rooms that the notification should go to.
Accepts a string value or an array of string
values. Must be specified when using the
v1 profile. At least one room or user must
be specified when using the `user` profile.
Not valid for the `integration` profile.
| `message.user` | no | - | The users that the notification should go to.
Accepts a string value or an array of string
values. At least one room or user must
be specified when using the `user` profile.
Not valid for the `integration` or `v1`
profiles.
|======
Here is an example for how it looks like as part of the action definition:
[source,json]
--------------------------------------------------
"actions" : {
"notify-hipchat" : {
"transform" : { ... },
"throttle_period" : "5m",
"hipchat" : {
"account" : "integration-account",
"message" : {
"message" : "Encountered {{ctx.payload.hits.total}} errors in the last 5 minutes (facepalm)",
"message_format" : "text",
"color" : "red",
"notify" : true
}
}
}
}
--------------------------------------------------
[[hipchat-api-user]]
===== `user` Accounts
The `user` API is arguably the most flexible API. It is also safe to use as it and is based on HipChat's `v2` API version.
To use this API you will require to add a new HipChat user. With this the user in place, all messages sent via this
account will be sent on this user behalf (make sure you name the user appropriately). After creating the user, you need
to create an API token for it. To create a user token please follow the instructions on HipChat's online documentation.
////
TODO: could not find a good link for that... we might need to show screenshots of the UI
////
While not supported by `v1` and `integration` accounts, the `user` account enables private user notification.
The following table lists the available fields when setting up the `hipchat` action for the `user` API:
[[hipchat-api-user-action-attributes]]
.v1 API Action Attributes
[options="header"]
|======
| Name |Required | Default | Description
| `message` | yes | - | The content of the notification message (size is limited by HipChat to 1000 characters)
| `message_format` | no | html* | The format of the message. Possible options are: `text` or `html`
| `color` | no | yellow* | The background color of the notification in the room
| `notify` | no | false | Indicates whether people in the room should be actively notified
|======
Here is an example for how it looks like as part of the action definition:
[source,json]
--------------------------------------------------
"actions" : {
"notify-hipchat" : {
"transform" : { ... },
"throttle_period" : "5m",
"hipchat" : {
"account" : "integration-account",
"message" : {
"room" : [ "mission-control", "devops" ],
"user" : "website-admin@example.com",
"message" : "Encountered {{ctx.payload.hits.total}} errors in the last 5 minutes (facepalm)",
"message_format" : "text",
"color" : "red",
"notify" : true
}
}
}
}
--------------------------------------------------

136
watcher/docs/reference/actions/slack.asciidoc
View File

@ -1,14 +1,15 @@
[[actions-slack]]
==== Slack Action
A watch <<actions, action>> that can connect to a https://slack.com/[Slack] server and send
messages to users and/or channels of a specific team.
A watch <<actions, action>> that sends messages to a https://slack.com/[Slack] team's channels or
users. To use the Slack action, you need to configure at least one
Slack account in Watcher. For information about configuring accounts, see <<configuring-slack,
Configuring Watcher to Send Notifications to Slack>>.
[[configuring-slack-actions]]
===== Configuring Slack Actions
You configure slack actions in a watch's `actions` array. Action-specific attributes are
You configure Slack actions in a watch's `actions` array. Action-specific attributes are
specified using the `slack` keyword.
The following snippet shows a simple slack action definition:
@ -16,74 +17,32 @@ The following snippet shows a simple slack action definition:
[source,json]
--------------------------------------------------
"actions" : {
"notify-slack" : { <1>
"transform" : { ... }, <2>
"throttle_period" : "5m", <3>
"notify-slack" : {
"transform" : { ... },
"throttle_period" : "5m",
"slack" : {
"to" : [ "#admins", "@chief-admin" ], <4>
"to" : [ "#admins", "@chief-admin" ], <1>
"message" : {
"text" : "Encountered {{ctx.payload.hits.total}} errors in the last 5 minutes (facepalm)" <5>
"text" : "Encountered {{ctx.payload.hits.total}} errors in the last 5 minutes (facepalm)" <2>
}
}
}
}
--------------------------------------------------
<1> The id of the action
<2> An optional <<transform, transform>> to transform the payload before executing the `webhook` action
<3> An optional <<actions-ack-throttle, throttle period>> for the action (5 minutes in this example)
<4> The users and/or channels where the message is sent to
<5> The content of the message.
<1> The channels and users you want to send the message to.
<2> The content of the message.
Before using the `slack` action in a watch, Watcher's internal Slack service needs to be configured. This
Service enable the configuration of multiple slack accounts. A Slack Account defines the following:
* `name` - (required) uniquely identifies the account. Slack actions may specify the name of the account with which
the messages should be sent.
* `url` - (required) the incoming webhook URL provided by slack
* `message_defaults` - (optional) a set of settings to define the default settings of the messages that are sent via this account
[[formatting-slack-messages]]
===== Using Attachments to Format Slack Messages
Here's an example settings for Slack service:
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 watch payload.
[source,yaml]
--------------------------------------------------
watcher.actions.slack.service:
default_account: team1
account:
team1:
url: https://hooks.slack.com/services/XXXXXXX/XXXXXXXX/XXXXXXXXXXXXXXXXXXXXXXX
message_default:
from: watcher
team2:
url: https://hooks.slack.com/services/YYYYYYY/YYYYYYYY/YYYYYYYYYYYYYYYYYYYYYYY
message_default:
from: watcher
--------------------------------------------------
[[configuring-slack-messages]]
===== Configuring Slack Messages
Slack provides powerful notification API that enables sending reach messages to the users and channels. The
following table describes the different attributes that can be used when configuring the messages in the action.
[[slack-message-attributes]]
.Slack Message Attributes
[options="header"]
|======
| Name |Required | Default | Description
| `from` | no | the watch id | The name that will appear as the sender of the notification
| `to` | yes | - | The channels/s and/or user/s that the notification should go to.
Channel names must start with a `#` and user names must start with `@`.
| `icon` | no | - | An icon can be associated with the message (accepts publicly available URL to the icon)
| `text` | yes | - | The main text/content of the message.
| `attachments` | no | - | Enables creating rich formatted sections in the message. The syntax for attachments
follows the syntax as defined by the slack APIs. You can read more about attachments
and their definition syntax https://api.slack.com/docs/attachments[here].
| `dynamic_attachments` | no | - | define an attachment template that enables adding attachments dynamically based
on the current payload (see bellow).
|======
Here is an example for how it looks like as part of the action definition:
The following snippet shows a standard message attachment.
[source,json]
--------------------------------------------------
@ -110,14 +69,18 @@ Here is an example for how it looks like as part of the action definition:
--------------------------------------------------
[[slack-dynamic-attachment]]
.Dynamic Attachments
As shown in the previous section, the "attachments" array in the slack message enables sending rich formatted messages
to channels and users. Each attachment has its own formatting, and multiple of those can belong to a single message.
To define an attachment template that is dynamically populated from the watch 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.
Dynamic attachments enables creating these message attachments dynamically based on the current watch payload. For example,
if the watch input executes a search with date histogram aggregation, dynamic attachments can reference the histogram
buckets in the payload and build and attachment per bucket. For example,
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
(good or danger).
. Defines an attachment template that references items in the list generated by the transform.
[source,json]
--------------------------------------------------
@ -141,7 +104,7 @@ buckets in the payload and build and attachment per bucket. For example,
"actions" : {
"notify-slack" : {
"throttle_period" : "5m",
"transform" : { <1>
"transform" : {
"script" : "return [ items : ctx.payload.hits.aggs.users_per_month.buckets.collect { [ month : it.key_as_string, count : it.doc_count, color : it.doc_count < 100 ? 'danger' : 'good' ] }]"
},
"slack" : {
@ -151,8 +114,8 @@ buckets in the payload and build and attachment per bucket. For example,
"to" : [ "#admins", "@chief-admin" ],
"text" : "System X Monitoring",
"dynamic_attachments" : {
"list_path" : "ctx.payload.items"
"attachement_template" : {
"list_path" : "ctx.payload.items" <1>
"attachment_template" : {
"title" : "{{month}}", <2>
"text" : "Users Count: {{count}}",
"color" : "{{color}}"
@ -163,7 +126,36 @@ buckets in the payload and build and attachment per bucket. For example,
}
}
--------------------------------------------------
<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.
<1> Transforms the payload to a list where each item in the list holds the month, user count for that month, and the color
representing the sentiment with that count (good or bad/danger)
<2> The parameter place holders refer to attributes in each item of the list above.
[[slack-action-attributes]]
===== Slack Action Attributes
[options="header"]
|======
| Name |Required | Description
| `from` | no | The sender name to display in the
Slack message. Overrides the incoming
webhook's configured name.
| `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.
| `icon` | no | The icon to display in the Slack messages.
Overrides the incoming webhook's configured
icon. Accepts a public URL to an image.
| `text` | yes | The message content.
| `attachments` | no | Slack message attachments. Message
attachments enable you to create more
richly-formatted messages. Specified as
as array as defined in the
https://api.slack.com/docs/attachments[Slack
attachments documentation].
| `dynamic_attachments` | no | Slack message attachments that can be
populated dynamically based on the current
watch payload. For more information, see
<<slack-dynamic-attachment, Using Attachments to
Format Slack Messages>>.
|======