Skip to content

Commit

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

* feat: template vars

* chore: kubernetes deployment health notification example

* docs: slack template for components, config & check events

* docs: add all notification template vars in reference

* docs: complete all template vars for notification

* chore: lint workflow change

* chore: refactor config notification events page

* chore: add slack notification screenshots

* docs: notification rate limiting

* docs: slack template functions

* docs: use gomplate style for notification template functions

* docs: repeat interval
  • Loading branch information
adityathebe authored Sep 3, 2024
1 parent 817c8dc commit 1fddf7f
Show file tree
Hide file tree
Showing 26 changed files with 1,372 additions and 386 deletions.
15 changes: 14 additions & 1 deletion .github/workflows/lint.yml
Original file line number Diff line number Diff line change
Expand Up @@ -13,4 +13,17 @@ jobs:
with:
node-version: '20.11.1'

- run: make fmt-check
- name: Run format check
run: make fmt-check
continue-on-error: true
id: fmt-check

- name: Run formatter and show diff if check failed
if: steps.fmt-check.outcome == 'failure'
run: |
make fmt
git diff
- name: Exit with error if format check failed
if: steps.fmt-check.outcome == 'failure'
run: exit 1
2 changes: 1 addition & 1 deletion Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ fmt:

.PHONY: fmt-check
fmt-check:
npx prettier --check "**/*.md"
npx prettier --check --log-level=debug "**/*.md"

.PHONY:
sync:
Expand Down
2 changes: 1 addition & 1 deletion canary-checker/docs/windows.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ To run Canary Checker on windows please ensure the following

## 2. Downloading required files

You only need the powershell script below(assuming internet connectivity), place it in the folder you wish to install Canary Checker in.
You only need the powershell script below(assuming internet connectivity). Place it in the folder you wish to install Canary Checker in.

```powershell
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
Expand Down
86 changes: 58 additions & 28 deletions common/src/components/Fields.jsx
Original file line number Diff line number Diff line change
Expand Up @@ -28,8 +28,8 @@ const schemes = {
"notificationconnection": "[Connection](/reference/connections)",
"notificationproperties": "[map[string]string](/reference/notifications#properties)",
}
export default function Fields({ common = [], rows = [], oneOf, anyOf, connection }) {

export default function Fields({ common = [], rows = [], oneOf, anyOf, connection, withTemplates }) {
const { siteConfig, siteMetadata } = useDocusaurusContext();

const oss = siteConfig.customFields.oss;
Expand Down Expand Up @@ -292,55 +292,85 @@ export default function Fields({ common = [], rows = [], oneOf, anyOf, connectio

return (
<>
<table className='fields'>
<table className="fields">
<thead>
<tr>
<th>Field</th>
<th>Description</th>
<th>Scheme</th>
{withTemplates && <th>Template Env</th>}
</tr>
</thead>
<tbody>
{rows.map((row, index) => (
<tr key={index}>
<td>
<code className={row.required ? "font-bold" : ""}>{row.field}{row.required ? "*" : ""}</code>
<code className={row.required ? 'font-bold' : ''}>
{row.field}
{row.required ? '*' : ''}
</code>
</td>
<td><ReactMarkdown>{(row.description ? row.description : "") + (row.default ? `. Defaults to \`${row.default}\`` : '')}</ReactMarkdown></td>
<td>
{row.anyOf &&
<code>{row.anyOf.join(' | ')}</code>
}
{!row.anyOf && row.scheme &&
<ReactMarkdown>
{(row.description ? row.description : '') +
(row.default ? `. Defaults to \`${row.default}\`` : '')}
</ReactMarkdown>
</td>
<td>
{row.anyOf && <code>{row.anyOf.join(' | ')}</code>}
{!row.anyOf && row.scheme && (
<ReactMarkdown>
{
schemes[row.scheme.toLowerCase()] || (row.scheme ? row.scheme : 'string')
}
{schemes[row.scheme.toLowerCase()] ||
(row.scheme ? row.scheme : 'string')}
</ReactMarkdown>
}
)}
</td>
{withTemplates && (
<td>
{row.templateEnv &&
row.templateEnv.map((v) => (
<p>
<a href={v.url}>
<code>{v.name}</code>
</a>
</p>
))}
</td>
)}
</tr>
))}

</tbody>
</table >
{anyOf &&
<blockquote style={{ borderLeft: "2px solid var(--ifm-color-warning-light)" }}>
<p>You must specify <code>{anyOf[0]}</code> and/or <code>{anyOf[1]}</code></p>
</table>
{anyOf && (
<blockquote
style={{ borderLeft: '2px solid var(--ifm-color-warning-light)' }}
>
<p>
You must specify <code>{anyOf[0]}</code> and/or{' '}
<code>{anyOf[1]}</code>
</p>
</blockquote>
}
{
oneOf && oneOf.length == 2 &&
<blockquote style={{ borderLeft: "2px solid var(--ifm-color-warning-light)" }}>
<p>You must specify <code>{oneOf[0]}</code> or <code>{oneOf[1]}</code> but not both</p>
)}
{oneOf && oneOf.length == 2 && (
<blockquote
style={{ borderLeft: '2px solid var(--ifm-color-warning-light)' }}
>
<p>
You must specify <code>{oneOf[0]}</code> or <code>{oneOf[1]}</code>{' '}
but not both
</p>
</blockquote>
}
{
oneOf && oneOf.length == 3 &&
<blockquote style={{ borderLeft: "2px solid var(--ifm-color-warning-light)" }}>
<p>You must specify one of <code>{oneOf[0]}</code>, <code>{oneOf[1]}</code> or <code>{oneOf[2]}</code></p>
)}
{oneOf && oneOf.length == 3 && (
<blockquote
style={{ borderLeft: '2px solid var(--ifm-color-warning-light)' }}
>
<p>
You must specify one of <code>{oneOf[0]}</code>,{' '}
<code>{oneOf[1]}</code> or <code>{oneOf[2]}</code>
</p>
</blockquote>
}
)}
</>
)
}
8 changes: 8 additions & 0 deletions mission-control/docs/notifications/concepts/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
title: Concepts
sidebar_position: 2
---

import DocCardList from '@theme/DocCardList';

<DocCardList />
40 changes: 40 additions & 0 deletions mission-control/docs/notifications/concepts/rate-limiting.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
---
title: Rate Limiting
---

To prevent overwhelming users with excessive notifications, Mission Control implements a rate limiting mechanism.

We use a sliding window rate limiter that restricts the total number of notifications sent within a specified time period.

Check warning on line 7 in mission-control/docs/notifications/concepts/rate-limiting.mdx

View workflow job for this annotation

GitHub Actions / vale

[vale] mission-control/docs/notifications/concepts/rate-limiting.mdx#L7

[Flanksource.ProfanityUnlikely] Be careful with 'period', it's profane in some cases.
Raw output
{"message": "[Flanksource.ProfanityUnlikely] Be careful with 'period', it's profane in some cases.", "location": {"path": "mission-control/docs/notifications/concepts/rate-limiting.mdx", "range": {"start": {"line": 7, "column": 116}}}, "severity": "WARNING"}

:::info
The rate limit is applied individually to each notification.
:::

:::caution Rate Limited Notifications
When a notification exceeds the rate limit, it is dropped and not delivered to the user.
:::

## Default Configuration

The following table outlines the default rate limiting parameters:

| Property | Value |
|----------------------------------|----------|
| Maximum number of notifications allowed per window | 50 |
| Time period for the sliding window | 4 hours |

Check warning on line 24 in mission-control/docs/notifications/concepts/rate-limiting.mdx

View workflow job for this annotation

GitHub Actions / vale

[vale] mission-control/docs/notifications/concepts/rate-limiting.mdx#L24

[Flanksource.ProfanityUnlikely] Be careful with 'period', it's profane in some cases.
Raw output
{"message": "[Flanksource.ProfanityUnlikely] Be careful with 'period', it's profane in some cases.", "location": {"path": "mission-control/docs/notifications/concepts/rate-limiting.mdx", "range": {"start": {"line": 24, "column": 8}}}, "severity": "WARNING"}

## Customizing Rate Limiting Parameters

You can override the default settings by adjusting the following properties:

- `notifications.max.count`: Sets the maximum number of notifications allowed within the window
- `notifications.max.window`: Defines the duration of the sliding window (in hours)

### Example Configuration

To allow a maximum of 100 notifications in a 6 hour window:

```
notifications.max.count=100
notifications.max.window=6h
```
61 changes: 61 additions & 0 deletions mission-control/docs/notifications/concepts/repeat-interval.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
---
title: Repeat Interval
---

The repeat interval determines the duration between subsequent notifications after an initial successful delivery.

```yaml title="deployment-failed.yaml"
apiVersion: mission-control.flanksource.com/v1
kind: Notification
metadata:
name: config-updates
namespace: default
spec:
events:
- config.healthy
- config.unhealthy
- config.warning
- config.unknown
filter: config.type == "Kubernetes::Deployment"
to:
email: [email protected]
repeatInterval: 2h
```
The above notification sends at max 1 email notification in a moving 2 hour window.
## Repeat Group
By default, the repeat interval applies to any notification sent for the given notification.
In the example above, if a notification is sent for a `config.healthy` event and then a new notification is to be sent
for a `config.unhealthy` event, then the notification is dropped due to the repeat interval.

With grouping, you can apply the repeat interval per source event & per resource ID.

- `source_event`
- `resource_id`

```yaml title="deployment-updates.yaml"
apiVersion: mission-control.flanksource.com/v1
kind: Notification
metadata:
name: config-updates
namespace: default
spec:
events:
- config.healthy
- config.unhealthy
- config.warning
- config.unknown
filter: config.type == "Kubernetes::Deployment"
to:
email: [email protected]
repeatInterval: 2h
// highlight-start
repeatGroup:
- source_event
// highlight-end
```

With this change, you'll now receive at max 4 notifications for each source event.

Check warning on line 61 in mission-control/docs/notifications/concepts/repeat-interval.mdx

View workflow job for this annotation

GitHub Actions / vale

[vale] mission-control/docs/notifications/concepts/repeat-interval.mdx#L61

[Flanksource.FutureTense] Use present tense verbs, not future tense verbs like 'you'll'. Say '(event) happens' instead of '(event) will happen'.
Raw output
{"message": "[Flanksource.FutureTense] Use present tense verbs, not future tense verbs like 'you'll'. Say '(event) happens' instead of '(event) will happen'.", "location": {"path": "mission-control/docs/notifications/concepts/repeat-interval.mdx", "range": {"start": {"line": 61, "column": 19}}}, "severity": "WARNING"}
90 changes: 0 additions & 90 deletions mission-control/docs/notifications/events/components.md

This file was deleted.

Loading

0 comments on commit 1fddf7f

Please sign in to comment.