Skip to content

Configuration File

IMPulse uses a single configuration file called impulse.yml. You can customize its location using the CONFIG_PATH environment variable.

The configuration can be reloaded while IMPulse is running without requiring a restart.

Required fields

Fields marked with "*" are mandatory within their parent section, but only if that parent section is present in the configuration.

Below are all the configuration options supported by IMPulse.

incident

  • description: incidents behavior options
  • type: dict

incident.notifications

  • description: incident notifications settings
  • type: dict

incident.notifications.assignment

  • description: enable/disable notifications about incident assignment changes
  • type: bool
  • default value: True

incident.notifications.new_firing

  • description: notification about new firing instances
  • type: bool
  • default value: True

incident.notifications.partial_resolved

  • description: nofitication about some resolved instances
  • type: bool
  • default value: False

incident.timeouts

  • description: incident status timeouts (see lifecycle)
  • type: dict

incident.timeouts.firing

  • description: after this time, incident status changes from 'firing' to 'unknown' if no alerts appear
  • type: string
  • default value: 6h
  • allowed values: same time format as wait in messenger chains

incident.timeouts.unknown

  • description: after this time, incident status changes from 'unknown' to 'closed' if no alerts appear
  • type: string
  • default value: 6h
  • allowed values: same time format as wait in messenger chains

incident.timeouts.resolved

  • description: after this time, incident status changes from 'resolved' to 'closed' if no alerts appear
  • type: string
  • default value: 12h
  • allowed values: same time format as wait in messenger chains

incident.timeouts.closed

  • description: after this time, 'closed' incident will be deleted
  • type: string
  • default value: 90d
  • allowed values: same time format as wait in messenger chains

messenger *

  • description: messenger configuration
  • type: dict

messenger.address * (Mattermost)

  • description: your messenger server address
  • type: string

messenger.admin_users *

  • description: IMPulse administrators (from messenger.users) notified of any warnings
  • type: list

messenger.channels *

  • description: define channels by their ID to use them in the route section. Use your messenger's UI to find the channel IDs.
  • type: dict

Example

messenger:
  channels:
    incidents_default: {id: C09NSUL269T}

messenger:
  channels:
    incidents_default: {id: w8gvebq58fgo9civ8begs6renw}

messenger:
  channels:
    incidents_default: {id: -1003748296152}

messenger.chains

  • description: escallation chains
  • type: dict

Chains specify notification sequences for incident escalation. They are referenced in the route section to determine who gets notified and in what order.

Each chain contains a list of steps. There are 5 step types. 3 of them are notifications:

The fourth step type is wait, which delays the execution of the next notification. Its format is similar to the sleep utility format, but it does not support floats or combined expressions like 1m 3s. Valid units: s (seconds), m (minutes), h (hours), d (days).

The fifth step type is chain, which allows you to include nested chains within a parent chain.

There are 3 types of chain:

  • simple
  • schedule
  • cloud

<simple chain>

  • description: a basic escalation chain. It starts executing when an incident is created.
  • type: list

Example: 

# Defined two simple chains for DevOps team
messenger:
  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>

  • description: a chain that allows you to define notification logic based on a calendar schedule.
  • type: dict

It is recommended to use steps without matcher at the end to handle unmatched datetimes.

Examples: 

messenger:
  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
          steps:
            - user: Dmitry
        - matcher:
            start_day_expr: dow
            start_day_values: ["Wed", "Thu"]
            start_time: "09:00" # 24h format
            duration: 24h
          steps:
            - user: Alexander
        - steps: # will work at Sunday
            - user: Administrator

You can also use modulus expressions for dow and dom:

- matcher:
    start_day_expr: dow % 2
    start_day_values: [0] # matches when Tue, Thu, Sat

messenger:
  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
messenger.chains[].type *
  • description: set chain type using type: schedule
  • type: string
messenger.chains[].timezone
  • description: time zone in "TZ identifier" format (details here)
  • type: string
  • default value: UTC
messenger.chains[].schedule
  • description: list of matchers with corresponding steps. IMPulse evaluates matchers from top to bottom. If a matcher matches the current time, the corresponding steps defined for that matcher are selected.
  • type: list

Examples: 

messenger:
  chains:
    support:
      type: schedule
      timezone: Asia/Tashkent
      schedule:
        - matcher:
            start_day_expr: dow
            start_day_values: ["Mon", "Tue"]
            start_time: "09:00"
            duration: 24h
          steps:
            - user: Dmitry
        - steps:
            - user: Administrator

matcher

  • description: datetime matcher which will be compared with current datetime
  • type: dict

Matcher contains theese fields:

start_day_expr *

  • description: date matching strategy: "dow" (day of week), "dom" (day of month), "date" (exact date). Expressions like "dow % 2" (least positive remainder) are also allowed.
  • type: string

start_day_values *

  • description: values for the expression start_day_expr
  • type: list

Available values:

  • for dow: 0 to 7 (like in cron) or "Sun", "Mon"...
  • for dom: 1 to 31
  • for date: "2024-12-24" format

start_time

  • description: local time in "HH:MM" format (24-hour)
  • type: string

duration

  • description: duration of the active window, e.g., "12h" or "2d"
  • type: string

steps

  • description: list of chain steps (same as in simple chain). It is recommended to use steps without matcher at the end to handle unmatched datetimes.
  • type: list

<cloud chain>

  • description: a chain that allows you to define dynamic chains using calendar providers (e.g., Google). Setup instruction here.
  • type: dict

Special ENVs (see details):

  • CHAIN_PROVIDER_DAYS_TO_SYNC
  • CHAIN_PROVIDER_MAX_EVENTS
  • CHAIN_PROVIDER_SYNC_INTERVAL_SECONDS
  • GOOGLE_SERVICE_ACCOUNT_FILE
messenger.chains[].type *
  • description: chain type
  • type: string
  • allowed values:
    • cloud only
messenger.chains[].provider *
  • description: cloud calendar provider
  • type: string
  • allowed values:
    • google only
messenger.chains[].calendar_id *
  • description: calendar ID. Get it on calendar settings page
  • type: string
messenger.chains[].default_steps
  • description: chain steps if there are no calendar events at the moment
  • type: list

To use cloud chains you should generate service account file key.json (see instructions for google provider) and add service account to your calendar.

Create "Event" in calendar. Put chain steps in "Description" using format:

- user: Dmitry
- wait: 10m
- user: Maria

Example

With event in calendar

name: Test event
from: 2024-12-24 15:00 (Asia/Tashkent)
to: 2024-12-25 15:00 (Asia/Tashkent)
description:
  - user: Valery

and config

messenger:
  chains:
    devops:
      type: cloud
      provider: google
      calendar_id: b7ec15a9f4cb22d45819b7d3e96424a03e51987461adbc22385f964cf7103a62@group.calendar.google.com
      default_steps:
        - user: Dmitry
        - wait: 5m
        - user: Maria

Under the hood, the following schedule chain will be generated:

messenger:
  chains:
    devops:
      type: schedule
      timezone: Asia/Tashkent
      schedule:
        - {matcher: {start_day_expr: date, start_day_values: ["2024-12-24"], start_time: "15:00", duration: 24h}, steps: [{user: Valery}]}
        - {steps: [{user: Dmitry}, {wait: 5m}, {user: Maria}]}

<nested chain>

  • description: allows one chain to include other chains as nested steps
  • type: string

Additionally, the chain step can be used with all types of chains. This allows one chain to include other nested chains. In some cases, this approach simplifies and reduces the overall configuration. Nesting is supported to any depth.

Example

messenger:
  chains:
    devops:
      - user: Dmitry
      - wait: 5m
      - user: Dmitry_s_boss
    programmers:
      - user: Valery
      - wait: 5m
      - chain: devops

messenger.impulse_address * (Mattermost, Telegram)

  • description: IMPulse address for button callbacks. Telegram supported only HTTPS.
  • type: string

messenger.users *

  • description: users declaration. Defines users used in chains for direct notifications.
  • type: dict

See instructions for getting user id for Slack (here), Mattermost (here), Telegram (here).

Example

messenger:
  users:
    Dmitry: {id: U73MD1YLR4M}

messenger:
  users:
    Dmitry: {id: ic8pft3ac7rjrd9eopxp4kc7qy}

messenger:
  users:
    Dmitry: {id: 482913726}

messenger.user_groups

  • description: groups of users for bulk notification. Used in chains.
  • type: list

Example

messenger:
  user_groups:
    developers: {users: ["Dmitry", "Alexander"]}

messenger.team * (Mattermost)

  • description: team name
  • type: string

messenger.template_files

  • description: path to custom template files for status_icons, header, and body (see Incident Structure)
  • type: dict

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. You can copy the default templates, modify them, and specify custom paths.

Template files supported special variables: incident (used here) and payload.

Example

messenger:
  template_files:
    status_icons: ./templates/status_icons.yml
    header: ./templates/header.yml
    body: ./templates/body.yml

messenger.template_files.body

  • description: path to the custom template file that defines the format of body
  • type: string
  • default value: ./templates/<messenger.type>_body.j2

messenger.template_files.header

  • description: path to the custom template file that defines the format of header
  • type: string
  • default value: ./templates/<messenger.type>_header.j2

messenger.template_files.status_icons

  • description: path to the custom template file that defines the format of status_icons
  • type: string
  • default value: ./templates/<messenger.type>_status_icons.j2

messenger.type *

  • description: messenger type
  • type: string
  • allowed values:
    • slack - Slack messenger
    • mattermost - Mattermost messenger
    • telegram - Telegram messenger
    • none - disable messenger integration

route *

  • description: incident routing rules based on alert fields. See details
  • type: dict

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 use Python regular expressions instead of Alertmanager's syntax.

Example: 

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

route.channel *

  • description: default channel where incidents will be created if they don't match any matchers
  • type: string

route.chain

  • description: default chain to notify users if alert don't match any matchers inside route.routes
  • type: string

route.routes

  • description: list of routing rules based on matchers to determine which channel and chain to use for incidents
  • type: list

route.routes[].matchers

  • description: conditions to match alert fields using Python regex patterns
  • type: list

route.routes[].channel

  • description: channel where incidents will be created if they match the matchers
  • type: string

route.routes[].chain

  • description: chain to notify users if incidents match the matchers
  • type: string

route.routes[].routes

  • description: nested routing rules for more detailed incident classification (recursive structure)
  • type: list

task_management

  • description: task tracking system integration configuration (e.g., Jira) (see details). The task_management: block enables Task button.
  • type: dict

task_management.type *

  • description: task tracking system type
  • type: string
  • options:
    • jira - Jira integration

task_management.project_key *

  • description: project key in the task tracking system where tasks will be created
  • type: string

Example 

task_management:
  type: jira
  project_key: PROJ

task_management.template_files

  • description: path to custom template files for task creation
  • type: dict

IMPulse uses Jinja templates to format task summary and description. You can customize these templates to match your requirements.

Template files support special variables: incident.

If template_files is not specified, IMPulse will use default template files

Example:

# Custom templates for both summary and description
task_management:
  type: jira
  project_key: PROJ
  template_files:
    summary: templates/jira_custom_summary.j2
    description: templates/jira_custom_description.j2

task_management.template_files.summary

  • description: path to the custom template file that defines the format of task summary
  • type: string
  • default value: ./templates/<task_management.type>_summary.j2

task_management.template_files.description

  • description: path to the custom template file that defines the format of task description
  • type: string
  • default value: ./templates/<task_management.type>_description.j2

ui

  • description: user interface configuration (see details). The ui: block enables the web interface
  • type: dict

Example:

ui:
  columns:
    - name: status
      header: Status
      value: incident.status
    - name: created
      type: datetime
      header: Created
      value: incident.created
    - name: alertname
      header: Alertname
      type: link
      url: incident.link
      value: payload.commonLabels.alertname
    - name: severity
      header: Severity
      value: payload.commonLabels.severity
    - name: summary
      header: Summary
      value: payload.commonAnnotations.summary
  colors:
    severity:
      critical: "#FF0000"
      warning: "#FFA500"
      info: "#00FF00"
  filters:
    - severity="critical"
  sorting:
    - severity: desc
      order: ["info", "warning", "critical"]
    - created: desc

ui.colors

  • description: allows you to color the border of a specific cell in a column based on its value.
  • type: dict

Example 

ui:
  colors:
    severity: # column name
      critical: "#FF0000" # set red border for column severity="critical"
      warning: "#FFA500" # set orange border for column severity="warning"
      info: "#00FFFF" # set cyan border for column severity="info"
    team: # column name
      devops: "#00FFFF" # set cyan border for column team="info"

ui.columns *

  • description: defines the columns that are used in the user interface
  • type: list

ui.columns[].name *

  • description: unique identifier for the column, used for filtering and sorting
  • type: string

ui.columns[].header *

  • description: display name shown in the column header
  • type: string

ui.columns[].value *

  • description: data source variable (e.g., incident.status, payload.commonLabels.alertname)
  • type: string

Supported special variables: incident and payload.

ui.columns[].type

  • description: column data type that determines how the value is rendered
  • type: string
  • default value: string
  • allowed values:
    • string - plain text
    • datetime - date/time values with formatting options
    • link - clickable links (requires url field)

ui.columns[].visible

  • description: whether the column is visible by default in the UI. Invisible columns can be used in search fields.
  • type: boolean
  • default value: True

ui.columns[].url

  • description: variable containing the required link (e.g., incident.link) (used with type: link)
  • type: string

Supported special variables: env and incident.

ui.columns[].format

  • description: formatting option for datetime columns (used with type: datetime)
  • type: string
  • default value: relative
  • allowed values:
    • absolute - full date and time
    • relative - relative time (e.g., "2h ago")

Example:

ui:
  columns:
    - name: status
      header: Status
      type: string
      value: incident.status
      visible: True
    - name: created
      type: datetime
      header: Created
      value: incident.created
    - name: alertname
      header: Alertname
      url: incident.link
      value: payload.commonLabels.alertname
    - name: severity
      header: Severity
      value: payload.commonLabels.severity
    - name: summary
      header: Summary
      value: payload.commonAnnotations.summary

ui.filters

  • description: defines the default filters applied in the user interface
  • type: list

Example

ui:
  filters:
    - severity=~"warning|critical"

ui.sorting

  • description: the default column sorting order
  • type: list

Sorting contains a list of column names and their sorting methods. There are three sorting methods: asc, desc, and none:

  • asc sorts values in alphabetical order
  • desc sorts in reverse alphabetical order
  • none disables sorting by default and used to define a custom order

Custom sorting is defined using the order field, which specifies the exact sequence in which rows should appear when asc is selected. If you want to disable sorting by default but use a custom order for some columns, use the none method.

Example:

ui:
  sorting:
    - created: desc
    - severity: none
      order: ["info", "warning", "critical"]

webhooks

  • description: webhooks provide alternative notification options via HTTP POST requests to custom endpoints
  • type: dict

see INTEGRATIONS / External menu for provider examples

webhooks[].auth

  • description: string for HTTP Basic Auth (e.g., user:password)
  • type: string

Supported special variables: env.

webhooks[].data

  • description: data to be sent in the POST request body
  • limitations: cannot be used together with webhooks[].json
  • type: dict

Supported special variables: env and incident.

Example: 

webhooks:
  dmitry_call:
    url: 'http://internal_system:8080'
    data:
      channel_id: '{{ incident["channel_id"] }}'

  complex_jinja_example:
    url: http://internal_system:8081/
    data:
      instances: '{{ incident.payload.alerts | map(attribute="labels.instance") | unique | join(", ") }}'

webhooks[].json

  • description: JSON data to be sent in the POST request body
  • limitations: cannot be used together with webhooks[].data
  • type: dict or str

Supported special variables: env and incident.

Examples:

# Send alert payload
webhooks:
  send_payload:
    url: 'http://another_host:5003/'
    json: '{{ incident["payload"] }}'

# Create custom JSON
webhooks:
  generate_json:
    url: 'http://another_host:5003/'
    json:
      channel:
        id: '{{ incident["channel_id"] }}'
      status: '{{ incident["status"] }}'

webhooks[].url *

  • description: URL to which the HTTP POST request will be sent
  • type: string

Supported special variables: env.