diff --git a/docs/incidents/concepts/notifications.md b/docs/incidents/concepts/notifications.md deleted file mode 100644 index e39c7e43..00000000 --- a/docs/incidents/concepts/notifications.md +++ /dev/null @@ -1,67 +0,0 @@ -# Notifications - -Each team can have one or more notifications set up. The notification can be setup in the team spec. -Whenever a responder is attached to an incident, the responder team will receive the notifications on matching services. - -## Notification Spec - -| Field | Description | Schema | Required | -| ---------- | -------------------------------------------------------------------------------------------------------- | ------------------- | -------- | -| connection | The connection to use for the notification. | `string` | `false` | -| filter | Filter is a CEL-expression used to decide whether this notification client should send the notification. | `string` | `false` | -| template | Go template for the notification message. | `string` | `true` | -| url | URL in the form of Shoutrrr notification service URL schema. | `string` | `false` | -| properties | Configuration properties for Shoutrrr. It's Templatable. | `map[string]string` | `false` | - -**Example:** - -```yaml -components: - - name: Cyza -notifications: - - connection: connection://googlechat/incident-notifications - filter: incident.severity == 'High' || incident.severity == "Critical" - template: | - Subscribed to new incident: {{.incident.title}} - - Type: {{.incident.type}} - Severity: {{.incident.severity}} - Status: {{.incident.status}} - - - url: slack://@incident-notifications - filter: incident.severity != 'Low' - template: | - Type: {{.incident.type}} - Severity: {{.incident.severity}} - Status: {{.incident.status}} - properties: - color: '{{if eq incident.severity "Low"}}good{{else}}danger{{end}}' - title: 'Subscribed to new incident: {{.incident.title}}' -``` - -## Supported services - -We use [Shoutrrr](https://github.com/containrrr/shoutrrr/) to deliver notifications to various services. - -| Services | URL Format | -| ----------- | ---------------------------------------------------------------------------------------- | -| Bark | `bark://devicekey@host` | -| Discord | `discord://token@id ` | -| Email | `smtp://username:password@host:port/?from=fromAddress&to=recipient1[,recipient2,...]` | -| Gotify | `gotify://gotify-host/token` | -| Google Chat | `googlechat://chat.googleapis.com/v1/spaces/FOO/messages?key=bar&token=baz ` | -| IFTTT | `ifttt://key/?events=event1[,event2,...]&value1=value1&value2=value2&value3=value3 ` | -| Join | `join://shoutrrr:api-key@join/?devices=device1[,device2, ...][&icon=icon][&title=title]` | -| Mattermost | `mattermost://[username@]mattermost-host/token[/channel]` | -| Matrix | `matrix://username:password@host:port/[?rooms=!roomID1[,roomAlias2]] ` | -| Ntfy | `ntfy://username:password@ntfy.sh/topic` | -| OpsGenie | `opsgenie://host/token?responders=responder1[,responder2] ` | -| Pushbullet | `pushbullet://api-token[/device/#channel/email]` | -| Pushover | `pushover://shoutrrr:apiToken@userKey/?devices=device1[,device2, ...]` | -| Rocketchat | `rocketchat://[username@]rocketchat-host/token[/channel\| @recipient]` | -| Slack | `slack://[botname@]token-a/token-b/token-c` | -| Teams | `teams://group@tenant/altId/groupOwner?host=organization.webhook.office.com` | -| Telegram | `telegram://token@telegram?chats=@channel-1[,chat-id-1,...]` | -| Zulip Chat | `zulip://bot-mail:bot-key@zulip-domain/?stream=name-or-id&topic=name` | - -For more details please visit: [https://containrrr.dev/shoutrrr/0.7/services/overview/](https://containrrr.dev/shoutrrr/0.7/services/overview/) diff --git a/docs/notifications/concepts/events.md b/docs/notifications/concepts/events.md new file mode 100644 index 00000000..d8c2e5f0 --- /dev/null +++ b/docs/notifications/concepts/events.md @@ -0,0 +1,16 @@ +There are numerous events in Mission Control that you can subscribe to get notifications. Here is the complete list of all events: + +| Category | event | Description | +| ------------------------------------------------------------------------ | ---------------------------- | ------------------------------------------------------------------------------------------ | +| [Health Check](../events/health-checks.md) | `check.passed` | when a previously failing check passes | +| | `check.failed` | when a previously passing check fails | +| [Incident](../events/incidents.md#incidents) | `incident.created` | when an incident is created | +| [Incident Statuses](../events/incidents.md#status) | `incident.status.` | When an incident's status changes. See the [list of statuses](./incident/overview/#status) | +| [Incident Comment](../events/incidents.md#comments) | `incident.comment.added` | When a new comment is added to an incident. | +| [Incident Responder](../events/incidents.md#responders) | `incident.responder.created` | when a responder is added to an incident | +| | `incident.responder.removed` | when a responder is removed from an incident | +| [Incident Definition of Done](../events/incidents.md#definition-of-done) | `incident.dod.added` | when a dod is added | +| | `incident.dod.removed` | when an existing dod is removed | +| | `incident.dod.passed` | when a previously failing dod passes | +| | `incident.dod.regressed` | when a previously passing dod fails | +| [Component](../events/components.md) | `component.status.` | When a component's status changes | diff --git a/docs/notifications/concepts/filtering.md b/docs/notifications/concepts/filtering.md new file mode 100644 index 00000000..64c796c8 --- /dev/null +++ b/docs/notifications/concepts/filtering.md @@ -0,0 +1,19 @@ +Customizing notifications is made possible through the use of filters, which are driven by CEL expressions (Check Execution Language). You can learn more about CEL expressions on the [CEL-spec GitHub page](https://github.com/google/cel-spec). + +The cel expression receives different input variables based on the event type. To determine which variables are available, refer to the corresponding event details in the [events](../concepts/events.md) section. + +## Examples + +```yaml +# Filter HTTP checks only +events: + - check.passed +filter: check.type == 'http' +``` + +```yaml +# Filter HTTP checks those that have failed for more than 5 times in the last 1 hour +events: + - check.failed +filter: check.type == 'http' && check.uptime.failed > 5 +``` diff --git a/docs/notifications/concepts/notification.md b/docs/notifications/concepts/notification.md new file mode 100644 index 00000000..f38b0bbe --- /dev/null +++ b/docs/notifications/concepts/notification.md @@ -0,0 +1,40 @@ +Notification allows you to receive alerts on a preferred channel when a particular set of events occur. + +## Notification Spec + +| Field | Description | Scheme | Required | +| ----------------- | -------------------------------- | ------------------- | -------- | +| `events` | Events of notification. | `[]string` | `true` | +| `title` | Title of notification. | `string` | `false` | +| `template` | Template of notification. | `string` | `false` | +| `filter` | Filter of notification. | `string` | `false` | +| `person_id` | Person ID of notification. | `uuid` | `false` | +| `team_id` | Team ID of notification. | `uuid` | `false` | +| `properties` | Properties of notification. | `map[string]string` | `false` | +| `custom_services` | Custom services of notification. | `JSON` | `false` | + +!!! Note + + One of `person_id`, `team_id` or `custom_services` is required. + +## Examples: + +```yaml title="http-check-passed.yaml" +events: + - check.passed +title: Check as {{.check.status}} +template: 'Canary: {{.canary.name}} Message: {{.status.message}} ' +filter: "check.type == 'http'" +person_id: d87243c9-3183-4ab9-9df9-c77c8278df11 +``` + +```yaml title="check-failure.yaml" +events: + - check.failed +title: Check as {{.check.status}} +template: 'Canary: {{.canary.name}} Error: {{.status.error}}' +filter: "check.type == 'http'" +custom_services: + - connection: connection://slack://@health-check-notifications + name: Slack-health-checks +``` diff --git a/docs/notifications/concepts/recipients.md b/docs/notifications/concepts/recipients.md new file mode 100644 index 00000000..9ddfbd27 --- /dev/null +++ b/docs/notifications/concepts/recipients.md @@ -0,0 +1,49 @@ +There are 3 types of receivers + +1. Person +2. Team +3. Custom Services + +A notification must and can only have a single recipient. + +## 1. Person + +When a person is chosen as a recipient, the notification will be delivered via email to the person's registered email address. + +## 2. Team + +Teams have the flexibility to fine-tune their notification preferences. They can choose from various communication channels and apply filters to tailor their alerts. For instance, a team can set up a configuration to receive both email and Slack notifications for high-severity incidents, while opting for Slack exclusively for low-severity issues. + +## 3. Custom Services + +For notifications that do not neatly fit into the person or team categories, there's the option to route them to custom services. This ensures that the unique and non-standard notification scenarios are managed effectively and in a way that suits the organization's specific needs. + +## Notification Config + +To define the notification channel for team or a custom service, we use the structure below. + +| Field | Description | Schema | Required | +| ---------- | -------------------------------------------------------------------------------------------------------- | ------------------- | -------- | +| name | A unique name for the notification. | `string` | `true` | +| connection | The connection to use for the notification channel. | `string` | `false` | +| filter | Filter is a CEL-expression used to decide whether this notification client should send the notification. | `string` | `false` | +| url | URL in the form of Shoutrrr notification service URL schema. | `string` | `false` | +| properties | Configuration properties for Shoutrrr. It's Templatable. | `map[string]string` | `false` | + +!!! Note + + One of either the `connection` or the `url` is required. + +### Example: + +```yaml title="backend-team.yaml" +notifications: + - connection: connection://smtp://system/?To=aditya@flanksource.com + filter: incident.severity == 'High' || incident.severity == "Critical" + + - url: slack://@incident-notifications + filter: incident.id != "" # Dummy filter to ensure that this filter only runs for incident related notifications + properties: + color: '{{if eq incident.severity "Low"}}good{{else}}danger{{end}}' + title: 'Subscribed to new incident: {{.incident.title}}' +``` diff --git a/docs/notifications/concepts/templating.md b/docs/notifications/concepts/templating.md new file mode 100644 index 00000000..b2044366 --- /dev/null +++ b/docs/notifications/concepts/templating.md @@ -0,0 +1,23 @@ +# Templating + +**Templating is:** + +> Simply a way to represent data in different forms. + +Templating is essential for crafting customized notifications. It involves using templates for both the notification title and body. In Mission Control, these templates are rendered using Go templates. To determine which variables you can use in a specific event's template, refer to the corresponding event details in the [events](../concepts/events.md) section. + +## Go Template + +Go templates are a feature of the Go programming language that allow you to define and execute templates. Templates are text files that contain placeholders for data, which are filled in at runtime. The view data for the template is the [search param](./api.md#search-params). + +```yaml +events: + - check.passed +title: Check as {{.check.status}} +template: | + Canary: {{.canary.name}} + {{if .agent}}Agent: {{.agent.name}}{{end}} + Message: {{.status.message}} +filter: "check.type == 'http'" +. . . +``` diff --git a/docs/notifications/events/components.md b/docs/notifications/events/components.md new file mode 100644 index 00000000..cb48efcf --- /dev/null +++ b/docs/notifications/events/components.md @@ -0,0 +1,52 @@ +Component status updates emit the following events + +1. `component.status.healthy` +2. `component.status.unhealthy` +3. `component.status.warning` +4. `component.status.error` +5. `component.status.info` + +## Environment variables + +| Field | Description | Schema | Optional | +| ----------- | ----------------------------- | ------------------------- | -------- | +| `component` | The component object | [`Component`](#component) | | +| `agent` | Agent details (if applicable) | [`Agent`](#check) | `true` | +| `permalink` | A link to the health check | `string` | | + +### Component + +| Field | Description | Schema | Optional | +| ----------------- | -------------------------------------------- | ------------------- | -------- | +| `id` | The id of the component | `uuid` | | +| `description` | The description of the component | `string` | | +| `external_id` | The external id of the component | `string` | | +| `hidden` | Whether the component is hidden | `bool` | | +| `labels` | The labels of the component | `map[string]string` | `true` | +| `name` | The name of the component | `string` | | +| `namespace` | The namespace of the component | `string` | | +| `parent_id` | The id of the parent component | `uuid` | `true` | +| `properties` | The properties of the component | `map[string]string` | `true` | +| `silenced` | Whether the component is silenced | `bool` | | +| `status_reason` | The status reason of the component | `string` | | +| `status` | The status of the component | `string` | | +| `summary` | The summary of the component | `map[string]string` | `true` | +| `text` | The text of the component | `string` | | +| `topology_type` | The type of the topology | `string` | | +| `type` | The type of the component | `string` | | +| `cost_per_minute` | The cost per minute of the component | `float64` | | +| `cost_total_1d` | The cost total 1d of the component | `float64` | | +| `cost_total_7d` | The cost total 7d of the component | `float64` | | +| `cost_total_30d` | The cost total 30d of the component | `float64` | | +| `created_by` | Id of the person that created this component | `uuid` | | +| `created_at` | Created timestamp | `time.Time` | | +| `updated_at` | Updated timestamp | `time.Time` | | +| `deleted_at` | Deleted timestamp | `time.Time` | `true` | + +### Agent + +| Field | Description | Schema | Optional | +| ------------- | ------------------------------ | -------- | -------- | +| `id` | The id of the agent | `uuid` | | +| `name` | The name of the agent | `string` | | +| `description` | Short description of the agent | `string` | | diff --git a/docs/notifications/events/health-checks.md b/docs/notifications/events/health-checks.md new file mode 100644 index 00000000..816cd91b --- /dev/null +++ b/docs/notifications/events/health-checks.md @@ -0,0 +1,89 @@ +Health checks emit 2 events + +1. `check.passed` +2. `check.failed` + +## Environment variables + +| Field | Description | Schema | Optional | +| ----------- | ----------------------------- | ------------------------------ | -------- | +| `canary` | The parent canary object | [`Canary`](#canary) | | +| `check` | The check | [`Check`](#check) | | +| `agent` | Agent details (if applicable) | [`Agent`](#check) | `true` | +| `status` | Check status details | [`CheckStatus`](#check-status) | | +| `permalink` | A link to the health check | `string` | | + +### Canary + +| Field | Description | Schema | Optional | +| ------------ | ---------------------------- | ------------------- | -------- | +| `id` | The id of the canary | `uuid` | | +| `name` | The name of the canary | `string` | | +| `namespace` | The namespace of the canary | `string` | | +| `agent_id` | The agent id of the canary | `string` | | +| `labels` | The labels of the canary | `map[string]string` | `true` | +| `source` | The source of the canary | `string` | | +| `created_at` | The created at of the canary | `string` | | +| `updated_at` | The updated at of the canary | `string` | | +| `deleted_at` | The deleted at of the canary | `string` | `true` | + +### Check + +| Field | Description | Schema | Optional | +| ---------------------- | -------------------------------------- | --------------------- | -------- | +| `id` | The id of the check | `uuid` | | +| `type` | The type of the check | `string` | | +| `name` | The name of the check | `string` | | +| `labels` | The labels of the check | `map[string]string` | `true` | +| `description` | The description of the check | `string` | | +| `status` | Check status details | `string` | | +| `severity` | The severity of the check | `string` | `true` | +| `uptime` | The past 1 hour uptime summary | [`Uptime`](#uptime) | `true` | +| `latency` | The past 1 hour latency summary | [`Latency`](#latency) | `true` | +| `transformed` | Whether the check has been transformed | `bool` | | +| `last_runtime` | The last runtime of the check | `time.Time` | `true` | +| `next_runtime` | The next runtime of the check | `time.Time` | `true` | +| `last_transition_time` | The last transition time of the check | `time.Time` | `true` | +| `created_at` | The created at of the check | `time.Time` | | +| `updated_at` | The updated at of the check | `time.Time` | | +| `deleted_at` | The deleted at of the check | `time.Time` | `true` | + +#### Uptime + +| Field | Description | Schema | Optional | +| ----------- | ------------------------------------ | ----------- | -------- | +| `passed` | The number of checks that passed | `int` | | +| `failed` | The number of checks that failed | `int` | | +| `p100` | The percentage of checks that passed | `float64` | | +| `last_pass` | The last time a check passed | `time.Time` | `true` | +| `last_fail` | The last time a check failed | `time.Time` | `true` | + +#### Latency + +| Field | Description | Schema | Optional | +| ----------- | ------------------------ | --------- | -------- | +| `p99` | The latency of the check | `float64` | `true` | +| `p97` | The latency of the check | `float64` | `true` | +| `p95` | The latency of the check | `float64` | `true` | +| `rolling1h` | The latency of the check | `float64` | | + +### Agent + +| Field | Description | Schema | Optional | +| ------------- | ------------------------------ | -------- | -------- | +| `id` | The id of the agent | `uuid` | | +| `name` | The name of the agent | `string` | | +| `description` | Short description of the agent | `string` | | + +### Check Status + +| Field | Description | Schema | Optional | +| ------------ | ----------------------------------------------- | ----------- | -------- | +| `check_id` | The id of the check associated with this status | `uuid` | | +| `status` | The status of the check | `bool` | | +| `invalid` | Whether the check errored out | `bool` | | +| `time` | The time of the check | `string` | | +| `duration` | The duration of the check | `int` | | +| `message` | The success message of the check | `string` | | +| `error` | The error of the check in case of failure | `string` | | +| `created_at` | The created at of the check | `time.Time` | | diff --git a/docs/notifications/events/incidents.md b/docs/notifications/events/incidents.md new file mode 100644 index 00000000..7c089f33 --- /dev/null +++ b/docs/notifications/events/incidents.md @@ -0,0 +1,185 @@ +There are various subcategories for incident related evens + +## Incidents + +- `incident.created` + +**Environment variables:** + +| Field | Description | Schema | Optional | +| ----------- | -------------------------- | ----------------------- | -------- | +| `incident` | The incident object | [`Incident`](#incident) | | +| `permalink` | A link to the health check | `string` | | + +## Comments + +- `incident.comment.added` + +**Environment variables:** + +| Field | Description | Schema | Optional | +| ----------- | -------------------------- | ----------------------- | -------- | +| `comment` | The comment object | [`Comment`](#comment) | | +| `author` | The author of the comment | [`Person`](#person) | | +| `incident` | The linked incident object | [`Incident`](#incident) | | +| `permalink` | A link to the health check | `string` | | + +## Responders + +- `incident.responder.added` +- `incident.responder.removed` + +**Environment variables:** + +| Field | Description | Schema | Optional | +| ----------- | -------------------------- | ------------------------- | -------- | +| `responder` | The incident object | [`Responder`](#responder) | | +| `incident` | The linked incident object | [`Incident`](#incident) | | +| `permalink` | A link to the health check | `string` | | + +## Definition of done + +- `incident.dod.added` +- `incident.dod.passed` +- `incident.dod.regressed` + +**Environment variables**: + +| Field | Description | Schema | Optional | +| ------------ | ---------------------------------------- | --------------------------- | -------- | +| `evidence` | The evidence on which the dod is defined | [`Evidence`](#evidence) | | +| `incident` | The linked incident object | [`Incident`](#incident) | | +| `hypothesis` | The linked hypothesis object | [`Hypothesis`](#hypothesis) | | +| `permalink` | A link to the health check | `string` | | + +## Status + +- `incident.status.cancelled` +- `incident.status.closed` +- `incident.status.investigating` +- `incident.status.mitigated` +- `incident.status.open` +- `incident.status.resolved` + +**Environment variables:** + +| Field | Description | Schema | Optional | +| ----------- | -------------------------- | ----------------------- | -------- | +| `incident` | The incident object | [`Incident`](#incident) | | +| `permalink` | A link to the health check | `string` | | + +## References + +### Incident + +| Field | Description | Schema | Optional | +| ------------------ | --------------------------------------------------------------------------------------- | ----------- | -------- | +| `id` | The id of the incident | `uuid.UUID` | | +| `incident_id` | The incident id | `string` | | +| `title` | The title of the incident | `string` | | +| `description` | The description of the incident | `string` | | +| `type` | The type of the incident ([Read more](../../incidents/overview.md#types)) | `string` | | +| `status` | The status of the incident ([Read more](../../incidents/overview.md#status)) | `string` | | +| `severity` | The severity of the incident ([Read more](../../incidents/overview.md#severity-levels)) | `string` | | +| `created_at` | The time the incident was created | `time.Time` | | +| `updated_at` | The time the incident was updated | `time.Time` | | +| `acknowledged` | The time the incident was acknowledged | `time.Time` | `true` | +| `resolved` | The time the incident was resolved | `time.Time` | `true` | +| `closed` | The time the incident was closed | `time.Time` | `true` | +| `created_by` | The user who created the incident | `uuid.UUID` | | +| `incident_rule_id` | The incident rule id | `uuid.UUID` | `true` | +| `commander_id` | The commander id | `uuid.UUID` | `true` | +| `communicator_id` | The communicator id | `uuid.UUID` | `true` | + +### Comment + +| Field | Description | Schema | Optional | +| --------------------- | -------------------------------- | ----------- | -------- | +| `id` | The id of the comment | `uuid.UUID` | | +| `created_by` | The user who created the comment | `uuid.UUID` | | +| `comment` | The comment | `string` | | +| `external_id` | The external id | `string` | `true` | +| `external_created_by` | The external created by user | `string` | `true` | +| `incident_id` | The incident id | `uuid.UUID` | | +| `responder_id` | The responder id | `uuid.UUID` | `true` | +| `hypothesis_id` | The hypothesis id | `uuid.UUID` | `true` | +| `updated_at` | The time the comment was updated | `time.Time` | | +| `created_by` | The user who created the comment | `uuid.UUID` | | + +### Person + +| Field | Description | Schema | Optional | +| ------------ | ---------------------------- | -------------------------------------- | -------- | +| `id` | The id of the person | `uuid.UUID` | | +| `name` | The name of the person | `string` | | +| `email` | The email of the person | `string` | `true` | +| `type` | The type of the person | `string` | `true` | +| `avatar` | The avatar of the person | `string` | `true` | +| `properties` | The properties of the person | [`PersonProperties`](#person-property) | `true` | + +#### Person Property + +| Field | Description | Schema | Optional | +| ------ | ----------------------- | -------- | -------- | +| `role` | The key of the property | `string` | | + +### Evidence + +| Field | Description | Schema | Optional | +| -------------------- | ---------------------- | ---------------- | -------- | +| `id` | The id of the evidence | `uuid.UUID` | | +| `hypothesis_id` | The hypothesis id | `uuid.UUID` | | +| `config_id` | The config id | `uuid.UUID` | `true` | +| `config_change_id` | The config change id | `uuid.UUID` | `true` | +| `config_analysis_id` | The config analysis id | `uuid.UUID` | `true` | +| `component_id` | The component id | `uuid.UUID` | `true` | +| `check_id` | The check id | `uuid.UUID` | `true` | +| `description` | The description | `string` | | +| `definition_of_done` | The definition of done | `bool` | | +| `done` | The done | `bool` | `true` | +| `factor` | The factor | `bool` | `true` | +| `mitigator` | The mitigator | `bool` | `true` | +| `created_by` | The created by | `uuid.UUID` | | +| `type` | The type | `string` | | +| `script` | The script | `string` | `true` | +| `script_result` | The script result | `string` | `true` | +| `evidence` | The evidence | `map[string]any` | `true` | +| `properties` | The properties | `map[string]any` | `true` | +| `created_at` | The created at | `time.Time` | | +| `updated_at` | The updated at | `time.Time` | + +### Hypothesis + +| Field | Description | Schema | Optional | +| ------------- | --------------------------- | ----------- | -------- | +| `id` | The id of the hypothesis | `uuid.UUID` | | +| `incident_id` | The incident id | `uuid.UUID` | | +| `type` | The type | `string` | | +| `title` | The title of the hypothesis | `string` | | +| `status` | The status | `string` | | +| `parent_id` | The parent id | `uuid.UUID` | `true` | +| `team_id` | The team id | `uuid.UUID` | `true` | +| `owner` | ID of the owner | `uuid.UUID` | `true` | +| `created_at` | created timestamp | `time.Time` | | +| `updated_at` | updated timestamp | `time.Time` | | +| `created_by` | created timestamp | `uuid.UUID` | | + +### Responder + +| Field | Description | schema | Optional | +| -------------- | -------------------------------------------- | ---------------- | -------- | +| `id` | The id of the responder | `uuid.UUID` | | +| `incident_id` | The incident id | `uuid.UUID` | | +| `type` | The type of the responder | `string` | | +| `index` | The index of the responder | `smallint` | | +| `person_id` | The person id | `uuid.UUID` | `true` | +| `team_id` | The team id | `uuid.UUID` | `true` | +| `external_id` | id of the externally linked responder | `string` | `true` | +| `properties` | properties | `map[string]any` | `true` | +| `acknowledged` | Whether the responder was acknowledged | `time.Time` | `true` | +| `resolved` | Timestamp of when the responder was resolved | `time.Time` | `true` | +| `closed` | Timestamp of when the responder was closed | `time.Time` | `true` | +| `created_by` | ID of the person that created this responder | `uuid.UUID` | | +| `created_at` | created timestamp | `time.Time` | | +| `updated_at` | updated timestamp | `time.Time` | | +| `deleted_at` | deleted timestamp | `time.Time` | | diff --git a/docs/notifications/index.md b/docs/notifications/index.md new file mode 100644 index 00000000..74999a65 --- /dev/null +++ b/docs/notifications/index.md @@ -0,0 +1,32 @@ +Notifications keep you updated on any new activites in Mission Control. Example: You can receive an email notification when any HTTP health check fails, or a Slack notification whenever a high severity incident is created, etc. + +Notifications are highly configurable. You can specify where you want to receive them, how you want to receive them, and when to receive them. + +For more information, see the list of [supported event types](./concepts/events.md). + +## Supported Channels + +Mission control uses [Shoutrrr](https://github.com/containrrr/shoutrrr/) under the hood to deliver notifications. Most of the services in the Shoutrrr are supported. Here's the complete list: + +| Services | URL Format | +| ----------- | ---------------------------------------------------------------------------------------- | +| Bark | `bark://devicekey@host` | +| Discord | `discord://token@id ` | +| Email | `smtp://username:password@host:port/?from=fromAddress&to=recipient1[,recipient2,...]` | +| Gotify | `gotify://gotify-host/token` | +| Google Chat | `googlechat://chat.googleapis.com/v1/spaces/FOO/messages?key=bar&token=baz ` | +| IFTTT | `ifttt://key/?events=event1[,event2,...]&value1=value1&value2=value2&value3=value3 ` | +| Join | `join://shoutrrr:api-key@join/?devices=device1[,device2, ...][&icon=icon][&title=title]` | +| Mattermost | `mattermost://[username@]mattermost-host/token[/channel]` | +| Matrix | `matrix://username:password@host:port/[?rooms=!roomID1[,roomAlias2]] ` | +| Ntfy | `ntfy://username:password@ntfy.sh/topic` | +| OpsGenie | `opsgenie://host/token?responders=responder1[,responder2] ` | +| Pushbullet | `pushbullet://api-token[/device/#channel/email]` | +| Pushover | `pushover://shoutrrr:apiToken@userKey/?devices=device1[,device2, ...]` | +| Rocketchat | `rocketchat://[username@]rocketchat-host/token[/channel\| @recipient]` | +| Slack | `slack://[botname@]token-a/token-b/token-c` | +| Teams | `teams://group@tenant/altId/groupOwner?host=organization.webhook.office.com` | +| Telegram | `telegram://token@telegram?chats=@channel-1[,chat-id-1,...]` | +| Zulip Chat | `zulip://bot-mail:bot-key@zulip-domain/?stream=name-or-id&topic=name` | + +For more details please visit: [https://containrrr.dev/shoutrrr/0.8/services/overview/](https://containrrr.dev/shoutrrr/0.7/services/overview/) diff --git a/mkdocs.yml b/mkdocs.yml index 4cafb389..9ddf4046 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -222,8 +222,19 @@ nav: - Hypothesis: ./incidents/concepts/hypothesis.md - Rules: ./incidents/concepts/rules.md - Responders: ./incidents/concepts/responders.md - - Notifications: ./incidents/concepts/notifications.md - Definition of Done: ./incidents/concepts/done-definition.md + - Notifications: + - Overview: ./notifications/index.md + - Concepts: + - Notification: ./notifications/concepts/notification.md + - Templating: ./notifications/concepts/templating.md + - Filtering: ./notifications/concepts/filtering.md + - Events: ./notifications/concepts/events.md + - Recipients: ./notifications/concepts/recipients.md + - Events: + - Health Checks: ./notifications/events/health-checks.md + - Component: ./notifications/events/components.md + - Incidents: ./notifications/events/incidents.md - Playbooks: - Overview: ./playbooks/overview.md - Quick Start: ./playbooks/quick-start.md