mirror of
https://github.com/prymitive/karma
synced 2026-05-07 03:26:52 +00:00
312 lines
8.9 KiB
Markdown
312 lines
8.9 KiB
Markdown
# unsee
|
|
|
|
Alert dashboard for [Prometheus Alertmanager](https://prometheus.io/docs/alerting/alertmanager/).
|
|
|
|
Alertmanager UI is useful for browsing alerts and managing silences, but it's
|
|
lacking as a dashboard tool - unsee aims to fill this gap.
|
|
It's developed as a dedicated tool as it's intended to provide only read access
|
|
to alert data, therefore safe to be accessed by wider audience.
|
|
|
|
|
|
|
|
## Supported Alertmanager versions
|
|
|
|
Alertmanager's API isn't stable yet and can change between releases, make sure
|
|
that the correct version of unsee is used:
|
|
|
|
* `0.1` release supports Alertmanager `0.4`
|
|
* `0.2` release supports Alertmanager `0.5`
|
|
|
|
`master` branch in git will always work with the latest supported Alertmanager
|
|
release.
|
|
|
|
## Building and running
|
|
|
|
### Installing using the go command
|
|
|
|
unsee is go installable, so the easiest way is to run:
|
|
|
|
go install github.com/cloudflare/unsee
|
|
|
|
The `unsee` binary will be installed into `$GOPATH/bin` directory.
|
|
Note that this will build the latest master version which might not work with
|
|
your Alertmanager version. See
|
|
[supported Alertmanager versions](#supported-alertmanager-versions).
|
|
|
|
### Building from source
|
|
|
|
To clone git repo and build the binary yourself run:
|
|
|
|
git clone https://github.com/cloudflare/unsee $GOPATH/src/github.com/cloudflare/unsee
|
|
cd $GOPATH/src/github.com/cloudflare/unsee
|
|
|
|
Check [supported Alertmanager versions](#supported-alertmanager-versions) and if
|
|
needed switch to the release branch that supports your Alertmanager version.
|
|
For example to build unsee `0.2.x` run:
|
|
|
|
git checkout -t release-0.2
|
|
|
|
To finally compile `unsee` the binary run:
|
|
|
|
make
|
|
|
|
## Running
|
|
|
|
`unsee` is configured via environment variables or command line flags.
|
|
Environment variable `ALERTMANAGER_URI` or cli flag `-alertmanager.uri` is the
|
|
only option required to run. See [Environment variables](#environment-variables)
|
|
section below for the full list of supported environment variables. Examples:
|
|
|
|
ALERTMANAGER_URI=https://alertmanager.example.com unsee
|
|
unsee -alertmanager.uri https://alertmanager.example.com
|
|
|
|
There is a make target which will compile and run unsee:
|
|
|
|
make run
|
|
|
|
By default it will listen on port `8080` and Alertmanager mock data will be
|
|
used, to override Alertmanager URI set `ALERTMANAGER_URI` and/or `PORT` make
|
|
variables. Example:
|
|
|
|
make PORT=5000 ALERTMANAGER_URI=https://alertmanager.example.com run
|
|
|
|
## Docker
|
|
|
|
### Building a Docker image
|
|
|
|
make docker-image
|
|
|
|
This will build a Docker image from sources.
|
|
|
|
### Running the Docker image
|
|
|
|
make run-docker
|
|
|
|
Will run locally built Docker image. Same defaults and override variables
|
|
apply as with `make run`. Example:
|
|
|
|
make PORT=5000 ALERTMANAGER_URI=https://alertmanager.example.com run-docker
|
|
|
|
## Environment variables
|
|
|
|
#### ALERTMANAGER_TIMEOUT
|
|
|
|
Timeout for requests send to Alertmanager, accepts values in
|
|
[time.Duration](https://golang.org/pkg/time/#Duration) format. Examples:
|
|
|
|
ALERTMANAGER_TIMEOUT=10s
|
|
ALERTMANAGER_TIMEOUT=2m
|
|
|
|
This option can also be set using `-alertmanager.timeout` flag. Example:
|
|
|
|
$ unsee -alertmanager.timeout 2m
|
|
|
|
Default is `40s`.
|
|
|
|
#### ALERTMANAGER_TTL
|
|
|
|
Interval for refreshing alerts and silences, tells unsee how often pull new
|
|
data from Alertmanager, accepts values in
|
|
[time.Duration](https://golang.org/pkg/time/#Duration) format. Examples:
|
|
|
|
ALERTMANAGER_TTL=30s
|
|
ALERTMANAGER_TTL=5m
|
|
|
|
This option can also be set using `-alertmanager.ttl` flag. Example:
|
|
|
|
$ unsee -alertmanager.ttl 5m
|
|
|
|
Default is `1m`.
|
|
|
|
Note that the maximum value for this option is `15m`.
|
|
The UI has a watchdog that tracks the timestamp of the last pull. If the UI
|
|
does not receive updates for more than 15 minutes it will print an error and
|
|
reload the page.
|
|
|
|
#### ALERTMANAGER_URI
|
|
|
|
URI of the Alertmanager instance, unsee will use it to pull alert groups and
|
|
silences. Endpoints in use:
|
|
|
|
* ${ALERTMANAGER_URI}/api/v1/alerts/groups
|
|
* ${ALERTMANAGER_URI}/api/v1/silences
|
|
|
|
Example:
|
|
|
|
ALERTMANAGER_URI=https://alertmanager.example.com
|
|
|
|
This option can also be set using `-alertmanager.uri` flag. Example:
|
|
|
|
$ unsee -alertmanager.uri https://alertmanager.example.com
|
|
|
|
This variable is required and there is no default value.
|
|
|
|
#### DEBUG
|
|
|
|
Will enable [gin](https://github.com/gin-gonic/gin) debug mode. This will
|
|
configure to print out more debugging information on startup.
|
|
Examples:
|
|
|
|
DEBUG=true
|
|
DEBUG=false
|
|
|
|
This option can also be set using `-debug` flag. Example:
|
|
|
|
$ unsee -debug
|
|
|
|
Default is `false`.
|
|
|
|
#### COLOR_LABELS_STATIC
|
|
|
|
List of label names that will all have the same color applied (different than
|
|
the default label color). This allows to quickly spot a specific label that
|
|
can have high range of values, but it's important when reading the dashboard.
|
|
For example coloring the instance label allows to quickly learn which instance
|
|
is affected by given alert. Accepts space separated list of label names.
|
|
Examples:
|
|
|
|
COLOR_LABELS_STATIC=instance
|
|
COLOR_LABELS_STATIC="instance cluster"
|
|
|
|
This option can also be set using `-color.labels.static` flag. Example:
|
|
|
|
$ unsee -color.labels.static "instance cluster"
|
|
|
|
This variable is optional and default is not set (no label will have static
|
|
color).
|
|
|
|
#### COLOR_LABELS_UNIQUE
|
|
|
|
List of label names that should have unique colors generated in the UI. Colors
|
|
can help visually identify alerts with shared labels, for example coloring
|
|
hostname label will allow to quickly spot all alerts for the same host.
|
|
Accepts space separated list of label names. Examples:
|
|
|
|
COLOR_LABELS_UNIQUE=hostname
|
|
COLOR_LABELS_UNIQUE="cluster environment rack"
|
|
|
|
This option can also be set using `-color.labels.unique` flag. Example:
|
|
|
|
$ unsee -color.labels.unique "cluster environment rack"
|
|
|
|
This variable is optional and default is not set (no label will have unique
|
|
color).
|
|
|
|
#### FILTER_DEFAULT
|
|
|
|
Default alert filter to apply when user loads unsee UI without any filter
|
|
specified. Accepts comma separated list of filter expressions (visit /help page
|
|
in unsee for details on filters). Examples:
|
|
|
|
FILTER_DEFAULT=level=critical
|
|
FILTER_DEFAULT="cluster=prod,instance=~prod"
|
|
|
|
This option can also be set using `-filter.default` flag. Example:
|
|
|
|
$ unsee -filter.default "cluster=prod,instance=~prod"
|
|
|
|
Default is not set (no filter will be applied).
|
|
|
|
#### JIRA_REGEX
|
|
|
|
This allows to define regex rules that will be applied to silence comments.
|
|
Regex rules will be used to discover JIRA issue IDs in the comment text and
|
|
inject links to those issues, instead of rendering as plain text.
|
|
Rule syntax:
|
|
|
|
$(regex)@$(jira url)
|
|
|
|
Accepts space separated list of rules. Examples:
|
|
|
|
JIRA_REGEX="DEVOPS-[0-9]+@https://jira.example.com"
|
|
|
|
The above will match DEVOPS-123 text in the silence comment string and convert
|
|
it to `https://jira.example.com/browse/DEVOPS-123` link.
|
|
|
|
This option can also be set using `-jira.regex` flag. Example:
|
|
|
|
$ unsee -jira.regex "DEVOPS-[0-9]+@https://jira.example.com"
|
|
|
|
This variable is optional and default is not set (no rule will be applied).
|
|
|
|
#### PORT
|
|
|
|
HTTP port to listen on. Example:
|
|
|
|
PORT=8000
|
|
|
|
This option can also be set using `-port` flag. Example:
|
|
|
|
$ unsee -port 8000
|
|
|
|
Default is `8080`.
|
|
|
|
#### SENTRY_DSN
|
|
|
|
DSN for [Sentry](https://sentry.io) integration in Go. See
|
|
[Sentry documentation](https://docs.sentry.io/quickstart/#configure-the-dsn) for
|
|
details. Example:
|
|
|
|
SENTRY_DSN=https://<key>:<secret>@sentry.io/<project>
|
|
|
|
This option can also be set using `-sentry.dsn` flag. Example:
|
|
|
|
$ unsee -sentry.dsn "https://<key>:<secret>@sentry.io/<project>"
|
|
|
|
This variable is optional and default is not set (Sentry support is disabled for
|
|
Go errors).
|
|
|
|
#### SENTRY_PUBLIC_DSN
|
|
|
|
DSN for [Sentry](https://sentry.io) integration in javascript. See
|
|
[Sentry documentation](https://docs.sentry.io/clients/javascript/) for details.
|
|
Example:
|
|
|
|
SENTRY_PUBLIC_DSN=https://<key>@sentry.io/<project>
|
|
|
|
This option can also be set using `-sentry.public.dsn` flag. Example:
|
|
|
|
$ unsee -sentry.public.dsn "https://<key>@sentry.io/<project>"
|
|
|
|
This variable is optional and default is not set (Sentry support is disabled for
|
|
javascript errors).
|
|
|
|
#### STRIP_LABELS
|
|
|
|
List of label names that should not be shown on the UI. This allows to hide some
|
|
labels that are not needed on the alert dashboard. Accepts space separated list
|
|
of label names. Examples:
|
|
|
|
STRIP_LABELS=exporter_type
|
|
STRIP_LABELS="prometheus_instance alert_type"
|
|
|
|
This option can also be set using `-strip.labels` flag. Example:
|
|
|
|
$ unsee -strip.labels "prometheus_instance alert_type"
|
|
|
|
This variable is optional and default is not set (all labels will be shown).
|
|
|
|
#### WEB_PREFIX
|
|
|
|
URL root for unsee, you can use to if you wish to serve it from location other
|
|
than /. Examples:
|
|
|
|
WEB_PREFIX=/unsee/
|
|
|
|
This will configure unsee to serve requests from http://localhost/unsee/
|
|
instead http://localhost/.
|
|
|
|
This option can also be set using `-web.prefix` flag. Example:
|
|
|
|
$ unsee -web.prefix /unsee/
|
|
|
|
Default is `/`.
|
|
|
|
## Contributing
|
|
|
|
Please see [CONTRIBUTING](/CONTRIBUTING.md) for details.
|
|
|
|
## License
|
|
|
|
Apache License 2.0, please see [LICENSE](/LICENSE).
|