valeriansaliou / vigil

🚦 Microservices Status Page. Monitors a distributed infrastructure and sends alerts (Slack, SMS, etc.).
https://crates.io/crates/vigil-server
Mozilla Public License 2.0
1.72k stars 128 forks source link
email-notifications infrastructure infrastructure-services microservices monitor monitoring servers slack slack-notifications sms-notifications status statuspage vigil webhook-events

Vigil

Test and Build Build and Release dependency status Buy Me A Coffee

Microservices Status Page. Monitors a distributed infrastructure and sends alerts (Slack, SMS, etc.).

Vigil is an open-source Status Page you can host on your infrastructure, used to monitor all your servers and apps, and visible to your users (on a domain of your choice, eg. status.example.com).

It is useful in microservices contexts to monitor both apps and backends. If a node goes down in your infrastructure, you receive a status change notification in a Slack channel, Email, Twilio SMS or/and XMPP.

Tested at Rust version: rustc 1.71.1 (eb26296b5 2023-08-03)

🇭🇺 Crafted in Budapest, Hungary.

👉 See a live demo of Vigil on Crisp Status Page.

:newspaper: The Vigil project was announced in a post on my personal journal.

Vigil

Who uses it?

Crisp Meilisearch miragespace Redsmin Image-Charts Pikomit Notice Bareconnect

👋 You use Vigil and you want to be listed there? Contact me.

Features

How does it work?

Vigil monitors all your infrastructure services. You first need to configure target services to be monitored, and then Vigil does the rest for you.

There are three kinds of services Vigil can monitor:

It is recommended to configure Vigil, Vigil Reporter or Vigil Local to send frequent probe checks, as to ensure you are quickly notified when a service gets down (thus to reduce unexpected downtime on your services).

Hosted alternative to Vigil

Vigil needs to be hosted on your own systems, and maintained on your end. If you do not feel like managing yet another service, you may use Crisp Status instead.

Crisp Status is a direct port of Vigil to the Crisp customer support platform.

Crisp Status hosts your status page on Crisp systems, and is able to do what Vigil does (and even more!). Crisp Status is integrated to other Crisp products (eg. Crisp Chatbox & Crisp Helpdesk). It warns your users over chatbox and helpdesk if your status page reports as dead for an extended period of time.

As an example of a status page running Crisp Status, check out Enrich Status Page.

How to use it?

Installation

Vigil is built in Rust. To install it, either download a version from the Vigil releases page, use cargo install or pull the source code from master.

👉 Each release binary comes with an .asc signature file, which can be verified using @valeriansaliou GPG public key: :key:valeriansaliou.gpg.pub.asc.

Install from packages:

Vigil provides pre-built packages for Debian-based systems (Debian, Ubuntu, etc.).

Important: Vigil only provides 64 bits packages targeting Debian 10, 11 & 12 for now (codenames: buster, bullseye & bookworm). You will still be able to use them on other Debian versions, as well as Ubuntu.

First, add the Vigil APT repository (eg. for Debian bookworm):

echo "deb [signed-by=/usr/share/keyrings/valeriansaliou_vigil.gpg] https://packagecloud.io/valeriansaliou/vigil/debian/ bookworm main" > /etc/apt/sources.list.d/valeriansaliou_vigil.list
curl -fsSL https://packagecloud.io/valeriansaliou/vigil/gpgkey | gpg --dearmor -o /usr/share/keyrings/valeriansaliou_vigil.gpg
apt-get update

Then, install the Vigil package:

apt-get install vigil

Then, edit the pre-filled Vigil configuration file:

nano /etc/vigil/vigil.cfg

Finally, restart Vigil:

service vigil restart

Install from Cargo:

If you prefer managing vigil via Rust's Cargo, install it directly via cargo install:

cargo install vigil-server

Ensure that your $PATH is properly configured to source the Crates binaries, and then run Vigil using the vigil command.

Install from source:

The last option is to pull the source code from Git and compile Vigil via cargo:

cargo build --release

You can find the built binaries in the ./target/release directory.

Install libssl-dev (ie. OpenSSL headers) and libstrophe-dev (ie. XMPP library headers; only if you need the XMPP notifier) before you compile Vigil. SSL dependencies are required for the HTTPS probes and email notifications.

Install from Docker Hub:

You might find it convenient to run Vigil via Docker. You can find the pre-built Vigil image on Docker Hub as valeriansaliou/vigil.

Pre-built Docker version may not be the latest version of Vigil available.

First, pull the valeriansaliou/vigil image:

docker pull valeriansaliou/vigil:v1.26.3

Then, seed it a configuration file and run it (replace /path/to/your/vigil/config.cfg with the path to your configuration file):

docker run -p 8080:8080 -v /path/to/your/vigil/config.cfg:/etc/vigil.cfg valeriansaliou/vigil:v1.26.3

In the configuration file, ensure that:

Vigil will be reachable from http://localhost:8080.

Configuration

Use the sample config.cfg configuration file and adjust it to your own environment.

You can also use environment variables with string interpolation in your configuration file, eg. manager_token = ${VIGIL_MANAGER_TOKEN}.

Available configuration options are commented below, with allowed values:

[server]

[assets]

[branding]

[metrics]

[plugins]

[plugins.rabbitmq]

[notify]

[notify.email]

[notify.twilio]

[notify.slack]

[notify.zulip]

[notify.telegram]

[notify.pushover]

[notify.gotify]

[notify.xmpp]

Notice: the XMPP notifier requires libstrophe (libstrophe-dev package on Debian) to be available when compiling Vigil, with the feature notifier-xmpp enabled upon Cargo build.

[notify.matrix]

[notify.webex]

[notify.webhook]

[probe]

[[probe.service]]

[[probe.service.node]]

Run Vigil

Vigil can be run as such:

./vigil -c /path/to/config.cfg

Usage recommendations

Consider the following recommendations when using Vigil:

What status variants look like?

Vigil has 3 status variants, either healthy (no issue ongoing), sick (services under high load) or dead (outage):

Healthy status variant

Status Healthy

Sick status variant

Status Sick

Dead status variant

Status Dead

What do announcements look like?

Announcements can be published to let your users know about any planned maintenance, as well as your progress on resolving a downtime:

Announcement

What do alerts look like?

When a monitored backend or app goes down in your infrastructure, Vigil can let you know by Slack, Twilio SMS, Email and XMPP:

Vigil alert in Slack

You can also get nice realtime down and up alerts on your eg. iPhone and Apple Watch:

Vigil down alert on iPhone (Slack) Vigil up alert on Apple Watch (Slack) Vigil alerts on iPhone (Twilio SMS)

## What do Webhook payloads look like? If you are using the Webhook notifier in Vigil, you will receive a JSON-formatted payload with alert details upon any status change; plus reminders if `notify.reminder_interval` is configured. **Here is an example of a Webhook payload:** ```json { "type": "changed", "status": "dead", "time": "08:58:28 UTC+0200", "replicas": [ "web:core:tcp://edge-3.pool.net.crisp.chat:80" ], "page": { "title": "Crisp Status", "url": "https://status.crisp.chat/" } } ``` Webhook notifications can be tested with eg. [Webhook.site](https://webhook.site/), before you integrate them to your custom endpoint. _You can use those Webhook payloads to create custom notifiers to anywhere. For instance, if you are using Microsoft Teams but not Slack, you may write a tiny PHP script that receives Webhooks from Vigil and forwards a notification to Microsoft Teams. This can be handy; while Vigil only implements convenience notifiers for some selected channels, the Webhook notifier allows you to extend beyond that._ ## How can I create script probes? Vigil lets you create custom probes written as shell scripts, passed in the Vigil configuration as a list of scripts to be executed for a given node. Those scripts can be used by advanced Vigil users when their monitoring use case requires scripting, ie. when `push` and `poll` probes are not enough. The replica health should be returned by the script shell as return codes, where: * **`rc=0`**: `healthy` * **`rc=1`**: `sick` * **`rc=2` and higher**: `dead` As scripts are usually multi-line, script contents can be passed as a literal string, enclosed between `'''`. As an example, the following script configuration always return as `sick`: ``` scripts = [ ''' # Do some work... exit 1 ''' ] ``` _Note that scripts are executed in a system shell ran by a Vigil-owned sub-process. Make sure that Vigil runs on an UNIX user with limited privileges. Running Vigil as root would let any configured script perform root-level actions on the machine, which is not recommended._ ## How can I integrate Vigil Reporter in my code? Vigil Reporter is used to actively submit health information to Vigil from your apps. Apps are best monitored via application probes, which are able to report detailed system information such as CPU and RAM load. This lets Vigil show if an application host system is under high load. ### Vigil Reporter Libraries * **NodeJS**: **[node-vigil-reporter](https://www.npmjs.com/package/vigil-reporter)** * **TypeScript**: **[ts-vigil-reporter](https://github.com/NikoGrano/ts-vigil-reporter)** * **Python**: **[py-vigil-reporter](https://pypi.org/project/py-vigil-reporter/)** * **Golang**: **[go-vigil-reporter](https://github.com/valeriansaliou/go-vigil-reporter)** * **Rust**: **[rs-vigil-reporter](https://crates.io/crates/vigil-reporter)** * **Dart**: **[dart-vigil-reporter](https://github.com/jonasroussel/dart_vigil_reporter)** * **C#**: **[cs-vigil-reporter](https://github.com/R3-IoT/cs-vigil-reporter)** 👉 Cannot find the library for your programming language? Build your own and be referenced here! ([contact me](https://valeriansaliou.name/)) ### Vigil Reporter HTTP API In case you need to manually report node metrics to the Vigil endpoint, use the following HTTP configuration (adjust it to yours). 👉 Read the [Vigil Reporter HTTP API](./PROTOCOL.md#vigil-reporter-http-api) protocol specifications. ## How can I administrate Vigil through Vigil Manager? Vigil Manager can be used to perform administrative actions on a running Vigil instance. For instance, it can be used to publish public announcements. ### Vigil Manager HTTP API Vigil Manager can be interacted with over its dedicated HTTP API. 👉 Read the [Vigil Manager HTTP API](./PROTOCOL.md#vigil-manager-http-api) protocol specifications. ## How can I monitor services on a different LAN using Vigil Local? Vigil Local is an (optional) slave daemon that you can use to report internal service health to your Vigil-powered status page master server. It is designed to be used behind a firewall, and to monitor hosts bound to a local loop or LAN network, that are not available to your main Vigil status page. Vigil Local monitors local `poll` and `script` replicas, and reports their status to Vigil on a periodic basis. You can [read more on Vigil Local](https://github.com/valeriansaliou/vigil-local) on its repository, and follow the setup instructions. ## :children_crossing: Troubleshoot Issues ### ICMP replicas always report as `dead` On Linux systems, non-priviledge users cannot create raw sockets, which Vigil ICMP probing system requires. It means that, by default, all ICMP probe attempts will fail silently, as if the host being probed was always down. This can easily be fixed by allowing Vigil to create raw sockets: ```bash setcap 'cap_net_raw+ep' /bin/vigil ``` _Note that HTTP and TCP probes do not require those raw socket capabilities._ ## :fire: Report A Vulnerability If you find a vulnerability in Vigil, you are more than welcome to report it directly to [@valeriansaliou](https://github.com/valeriansaliou) by sending an encrypted email to [valerian@valeriansaliou.name](mailto:valerian@valeriansaliou.name). Do not report vulnerabilities in public GitHub issues, as they may be exploited by malicious people to target production servers running an unpatched Vigil server. **:warning: You must encrypt your email using [@valeriansaliou](https://github.com/valeriansaliou) GPG public key: [:key:valeriansaliou.gpg.pub.asc](https://valeriansaliou.name/files/keys/valeriansaliou.gpg.pub.asc).**