Configuration File¶
The only configuration file for IMPulse is impulse.yml
. To change default impulse.yml
path see Environment Variables
All options¶
incident - incidents behavior options
alerts_firing_notifications [
bool
, defaultFalse
] - notification about new firing instancesalerts_resolved_notifications [
bool
, defaultFalse
] - nofitication about old resolved instancestimeouts - incident status timeouts (to realize incident lifecycle)
firing [
string
, default6h
] - after this time Incident status will change from 'firing' to 'unknown' if no new alerts appearunknown [
string
, default6h
] - after this time Incident status will change from 'resolved' to 'closed' if no new alerts appearresolved [
string
, default12h
] - after this time Incident status will change from 'resolved' to 'closed' if no new alerts appear
route [dict
, required] - route for incidents routing is based on alert's fields. See details
application [dict
, required] - messenger configuration
address [
string
, mattermost only] - your Mattermost server addressadmin_users [
list
, required] - IMPulse administrators. They will be notified when any warningsimpulse_address [
string
] - define where Mattermost / Telegram will send button eventsusers [
dict
, required] - users declaration. See detailsuser_groups [
list
] - user groups declaration. See detailschannels [
dict
, required] - messenger channels used in IMPulse. See detailschains [
dict
] - entity to describe notifications order. See detailstemplate_files [
dict
] - path to custom template files. See detailstype [
string
, required] - type of messenger (mattermost
,slack
ortelegram
)
webhooks - see details to understand how to work with it
experimental [dict
] - experimental options (WE HIGHLY RECOMMEND DO NOT USE IT)
recreate_chain [
bool
, defaultFalse
] - this option will enable chain and start it again when new alerts added to incident
Details¶
chains¶
Chain defines how to notify people about incident. Chains used in route.
There are 2 types of chain: simple and schedule.
simple chain¶
Every chain has list of steps. Step can be one of 4 instructions. 3 of them is notifications: user
, user_group
, webhook
. The last one is wait
- to split notifications by time.
wait
format seems like sleep utility format, but without float support and complex expressions like 1m 3s
. Available 4 options: s
(seconds), m
(minutes), h
(hours), d
(days).
devops chains example
Defined two chains for DevOps team
application:
chains:
devops:
- user: Dmitry
- wait: 5m
- user: Dmitry_s_boss
devops-critical:
- user: Dmitry
- wait: 3m
- webhook: Dmitry_call
- wait: 5m
- user: Dmitry_s_boss
- wait: 15m
- user: CTO
schedule chain¶
Schedule chain add you ability to set chains with calendar
schedule chain options:¶
type [string
, required] - set chain type using type: schedule
timezone [string
, default UTC
] - your timezone with "TZ identifier" format (details here)
schedule [list
] - list of datetime matchers with steps. Current datetime is compared with every matcher and if any matches, theese steps will be used
matcher [
dict
] - datetime matcher which will be compared with current datetimestart_day_expr [
string
, required] - expression to select start day for datetime range.Expression can have one of three instructions:
dow - day of week. Available
start_day_values
:0
to7
(like in cron) or "Sun", "Mon"...dom - day of month [1..31]
date - exactly date with format
2024.12.24
Also you can use expression with
dom
anddow
likedom % 2
which calculates least positive remainder as value.start_day_values [
list
] - list of start day values which will matchstart_time [
string
] - local time when duty starts in start_dayduration [
string
] - time range duration (24h
maximum)steps [
list
, required] - chain steps like in simple chain
We recommend to use steps
without matcher
in the end, to handle datetimes which don't match any of matchers.
schedule chain examples
application:
chains:
support:
type: schedule
timezone: Asia/Tashkent
schedule:
- matcher:
start_day_expr: dow
start_day_values: ["Mon", "Tue"]
start_time: "09:00" # 24h format
duration: 24h # 0h..24h
steps:
- user: Dmitry
- matcher:
start_day_expr: dow
start_day_values: ["Wed", "Thu"]
start_time: "09:00" # 24h format
duration: 24h # 0h..24h
steps:
- user: Alexander
- steps: # will work at Sunday
- user: Administrator
Also you can use this format for dow
and dom
:
- matcher:
start_day_expr: dow % 2
start_day_values: [0] # matches when Tue, Thu, Sat
Defined two simple chains for DevOps team
application:
chains:
support:
type: schedule
timezone: Asia/Tashkent
schedule:
- {matcher: {start_day_expr: dow, start_day_values: [1, 2], start_time: "12:00", duration: 12h}, steps: [{user: Dmitry}]}
- {matcher: {start_day_expr: dow, start_day_values: [3, 4], start_time: "12:00", duration: 12h}, steps: [{user: Alexander}]}
- {matcher: {start_day_expr: dow, start_day_values: [5, 6], start_time: "12:00", duration: 12h}, steps: [{user: Maria}]}
- {steps: [{user: Oleg }]} # full Sunday and 00:00 to 12:00 every day
channels¶
Define channels with their ID for using in route. Use your messanger UI to get channels ID
channels examples
Define default channels (Slack)
application:
channels:
incidents_default: {id: C09NSUL269T}
Define default channel (Mattermost)
application:
channels:
incidents_default: {id: w8gvebq58fgo9civ8begs6renw}
Define default channel (Telegram)
application:
channels:
incidents_default: {id: -1003748296152}
route¶
Route configure messenger channels, where incidents will be created, and chains to notify people by rules.
It is very similar to Alertmanager's route. But has only four instructions: routes
, matchers
, channel
, chain
.
Matchers work like Alertmanager's but use Python regex instead.
route example
Complex example with comments
route:
channel: incidents_default # default channel where incidents will be created if their didn't match any matchers
chain: devops # optional, but we recommend set it to handle alerts didn't match any matchers
routes:
# Infrastructure routes
- matchers:
- service =~ "cpu|disk|memory|network" # regex selector powered by Python regex
channel: incidents-infrastructure # channel for not "critical" or "warning" severity
# no chain here means users will not be notified, just incident created
routes:
- matchers:
- severity = "critical" # simple selector
channel: incidents-infrastructure
chain: devops-critical
- matchers:
- severity = "warning"
channel: incidents-infrastructure
chain: devops
# Services routes
- matchers:
- service = "fingernote"
channel: incidents-services
chain: fingernote-team
routes:
- matchers:
- severity = "critical"
channel: incidents-services
chain: fingernote-team-critical
- matchers:
- service = "pickcase"
channel: incidents-services
chain: pickcase-team
routes:
- matchers:
- severity = "critical"
channel: incidents-services
chain: pickcase-team-critical
template_files¶
IMPulse uses jinja2 templates to set messages format. And you can modify it.
Incident message contains three parts (picture). Default template files for theese parts is here. Just copy, modify and replace default template files with yours.
Template files can contain special words incident
and payload
as variables to show additional info. incident
contains incident attributes (used here). payload
is an Alertmanager alerts payload
template_files example
application:
template_files:
status_icons: ./templates/status_icons.yml # path to custom status_icons template file
header: ./templates/header.yml # path to custom header template file
body: ./templates/body.yml # path to custom body template file
users¶
Object which define users. They used in chains as one of notification type.
To get users id
instructions for Slack (here) and Mattermost (here).
users example¶
Slack example
application:
users:
Dmitry: {id: U73MD1YLR4M}
Mattermost example
application:
users:
Dmitry: {id: ic8pft3ac7rjrd9eopxp4kc7qy}
user_groups¶
Object to notify multiple users at once. They used in chains as one of notification type.
user_groups example¶
application:
user_groups:
developers: {users: ["Dmitry", "Alexander"]}
webhooks¶
Webhooks is the only alternative notification way outside messenger. It used to send POST HTTP requests to any endpoint.
Webhooks can have special words env
and incident
as variables to use additional info:
env
to get environment variables, such as passwords and tokens. See examples below.incident
to get current incident fields
webhooks examples¶
Twilio.com calls
webhooks:
Dmitry_call:
url: 'https://api.twilio.com/2010-04-01/Accounts/{{ env["TWILIO_ACCOUNT_SID"] }}/Calls.json'
data:
To: '+998xxxxxxxxx'
From: '{{ env["TWILIO_NUMBER"] }}'
Url: http://example.com/twiml.xml
auth: '{{ env["TWILIO_ACCOUNT_SID"] }}:{{ env["TWILIO_AUTH_TOKEN"] }}'
To make this config works you should add theese custom Environment Variables
TWILIO_ACCOUNT_SID
TWILIO_AUTH_TOKEN
TWILIO_NUMBER
Zvonok.com calls
webhooks:
Dmitry_call:
url: "https://zvonok.com/manager/cabapi_external/api/v1/phones/call/"
data:
campaign_id: '{{ env["ZVONOK_CAMPAIGN_ID"] }}'
phone: '+998xxxxxxxxx'
public_key: '{{ env["ZVONOK_PUBLIC_KEY"] }}'
To make this config works you should add theese custom Environment Variables
ZVONOK_CAMPAIGN_ID
ZVONOK_PUBLIC_KEY