diff --git a/README.md b/README.md index cc0fd80..ad87045 100644 --- a/README.md +++ b/README.md @@ -46,6 +46,9 @@ at `/etc/tuwat.d`. The files have to end with `.toml`, the basename will be used as dashboard name. +For further examples and more information on dashboards, see the +[dashboard documentation](docs/dashboards.md). + ### Rules The rule-system works via an exclude list, matching rules simply exclude items. @@ -58,40 +61,7 @@ description = "blocked because not needed" what = "fooo service" ``` -* The `description` field provides a visible explanation, why the item is - excluded. -* The `what` field selects all items where the `What` matches the given - regular expression. - -```toml -[[rule]] -description = "Ignore Drafts" -what = "Thing" -when = "> 60" -[rule.label] -Draft = "true" -``` - -* The `label` section selects items via labels. In this example it would match - an item which has the label `Draft` which matches the given regular expression. -* The label rules will combine as `AND`. -* `what` rules will combine as `AND` with label rules. -* `when` rules will combine with `AND` with label and `what` rules. - -#### Matching Rules - -The default is to match the value in the configuration as a regular expression. -However, this can be changed by specifying an operator. - -* `~= string`: Explicitly require a regular expression to be matched -* `= string`: Require the string to exactly match. In case the value is - numeric, this will mean that the value will compared like a floating point - value. This means that differences below `1e-8` will be considered to be - the same. -* `> number`: Require both configuration and the value in the alert to be a - numerical value and that the value in the alert to be bigger than the - configured number. - This also applies to the `<`, `>=`, `<=` operators. +For more information, see the [rule documentation](docs/rules.md). ## License @@ -109,6 +79,12 @@ export TUWAT_TEMPLATEDIR= TUWAT_STATICDIR= * Open http://localhost:8988 +Setting `TUWAT_TEMPLATEDIR` and `TUWAT_STATICDIR` to empty will +automatically use the development directories (`pkg/web/templates` +and `pkg/web/static` respectively). +Not declaring the template/static directory means that the +versions bundled into the binary are used. + ### Adding a new collector * See `pkg/connectors/example` for a very basic example on how a connector diff --git a/docs/config/dashboards/drafts.toml b/docs/config/dashboards/drafts.toml new file mode 100644 index 0000000..719abea --- /dev/null +++ b/docs/config/dashboards/drafts.toml @@ -0,0 +1,7 @@ +[main] +mode = "include" + +[[rule]] +description = "Show only drafts" +[rule.label] +Draft = "true" diff --git a/docs/config/dashboards/no-drafts.toml b/docs/config/dashboards/no-drafts.toml new file mode 100644 index 0000000..5f4d48c --- /dev/null +++ b/docs/config/dashboards/no-drafts.toml @@ -0,0 +1,4 @@ +[[rule]] +description = "Ignore Drafts" +[rule.label] +Draft = "true" diff --git a/docs/dashboards.md b/docs/dashboards.md new file mode 100644 index 0000000..1d49efd --- /dev/null +++ b/docs/dashboards.md @@ -0,0 +1,72 @@ +# Dashboards + +## Single Dashboard + +To only show a single dashboard, simply add all configuration +and rules in the main `config.toml`. + +### Example + +`tuwat -conf config.toml` + +```toml +[[rule]] +description = "Ignore Drafts" +[rule.label] +Draft = "true" + +[[github]] +Repos = ['synyx/tuwat', 'synyx/buchungsstreber'] +Tag = 'gh' +``` + + +### Dashboard types + +There are two kinds of dashboards: + +* `mode = "exclude"`: The normal kind of dashboard. Each rule + will filter the matching items from the board. +* `mode = "include"`: Only items matching the rules are shown + on the board. + +```toml +[main] +mode = "include" +``` + +## Multiple Dashboards + +To have multiple dashboards, split the configuration into a main config in `config.toml` and create a folder containing the +rule files for additional dashboards. These dashboards will appear in the navigation bar named like the corresponding files. + + +### Example + +`tuwat -conf config.toml -dashboards tuwat.d` + +```toml +# config.example.toml +[[github]] +Repos = ['synyx/tuwat', 'synyx/buchungsstreber'] +Tag = 'gh' +``` + +```toml +# tuwat.d/no-drafts.toml +[[rule]] +description = "Ignore Drafts" +[rule.label] +Draft = "true" +``` + +```toml +# tuwat.d/drafts.toml +[main] +mode = "include" + +[[rule]] +description = "Show only drafts" +[rule.label] +Draft = "true" +``` diff --git a/docs/rules.md b/docs/rules.md new file mode 100644 index 0000000..45fbe13 --- /dev/null +++ b/docs/rules.md @@ -0,0 +1,69 @@ +# Rules + +The rule-system works via an exclude list, matching rules will include or +exclude the matching items, depending on the +[type of dashboard](dashboards.md#dashboard-types). + +The configuration is done via [toml](https://toml.io/). + +For example: + +```toml +[[rule]] +description = "blocked because not needed" +what = "fooo service" +``` + +* The `description` field provides a visible explanation, why the item is + excluded. +* The `what` field selects all items where the `What` matches the given + regular expression. + +```toml +[[rule]] +description = "Ignore Drafts" +what = "Thing" +when = "> 60" +[rule.label] +Draft = "true" +``` + +* The `label` section selects items via labels. In this example it would match + an item which has the label `Draft` which matches the given regular expression. +* The label rules will combine as `AND`. +* `what` rules will combine as `AND` with label rules. +* `when` rules will combine with `AND` with label and `what` rules. + +## Matching Rules + +The default is to match the value in the configuration as a regular expression. +However, this can be changed by specifying an operator. + +* `~= string`: Explicitly require a regular expression to be matched. + This is the same as just leaving `~= ` out. +* `= string|number`: Require the string or number to exactly match. In case + the value is numeric, this will mean that the value will compared like a + floating point value. This means that differences below `1e-8` will be + considered to be the same. +* `> number`: Require both configuration and the value in the alert to be a + numerical value and that the value in the alert to be bigger than the + configured number. + This also applies to the `<`, `>=`, `<=` operators. + +### Example + +```toml +[[rule]] +description = "Ignore certain group" +[rule.label] +groups = "= A-Group" + +[[rule]] +description = "Ignore all with group beginning with A" +[rule.label] +groups = "~= (^|,)A" + +[[rule]] +description = "Ignore old things" +when = ">= 60" +```