378 lines
14 KiB
Plaintext
378 lines
14 KiB
Plaintext
[[actions-hipchat]]
|
|
=== HipChat Action
|
|
|
|
Use the `hipchat` action to send messages to https://www.hipchat.com[HipChat]
|
|
rooms or users. To send HipChat messages, you must <<<<configuring-hipchat,
|
|
configure at least one HipChat account>> in `elasticsearch.yml`.
|
|
|
|
[[configuring-hipchat-actions]]
|
|
==== Configuring HipChat Actions
|
|
|
|
You configure HipChat actions in a `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`.
|
|
|
|
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 specific room, the only required
|
|
attribute is the message itself:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
"actions" : {
|
|
"notify-hipchat" : {
|
|
"transform" : { ... },
|
|
"throttle_period" : "5m",
|
|
"hipchat" : {
|
|
"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,js]
|
|
--------------------------------------------------
|
|
"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
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
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,js]
|
|
--------------------------------------------------
|
|
"actions" : {
|
|
"notify-hipchat" : {
|
|
"transform" : { ... },
|
|
"throttle_period" : "5m",
|
|
"hipchat" : {
|
|
"account" : "v1-account",
|
|
"message" : {
|
|
"from" : "Watcher",
|
|
"room" : [ "server-status", "infra-team" ],
|
|
"body" : "Encountered {{ctx.payload.hits.total}} errors in the last 5 minutes (facepalm)",
|
|
"format" : "text",
|
|
"color" : "red",
|
|
"notify" : true
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
|
|
[[hipchat-action-attributes]]
|
|
==== HipChat Action Attributes
|
|
|
|
[cols=",^,,", options="header"]
|
|
|======
|
|
| Name |Required | Default | Description
|
|
|
|
| `account` | no | Default account | The HipChat account to use to send the message.
|
|
|
|
| `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`)
|
|
|
|
| `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.
|
|
|======
|
|
|
|
|
|
[[configuring-hipchat]]
|
|
==== Configuring HipChat Accounts
|
|
|
|
You configure the accounts {watcher} can use to communicate with HipChat in the
|
|
`xpack.notification.hipchat` namespace in `elasticsearch.yml`. Both
|
|
https://www.hipchat.com/docs/api[v1] and
|
|
https://www.hipchat.com/docs/apiv2[v2] HipChat APIs are supported.
|
|
|
|
{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 this API
|
|
is familiar to many users. That said, 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 set a default
|
|
HipChat account or specify which account the notification should be sent with
|
|
in the <<actions-hipchat, hipchat>> action.
|
|
|
|
[source,yaml]
|
|
--------------------------------------------------
|
|
xpack.notification.hipchat:
|
|
default_account: team1
|
|
account:
|
|
team1:
|
|
...
|
|
team2:
|
|
...
|
|
--------------------------------------------------
|
|
|
|
|
|
[[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`, the messages are sent 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 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. Use the <<hipchat-api-user, `user`>>
|
|
profile to notify a particular HipChat user.
|
|
|
|
You need a room-specific authentication token to configure an `integration`
|
|
account. To generate an authentication token:
|
|
|
|
. 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::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::hipchat-copy-room-token.jpg[]
|
|
|
|
To configure a HipChat account that uses the `integration` profile:
|
|
|
|
. 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]
|
|
--------------------------------------------------
|
|
xpack.notification.hipchat:
|
|
account:
|
|
notify-monitoring:
|
|
profile: integration
|
|
auth_token: 3eLB803Nyp7UBmegJwP1rMdUmzk5HqnzJCgflrhv
|
|
room: monitoring
|
|
--------------------------------------------------
|
|
|
|
You can also specify defaults for the <<hipchat-account-attributes,
|
|
message attributes>>:
|
|
|
|
[source,yaml]
|
|
--------------------------------------------------
|
|
xpack.notification.hipchat:
|
|
account:
|
|
notify-monitoring:
|
|
profile: integration
|
|
auth_token: 3eLB803Nyp7UBmegJwP1rMdUmzk5HqnzJCgflrhv
|
|
room: monitoring
|
|
message:
|
|
format: text
|
|
color: blue
|
|
notify: true
|
|
--------------------------------------------------
|
|
|
|
|
|
[[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 a `user` account, you need to:
|
|
|
|
. Add a HipChat user for {watcher}. When setting the user name, keep in mind that
|
|
the messages are sent on behalf of this user.
|
|
. 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::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::hipchat-copy-room-token.jpg[]
|
|
|
|
To configure a HipChat account that uses the `user` profile:
|
|
|
|
. 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 configuration creates an account called
|
|
`notify-monitoring` that sends messages to the `monitoring` room:
|
|
|
|
[source,yaml]
|
|
--------------------------------------------------
|
|
xpack.notification.hipchat:
|
|
account:
|
|
notify-monitoring:
|
|
profile: user
|
|
user: watcher-user@example.com
|
|
auth_token: 3eLB803Nyp7UBmegJwP1rMdUmzk5HqnzJCgflrhv
|
|
--------------------------------------------------
|
|
|
|
You can also specify defaults for the <<hipchat-account-attributes,
|
|
message attributes>>:
|
|
|
|
[source,yaml]
|
|
--------------------------------------------------
|
|
xpack.notification.hipchat:
|
|
account:
|
|
notify-monitoring:
|
|
profile: user
|
|
user: watcher-user@example.com
|
|
auth_token: 3eLB803Nyp7UBmegJwP1rMdUmzk5HqnzJCgflrhv
|
|
message:
|
|
format: text
|
|
color: blue
|
|
notify: true
|
|
--------------------------------------------------
|
|
|
|
|
|
[[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`, messages are sent 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. Use the <<hipchat-api-user, `user`>> profile to send
|
|
private messages to HipChat users.
|
|
|
|
Before you can configure a `v1` account, 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::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::hipchat-copy-v1-token.jpg[]
|
|
|
|
To configure a HipChat account that uses the `v1` profile:
|
|
|
|
. Set the `type` to `v1`.
|
|
. Set `auth_token` to the v1 authentication token you generated.
|
|
|
|
For example, the following configuration creates an account called
|
|
`notify-monitoring`:
|
|
|
|
[source,yaml]
|
|
--------------------------------------------------
|
|
xpack.notification.hipchat:
|
|
account:
|
|
notify-monitoring:
|
|
profile: v1
|
|
auth_token: 3eLB803Nyp7UBmegJwP1rMdUmzk5HqnzJCgflrhv
|
|
--------------------------------------------------
|
|
|
|
You can also specify defaults for the <<hipchat-account-attributes,
|
|
message attributes>>.
|
|
|
|
[source,yaml]
|
|
--------------------------------------------------
|
|
xpack.notification.hipchat:
|
|
account:
|
|
notify-monitoring:
|
|
profile: v1
|
|
auth_token: 3eLB803Nyp7UBmegJwP1rMdUmzk5HqnzJCgflrhv
|
|
message:
|
|
format: text
|
|
color: blue
|
|
notify: true
|
|
--------------------------------------------------
|