Skip to content

Commit

Permalink
docs: notification (#92)
Browse files Browse the repository at this point in the history 
* docs: notification

first draft

* doc: recipients

* docs: notification

* add environment variables for health check events

* env var for component events

* docs: env vars for incidents

* finalize notification documentation

* chore: remove screenshots and some fields
  • Loading branch information
@adityathebe
adityathebe authored Sep 13, 2023
1 parent d5e4ee7 commit 47b0a6f
Show file tree
Hide file tree
Showing 11 changed files with 517 additions and 68 deletions.
67 changes: 0 additions & 67 deletions docs/incidents/concepts/notifications.md
View file

This file was deleted.

16 changes: 16 additions & 0 deletions docs/notifications/concepts/events.md
View file
Original file line number Diff line number Diff line change
@@ -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.<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.<status>` | When a component's status changes |
19 changes: 19 additions & 0 deletions docs/notifications/concepts/filtering.md
View file
Original file line number Diff line number Diff line change
@@ -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
```
40 changes: 40 additions & 0 deletions docs/notifications/concepts/notification.md
View file
Original file line number Diff line number Diff line change
@@ -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://<api-token>@health-check-notifications
name: Slack-health-checks
```
49 changes: 49 additions & 0 deletions docs/notifications/concepts/recipients.md
View file
Original file line number Diff line number Diff line change
@@ -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/[email protected]
filter: incident.severity == 'High' || incident.severity == "Critical"

- url: slack://<api-token>@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}}'
```
23 changes: 23 additions & 0 deletions docs/notifications/concepts/templating.md
View file
Original file line number Diff line number Diff line change
@@ -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'"
. . .
```
52 changes: 52 additions & 0 deletions docs/notifications/events/components.md
View file
Original file line number Diff line number Diff line change
@@ -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` | |
Loading

0 comments on commit 47b0a6f

Please sign in to comment.