](https://bonsai.sensu.io/assets/sensu/sensu-google-chat-handler)

Sensu Go Google Chat Handler

Table of Contents

• Overview
• Enterprise Plugin
• Configuration
  • Google Chat Space setup
  • Asset registration
  • Handler definition
  • Annotations
  • Usage examples
  • Help output
  • Templates
  • Example messages
• Installation from source
• Contributing

Overview

The Sensu Google Chat handler is a Sensu Event Handler that sends
event data to a configured Google Chat group/space.

Enterprise Plugin

The Sensu Google Chat Handler is an Enterprise plugin that requires a valid Sensu license to run.
Sensu Go >= 5.21 will add the SENSU_LICENSE_FILE environment variable to the handler execution.
To run the plugin independently of Sensu (ex. test/dev), you must set the env var:

SENSU_LICENSE_FILE=$(sensuctl license info --format json)

Configuration

Google Chat space setup

This link will help to setup an incoming webhook that is needed by this
plugin.

Asset registration

Sensu Assets are the best way to make use of this plugin. If you're not
using an asset, please consider doing so! If you're using sensuctl 5.13 with
Sensu Backend 5.13 or later, you can use the following command to add the asset:

sensuctl asset add sensu/sensu-google-chat-handler

If you're using an earlier version of sensuctl, you can find the asset on the
Bonsai Asset Index.

Handler definition

type: Handler
api_version: core/v2
metadata:
  name: google-chat
  namespace: default
spec:
  command: sensu-google-chat-handler
  type: pipe
  filters:
    - is_incident
    - not_silenced
  runtime_assets:
    - sensu/sensu-google-chat-handler
  secrets:
    - name: GOOGLE_CHAT_WEBHOOK_URL
      secret: google_chat_webhook_url

Security Note: The Google Chat webhook URL is treated as a security
sensitive configuration option in this example and is loaded into the handler
config as a secret instead of as a command argument.

Proxy support

This handler supports the use of the environment variables HTTP_PROXY,
HTTPS_PROXY, and NO_PROXY (or the lowercase versions thereof). HTTPS_PROXY takes
precedence over HTTP_PROXY for https requests. The environment values may be
either a complete URL or a "host[:port]", in which case the "http" scheme is
assumed.

Security Note: The Google Chat webhook URL is treated as a security
sensitive configuration option in this example .

Annotations

All arguments for this handler are tunable on a per entity or check basis based
on annotations. The annotations keyspace for this handler is
sensu.io/plugins/sensu-google-chat-handler/config.

Examples

To change the host argument for a particular check, for that checks's
metadata add the following:

type: CheckConfig
api_version: core/v2
metadata:
  annotations:
    sensu.io/plugins/sensu-google-chat-handler/config/webhook-url: "https://chat.googleapis.com/alternate-webhook/"
[...]

Usage examples

Example Sensu Handler YAML

You can use the following YAML file with sensuctl create -f google-chat-handler.yaml to register the handler:

type: Handler
api_version: core/v2
metadata:
  name: google-chat
  namespace: default
spec:
  command: sensu-google-chat-handler --message-template '{"Entity":"{{.Entity.Name}}","Check":"{{.Check.Name}}","State":"{{.Check.State}}","Occurrences":"{{.Check.Occurrences}}","Output":"{{.Check.Output}}"}' --title-template "Sensu Event - {{.Entity.Name}}/{{.Check.Name}}"
  type: pipe
  filters:
    - is_incident
    - not_silenced
  runtime_assets:
    - sensu/sensu-google-chat-handler
  secrets:
    - name: GOOGLE_CHAT_WEBHOOK_URL
      secret: google_chat_webhook_url

Instructions:

1. Save this as google-chat-handler.yaml (already provided in this repo).
2. Run:

   sensuctl create -f google-chat-handler.yaml
   

3. Make sure you have a secret named google_chat_webhook_url containing your Google Chat webhook URL.

Help output

The Sensu Go Google Chat handler for notifying a group/space

Usage:
  sensu-google-chat-handler [flags]
  sensu-google-chat-handler [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  version     Print the version number of this plugin

Flags:
  -i, --icon-url string           The URL for an icon to display in the message (default is no icon)
  -k, --thread-key string         The thread key to use when sending the message to Google Chat (default is no thread)
  -S, --section-header string     A template for the section header displayed in the Google Chat card (default is no header)
  -C, --section-collapsible       Whether the card section should be collapsible (default false)
  -U, --section-uncollapsible-widgets-count int64  Number of widgets that remain visible when the section is collapsed (default 0)
  -o, --max-output-length int     The maximum event output length to send to Google Chat - 0 for no limit (default 100)
  -m, --message-template string   The template for the message to be sent, in Golang JSON string format (default is no template, but a preformatted message)
  -s, --summary-template string   The template for the summary, in Golang text/template format (may not be reflected in Google Chat) (default "Sensu Event: {{.Entity.Name}}/{{.Check.Name}}: {{.Check.State}}")
  -t, --title-template string     The template for the title, in Golang text/template format (default "Sensu Event")
  - -w, --webhook-url string        The webhook URL to send messages to (default is the value of GOOGLE_CHAT_WEBHOOK_URL env variable)
  -h, --help                      help for sensu-google-chat-handler

Use "sensu-google-chat-handler [command] --help" for more information about a command.

Templates

This handler provides options for using templates to populate the values
provided by the event in the message, summary, and title fields in a chat
message card. The message template also provides limited support of markdown
to further embellish the message formatting.

More information on template syntax and format can be found in
[the documentation][10]

Example messages

sensu-google-chat-handler
sensu-google-chat-handler --icon-url https://www.sensu.io/img/sensu-logo.png --webhook-url YOUR_WEBHOOK_URL
sensu-google-chat-handler --title-template "Sensu Event - {{.Entity.Name}}/{{.Check.Name}}" --webhook-url YOUR_WEBHOOK_URL
sensu-google-chat-handler --message-template '{"Entity":"{{.Entity.Name}}","Check":"{{.Check.Name}}","Status":"{{.Check.State}}","Occurrences":"{{.Check.Occurrences}}"}' --webhook-url YOUR_WEBHOOK_URL
sensu-google-chat-handler --message-template '{"Entity":"{{.Entity.Name}}","Check":"{{.Check.Name}}","Status":"{{.Check.State}}","Occurrences":"{{.Check.Occurrences}}"}' --title-template "Sensu Event Details- {{.Entity.Name}}/{{.Check.Name}}" --icon-url https://www.sensu.io/img/sensu-logo.png --webhook-url YOUR_WEBHOOK_URL

All default arguments (OK event)

Notice the format of the message when not using --message-template.

sensu-google-chat-handler

Icon specification (OK event)

sensu-google-chat-handler --icon-url https://www.sensu.io/img/sensu-logo.png

Title template specification (OK event)

sensu-google-chat-handler --title-template "Sensu Event - {{.Entity.Name}}/{{.Check.Name}}"

Message template specification (OK event)

This makes use of the limited markdown support in the JSON string format.

sensu-google-chat-handler --message-template '{"Entity":"{{.Entity.Name}}","Check":"{{.Check.Name}}","State":"{{.Check.State}}","Occurrences":"{{.Check.Occurrences}}","Output":"{{.Check.Output}}"}'

This template will produce a Google Chat card with the following fields:

• Entity: The entity name
• Check: The check name
• State: The check state (e.g., passing, failing)
• Occurrences: The number of occurrences
• Output: The check output

This matches the rich card format shown in the desired example. You can add or remove fields as needed by editing the template JSON.

Thread and collapsible section example

sensu-google-chat-handler --webhook-url YOUR_WEBHOOK_URL --thread-key "sensu-events" --section-header "Sensu Event Details" --section-collapsible --section-uncollapsible-widgets-count 2 --message-template '{"Entity":"{{.Entity.Name}}","Check":"{{.Check.Name}}","State":"{{.Check.State}}","Occurrences":"{{.Check.Occurrences}}","Output":"{{.Check.Output}}"}'

This example sends the card into a Google Chat thread, renders a custom section header, and leaves the first two widgets visible when the section is collapsed.

All custom arguments (OK event)

sensu-google-chat-handler --message-template '{"Entity":"{{.Entity.Name}}","Check":"{{.Check.Name}}","State":"{{.Check.State}}","Occurrences":"{{.Check.Occurrences}}","Output":"{{.Check.Output}}"}' --title-template "Sensu Event Details- {{.Entity.Name}}/{{.Check.Name}}" --icon-url https://www.sensu.io/img/sensu-logo.png

Installation from source

Download the latest version of the sensu-google-chat-handler from
releases, or create an executable from this source.

From the local path of the sensu-google-chat-handler repository:

go build -o /usr/local/bin/sensu-google-chat-handler main.go

Contributing

For more information about contributing to this plugin, see Contributing.