Microsoft Teams event handler

Microsoft Teams is a widely used “digital workspace” that facilitates communication among team members. To configure Kapacitor to send alerts to one or more Microsoft Teams channels, do the following:

Set up Teams

  1. Log in to Teams, and then create a new incoming webhook for a Teams channel.
  2. In your kapacitor.conf file, add a [teams] section with configuration options for the Microsoft Teams event handler, including the incoming webhook URL as the channelurl. For example:
[teams]
  enabled = true
  default = true
  channel-url =  "https://outlook.office.com/webhook/..."
  global = true
  state-changes-only = true
  1. To add multiple Microsoft Teams clients, repeat steps 1-2 to obtain a new web hook and add another [teams] section in kapacitor.conf. The channelurl acts as a unique identifier for each configured Teams client.

Configuration

enabled

Set to true to enable the Microsoft Teams event handler.

default

If there are multiple teams configurations, identify one as the default.

channelurl

Specify the Microsoft Team webhook URL to send messages and alerts.

global

Set to true to send all alerts to Teams without explicitly specifying Microsoft Teams in the TICKscript.

state-changes-only

Set to true to send alerts for state-changes-only. Only applies if global is true.

Handler file options

The following options can be set in a Microsoft Teams event handler file or when using .teams() in a TICKscript.

Name Type Description
team string Specifies which Team configuration to use when there are multiple configurations.
channel string Teams channel to post messages to. If empty uses the channel from the configuration.

Example handler file

id: handler-id
topic: topic-name
kind: teams
options:
  team: 'teams.microsoft.com/team/'
  channel: '#alerts'

For information about using handler files, see Add and use event handlers.

Example alerts

Send alert to Teams channel in configuration file

  stream
    |alert()
       .teams()

Send alert to Teams channel with webhook (overrides configuration file)

  stream
    |alert()
       .teams()
       .channelURL('https://outlook.office.com/webhook/...')

Send alerts to Teams from a TICKscript

Use the .teams() attribute in your TICKscripts to:

  • Send alerts to Teams
  • Define a Teams handler that subscribes to a topic and sends published alerts to Teams

To avoid posting a message every alert interval, use AlertNode.StateChangesOnly so only events where the alert changed state are sent to Teams.

The following TICKscript uses the .teams() event handler to send the message, “Hey, check your CPU”, to the #alerts Teams channel when idle CPU usage drops below 20%.

teams-cpu-alert.tick

stream
  |from()
    .measurement('cpu')
  |alert()
    .warn(lambda: "usage_idle" < 20)
    .stateChangesOnly()
    .message('Hey, check your CPU')
    .teams()

Send alerts to Teams from a defined handler

The following example sends an alert to the cpu topic with the message, “Hey, check your CPU”. A Teams handler is added that subscribes to the cpu topic and publishes all alert messages to Teams.

Create a TICKscript that publishes alert messages to a topic. The TICKscript below sends an critical alert message to the cpu topic any time idle CPU usage drops below 5%.

cpu_alert.tick

stream
  |from()
    .measurement('cpu')
  |alert()
    .crit(lambda: "usage_idle" < 5)
    .stateChangesOnly()
    .message('Hey, check your CPU')
    .topic('cpu')

Add and enable the TICKscript:

kapacitor define cpu_alert -tick cpu_alert.tick
kapacitor enable cpu_alert

Create a handler file that subscribes to the cpu topic and uses the Teams event handler to send alerts to Teams. This handler uses a non-default Teams handler, “critical-alerts”, which sends messages to the #critical-alerts channel in Teams.

teams_cpu_handler.yaml

id: teams-cpu-alert
topic: cpu
kind: teams
channelurl: 'alerts'

Add the handler:

kapacitor define-topic-handler teams_cpu_handler.yaml

This documentation is open source. See a typo? Please, open an issue.


Need help getting up and running? Get Support