Skip to content

Commit

Permalink
Reformat markdown documentation.
Browse files Browse the repository at this point in the history
  • Loading branch information
@BuJo
BuJo committed Jan 3, 2025
1 parent 77cb860 commit b4b0ec2
Show file tree
Hide file tree
Showing 4 changed files with 83 additions and 82 deletions.
97 changes: 50 additions & 47 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,15 @@
# Releases

## 1.12.2 - 2025-01-03 New Year

## 1.12.1 - 2024-10-17 Patchman Slowness

* Handle slow patchman instances.

## 1.12.0 - 2024-10-17 Patchman Filter

* Enable pre-filtering Patchman results, see [example.toml](config.example.toml) for details.
* Enable pre-filtering Patchman results, see [example.toml](config.example.toml)
for details.

## 1.11.0 - 2024-10-16 Menu Styling

Expand All @@ -15,7 +18,8 @@

## 1.10.2 - 2024-09-03 Log Volume Fix

* The 1.10.0 version unfortunately introduced a large unnecessary log volume change.
* The 1.10.0 version unfortunately introduced a large unnecessary log volume
change.

## 1.10.1 - 2024-08-29 Graylog Labels

Expand All @@ -31,24 +35,23 @@

## 1.9.0 - 2024-07-10 Tracing IDs

* Using `tuwat -otelUrl stdout` or `TUWAT_OTEL_URL=stdout` now enables
tracing output on stdout.
* Using `tuwat -otelUrl stdout` or `TUWAT_OTEL_URL=stdout` now enables tracing
output on stdout.
* Add spans/traces to logs to enable correlation
* Cleanup file paths in logging for visibility by stripping the
build path.
* Cleanup file paths in logging for visibility by stripping the build path.
* Remove error logging keys containing `<nil>` strings.

## 1.8.0 - 2024-06-05 Icinga2 Host ACKs

* Downtimes and acknowledgements as well as disabling notifications
for a host will also disable those for the services on this host.
This differs from `icinga` and `nagios`, as they allow actions
like `Schedule downtime for this host` vs. `allow downtime for
* Downtimes and acknowledgements as well as disabling notifications for a host
will also disable those for the services on this host. This differs from
`icinga` and `nagios`, as they allow actions like
`Schedule downtime for this host` vs. `allow downtime for
this host and all services`.
* Potentially breaking: Change logging system from `zap` to stdlib
`slog`. In case the logs are parsed using external systems, the
logs are now in a different format.
This was done to reduce the overall amount of dependencies.
`slog`. In case the logs are parsed using external systems, the logs are now
in a different format. This was done to reduce the overall amount of
dependencies.

## 1.7.0 - 2024-04-29 Negative Times

Expand All @@ -57,9 +60,9 @@

## 1.6.0 - 2024-02-21 GitLab MR groups

* Allow GitLab Groups to be configured for pulling merge requests.
This has the advantage of needing to specify fewer single projects
and also ignores archived projects by default.
* Allow GitLab Groups to be configured for pulling merge requests. This has the
advantage of needing to specify fewer single projects and also ignores
archived projects by default.
* Fix application crash on certain network timeouts.

## 1.5.2 - 2024-02-20
Expand All @@ -73,13 +76,12 @@

## 1.5.0 - 2024-02-19 backend mode

* Add `alertmanager` API, e.g. `/api/alertmanager/v2/status` for
use as API project.
Note that this is an experimental feature and should not be relied
* Add `alertmanager` API, e.g. `/api/alertmanager/v2/status` for use as API
project. Note that this is an experimental feature and should not be relied
upon.
* Add negative matchers: `!=` and `!~`
* Use [semver](https://semver.org/) for versioning tuwat. This allows
tuwat to be used as a library.
* Use [semver](https://semver.org/) for versioning tuwat. This allows tuwat to
be used as a library.

## v1.4 - 2024-01-11 light mode

Expand All @@ -93,20 +95,20 @@

* Fix rule matching from `v1.1` which made every rule match everything.
* `tuwat` now listens to every network instead of only `localhost`
for the web port. The management port still only binds to `localhost`.
for the web port. The management port still only binds to `localhost`.
* The `icinga2` adapter now adds host groups to services.
* Add more documentation regarding rules and dashboards.

## v1.1 - 2023-11-20 Rule Matchers

* Add a `when` rule to be able to match on when the alert happened.
* Add more expressive rules, making it possible to express a
`greater than` on numerical values. See `README` for details.
`greater than` on numerical values. See `README` for details.
* Breaking configuration changes:
* The `what` rules are now combined via `AND` with label rules.
This streamlines the behaviour, making it behave like the label
rules themselves. It also makes it possible e.g. to express that
a rule matcher only applies when the alert is old.
* The `what` rules are now combined via `AND` with label rules. This
streamlines the behaviour, making it behave like the label rules
themselves. It also makes it possible e.g. to express that a rule matcher
only applies when the alert is old.

## v1.0 - 2023-10-23 Maintenance

Expand All @@ -130,21 +132,21 @@
* UX change: Full row for items now clickable for details
* Adds possibility of having multiple dashboards/rule-sets
* Breaking configuration changes:
* OAuth2 configuration is now a subsection named `OAuth2Creds`
* BasicAuth Username now configured with key `Username` instead of `User`
for all connectors.
* OAuth2 configuration is now a subsection named `OAuth2Creds`
* BasicAuth Username now configured with key `Username` instead of `User`
for all connectors.
* Breaking behavioural changes:
* If observability depends on the label `thing` for websocket connections,
this has been renamed to `client`.
* If observability depends on the label `thing` for websocket connections,
this has been renamed to `client`.

## v0.16 - 2023-06-12 Resource Consumption

* To not display all merge requests, you can now specify the projects via
`Projects = []`
* Fixes connection leak in nagios-api connector
* Breaking Configuration Changes:
* Change parsing of rules, so that label matchers are combined with `AND`
instead of `OR`.
* Change parsing of rules, so that label matchers are combined with `AND`
instead of `OR`.

## v0.15 - 2023-05-26 GitLab MR flood

Expand All @@ -158,8 +160,9 @@

Breaking Changes:

* actuator endpoints now on different port, no longer on main port (`8988` by default)
* http://127.0.0.1:8987/actuator/health (`/info`, `/prometheus`)
* actuator endpoints now on different port, no longer on main port (`8988` by
default)
* http://127.0.0.1:8987/actuator/health (`/info`, `/prometheus`)

## v0.13 - 2023-05-11 Multiple Users

Expand All @@ -174,25 +177,25 @@ Breaking Changes:

* Add a new GitHub collector showing open issues/pull requests
* Breaking Configuration Changes:
* `GND_ENVIRONMENT` env var renamed to `TUWAT_ENVIRONMENT`
* `GND_INSTANCE` env var renamed to `TUWAT_INSTANCE`
* `GND_ADDR` env var renamed to `TUWAT_ADDR`
* `-mode dev|prod` removed in favour of `TUWAT_TEMPLATEDIR` and
`TUWAT_STATICDIR` env vars.
* `GND_ENVIRONMENT` env var renamed to `TUWAT_ENVIRONMENT`
* `GND_INSTANCE` env var renamed to `TUWAT_INSTANCE`
* `GND_ADDR` env var renamed to `TUWAT_ADDR`
* `-mode dev|prod` removed in favour of `TUWAT_TEMPLATEDIR` and
`TUWAT_STATICDIR` env vars.
* Added `TUWAT_CONF` env var for specifying the configuration file

## v0.10 - 2023-02-10 Minimize Collections

* Do not collect, if there is no-one subscribed to the dashboard to
avoid cpu/network activity
* Do not collect, if there is no-one subscribed to the dashboard to avoid
cpu/network activity
* Propagate telemetry information to sources

## v0.9 - 2022-10-31 Open Source

* Open the source under a 3-Clause BSD License
* Preparations for releasing on GitHub
* Rename project from a temporary `gonagdash` to a hopefully less
temporary `tuwat`.
* Rename project from a temporary `gonagdash` to a hopefully less temporary
`tuwat`.
* Revise output on `tuwat -version`

## v0.8 - 2022-10-24 Silencing
Expand Down Expand Up @@ -228,5 +231,5 @@ Stream changes to the browser via Websockets.

## v0.1 - 2022-09-24 Initial Release

Initial Release of Tuwat providing a basic non-working Dashboard for
Nagios, Icinga 2, Patchman, Alertmanager and GitLab MRs.
Initial Release of Tuwat providing a basic non-working Dashboard for Nagios,
Icinga 2, Patchman, Alertmanager and GitLab MRs.
23 changes: 11 additions & 12 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,12 @@

## What is the tuwat Dashboard?

Tuwat is a replacement for the venerable [Nagdash] which had been adapted
time and time again to provide accessors for an evolving infrastructure.
Tuwat is a replacement for the venerable [Nagdash] which had been adapted time
and time again to provide accessors for an evolving infrastructure.

The driving mindset for Tuwat (in German "tu was", meaning "do something")
is to show actionable items. This is a slight departure of [Nagdash],
which shows only Nagios `Hosts`/`Services`.
is to show actionable items. This is a slight departure of [Nagdash], which
shows only Nagios `Hosts`/`Services`.

[Nagdash]: https://github.com/lozzd/Nagdash

Expand Down Expand Up @@ -48,8 +48,8 @@ Available styles:
The main configuration can contain `Rules`, but if multiple rule-sets/dashboards
are needed, dashboards can be added to a folder.

The `-dashboards` flag can be used to specify the folder, by default it looks
at `/etc/tuwat.d`.
The `-dashboards` flag can be used to specify the folder, by default it looks at
`/etc/tuwat.d`.

The files have to end with `.toml`, the basename will be used as dashboard name.

Expand Down Expand Up @@ -86,16 +86,15 @@ 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
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
is implemented.
* See `pkg/connectors/example` for a very basic example on how a connector is
implemented.

### JavaScript Development

Expand Down
19 changes: 9 additions & 10 deletions docs/dashboards.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@

## Single Dashboard

To only show a single dashboard, simply add all configuration
and rules in the main `config.toml`.
To only show a single dashboard, simply add all configuration and rules in the
main `config.toml`.

### Example

Expand All @@ -20,15 +20,13 @@ 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.
* `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]
Expand All @@ -37,9 +35,10 @@ 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.

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

Expand Down
26 changes: 13 additions & 13 deletions docs/rules.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,8 @@ 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.
* The `what` field selects all items where the `What` matches the given regular
expression.

```toml
[[rule]]
Expand All @@ -28,31 +28,31 @@ when = "> 60"
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` 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` with other label rules and `when` and
`what` rules.
* `when` rules interpreted as "X seconds from now". The above example would match
an alert when the alert has lasted a minimum of 60 seconds. Times in the future
have an undefined behaviour.
* `when` rules interpreted as "X seconds from now". The above example would
match an alert when the alert has lasted a minimum of 60 seconds. Times in the
future have an undefined behaviour.

## 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`: Explicitly require a regular expression to be matched. This is
the same as just leaving `=~ ` out.
* `!~ string`: Require non-matching regular expression to be matched.
* `= string|number`: Require the string or number to exactly match. In case
* `= 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
floating point value. This means that differences below `1e-8` will be
considered to be the same.
* `!= string|number`: Require not matching the exact string/number.
* `> 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.
configured number. This also applies to the `<`, `>=`, `<=` operators.

### Example

Expand Down

0 comments on commit b4b0ec2

Please sign in to comment.