Slack Plugin¶

The Slack plugin offers an interface to interact with Sentinela through Slack. It allows users to receive notifications from Sentinela in a Slack channel while also providing useful commands from notification buttons or Slack messages mentioning the Sentinela bot.

sentinela example

Enabling¶

To enable the Slack plugin, add slack to the plugins list in the configuration file.

Create the Slack app¶

First create a Slack app in your workspace. The provided app manifest template has the basic configuration and permissions needed for the Sentinela Slack app.

Environment variables¶

The following environment variables are used by the Slack plugin: - SLACK_TOKEN: The token used to send messages to Slack. This token is generated when you create your Slack app and install it in your workspace. Example: xoxb-1234567890-1234567890123-12345678901234567890abcdef. - SLACK_WEBSOCKET_ENABLED: A flag to enable or disable the websocket connection for receiving events from Slack. Set this to true to enable the websocket or false to disable it. Defaults to false. - SLACK_APP_TOKEN: The token used to start the websocket connection for receiving events from interactions with the Sentinela Slack app. This token is generated when you create your Slack app and enable the Socket Mode. Example: xapp-1234567890-1234567890123-12345678901234567890abcdef. - SLACK_MAIN_CHANNEL: The Slack channel where notifications for internal monitors and example monitors will be sent. If using the provided docker compose implementations, these variables must be configured accordingly. They are located at the docker/ directory. Example: C0011223344. - SLACK_MAIN_MENTION: The Slack user or group to mention in notifications for internal monitors and example monitors. If using the provided docker compose implementations, these variables must be configured accordingly. They are located at the docker/ directory. Example: U0011223344.

Command settings¶

The Slack commands can be configured in the plugins_configs key of the configs.yaml file. This settings are configured per command, allowing commands to be disabled.

plugins_configs:
  slack:
    commands:
      monitor_disable:
        enabled: true
      monitor_enable:
        enabled: true
      monitor_refresh:
        enabled: true
      alert_acknowledge:
        enabled: true
      alert_lock:
        enabled: true
      alert_solve:
        enabled: true
      issue_drop:
        enabled: true
      monitor_documentation:
        enabled: true
      resend_notifications:
        enabled: true

Parameters: - enabled: Boolean. Flag to enable the command. When set to false, the message will be answered with a message indicating that the command is disabled. Defaults to true.

When a command is not configured, it will be considered as enabled.

Slack commands¶

Sentinela provides two main ways to interact through Slack: 1. Buttons in notifications sent to a Slack channel. 2. Messages mentioning the Sentinela Slack app directly.

Buttons in notifications¶

Slack notifications can include buttons to interact with the notifications, depending on it's priority and status. Buttons are shown only for active notifications.

Possible buttons: - Ack: Acknowledge the alert. Visible if the alert has not yet been acknowledged at the priority level. - Lock: Lock the alert. Visible if the alert is not already locked. - Solve: Solves the alert. Visible only if the monitor’s issue settings is set as not solvable. - Docs: Sends the monitor documentation as a thread reply. Visible if the monitor has documentation.

Slack message with buttons

Messages mentioning Sentinela¶

As a Slack app, Sentinela can also respond to direct commands sent in a message. To interact this way, mention the Sentinela app, followed by the desired action.

Available commands: - disable monitor {monitor_name}: Disable the specified monitor. - enable monitor {monitor_name}: Enable the specified monitor. - refresh {monitor_name} [task]: Refresh the monitor. Without task, both search and update will be executed. With task, only search or update is executed. - ack {alert_id}: Acknowledge the specified alert. - lock {alert_id}: Lock the specified alert. - solve {alert_id}: Solve the specified alert. - drop issue {issue_id}: Drop the specified issue. - docs {monitor_name}: Send the monitor's documentation as a thread reply. - resend notifications: Delete and resend all active notifications for the current channel. Sometimes a Slack channel can have a lot of messages and a notification might get lost in the past. This command will resend the notification message so it'll be among the latest messages.

Examples: - @Sentinela disable monitor some_monitor - @Sentinela enable monitor some_monitor - @Sentinela refresh some_monitor - @Sentinela refresh some_monitor search - @Sentinela refresh some_monitor update - @Sentinela ack 1234 - @Sentinela lock 2345 - @Sentinela solve 3456 - @Sentinela drop issue 1212 - @Sentinela docs some_monitor - @Sentinela resend notifications

Warning

Ensure the message is using the correct @ mention for the Sentinela Slack app in your workspace.

Actions¶

Slack plugin implements a single action to handle the resend notification command.

Notifications¶

from plugins.slack.notifications import SlackNotification

The SlackNotification class manages sending notifications for alerts to a specified Slack channel. SlackNotification objects with a different combination of channel, title, min_priority_to_send, mention, and min_priority_to_mention are considered different notification targets.

class SlackNotification:
    channel: str
    title: str
    issues_fields: list[str]
    min_priority_to_send: AlertPriority = AlertPriority.low
    mention: str | None = None
    mention_on_update: bool = False
    min_priority_to_mention: AlertPriority = AlertPriority.moderate
    issue_show_limit: int = 10

Parameters: - channel: The Slack channel where notifications will be sent. - title: A title for the notification to help users to identify the problem. - issues_fields: A list of fields from the issue data to include in the notification. - min_priority_to_send: Minimum alert priority that triggers a notification. Notifications will be sent if the alert is not acknowledged at the current priority level and it's is greater than or equal to this setting. Defaults to low (P4). - mention: Slack user or group to mention if the alert reaches a specified priority. Provide the Slack identifier for a user (e.g., U0011223344) or a group (e.g., G0011223344). Set to None to avoid mentioning anyone. Defaults to None. - min_priority_to_mention: Minimum alert priority that triggers a mention. Mentions will occur if the alert is not acknowledged at the current priority level and it's is greater than or equal to this setting. Defaults to moderate (P3). - mention_on_update: If set to 'False', the mention will be sent when the alert becomes unacknowledged and the priority is greater than or equal to the minimum priority to mention. If the alert is updated and the alert continues to be unacknowledged, the mention will persist. When set to 'True', the mention will be deleted and sent again every time alert is updated, if the alert is not acknowledged and the priority is greater than or equal to the minimum priority to mention. This option can be used as a renotification. Defaults to False. - issue_show_limit: Maximum number of issues to show in the notification. If the limit is reached, the message XXX more... will be shown at the and of the issues list, where XXX is the number of issues not being shown. Defaults to 10.

The Slack message will show the alert and its issues information. The notification will persist and will be updated until the alert is detected as solved, even if its priority falls to P5.

The notification also includes buttons to interact with the alert, allowing it to be acknowledged, locked or marked as solved. The last is only included if the issues setting was set as not solvable.

notification_options = [
    SlackNotification(
        channel="C0011223344",
        title="Alert name",
        issues_fields=["id", "name"],
        mention="U0011223344",
    )
]

Using Slack notification for internal monitors¶

To use the Slack notification for internal monitors, the settings for the internal_monitors_notification key in the configs.yaml file must be configured as follows: - notification_class: Should be set to plugin.slack.notifications.SlackNotification - params: Should include the desired parameters for the notification. - channel and mention will be obtained from the environment variables SLACK_MAIN_CHANNEL and SLACK_MAIN_MENTION, respectively, as specified in Environment variables. - title and issues_fields are specific to each monitor and are already defined in the internal monitors. If configured in the params field, they will be ignored. - min_priority_to_send, min_priority_to_mention, mention_on_update, and issue_show_limit can be set in the params field to customize the notification behavior. If not set, the default values will be used.

The provided settings will be applied to every internal and example monitors.

Services¶

The Slack plugin includes a service that connects to the Slack websocket API to receive mentions and button press events. Any event received will queue an action to be processed by Sentinela.