phares3757/gatus
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README.md

Browse Source
This commit is contained in:
Chris
2021-07-06 20:06:40 -04:00
committed by GitHub
parent 9d8a3f1574
commit 38de0ec9cd
1 changed files with 14 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files

58
README.md
View File

@ -26,7 +26,6 @@ For more details, see [Usage](#usage)
## Table of Contents ## Table of Contents
- [Why Gatus?](#why-gatus) - [Why Gatus?](#why-gatus)
- [Features](#features) - [Features](#features)
- [Usage](#usage) - [Usage](#usage)
@ -45,9 +44,9 @@ For more details, see [Usage](#usage)
- [Configuring custom alerts](#configuring-custom-alerts) - [Configuring custom alerts](#configuring-custom-alerts)
- [Kubernetes (ALPHA)](#kubernetes-alpha) - [Kubernetes (ALPHA)](#kubernetes-alpha)
- [Auto Discovery](#auto-discovery) - [Auto Discovery](#auto-discovery)
- [Deploying](#deploying) - [Deployment](#deployment)
- [Docker](#docker) - [Docker](#docker)
- [Helm Chart](#helm-chart) - [Helm Chart](#helm-chart)
- [Running the tests](#running-the-tests) - [Running the tests](#running-the-tests)
- [Using in Production](#using-in-production) - [Using in Production](#using-in-production)
- [FAQ](#faq) - [FAQ](#faq)
@ -68,7 +67,6 @@ For more details, see [Usage](#usage)
## Why Gatus? ## Why Gatus?
Before getting into the specifics, I want to address the most common question: Before getting into the specifics, I want to address the most common question:
> Why would I use Gatus when I can just use Prometheus’ Alertmanager, Cloudwatch or even Splunk? > Why would I use Gatus when I can just use Prometheus’ Alertmanager, Cloudwatch or even Splunk?
@ -87,7 +85,6 @@ fixing the issue before they even know about it.
## Features ## Features
![Gatus dark mode](.github/assets/dark-mode.png) ![Gatus dark mode](.github/assets/dark-mode.png)
The main features of Gatus are: The main features of Gatus are:
@ -101,7 +98,6 @@ The main features of Gatus are:
## Usage ## Usage
By default, the configuration file is expected to be at `config/config.yaml`. By default, the configuration file is expected to be at `config/config.yaml`.
You can specify a custom path by setting the `GATUS_CONFIG_FILE` environment variable. You can specify a custom path by setting the `GATUS_CONFIG_FILE` environment variable.
@ -135,7 +131,6 @@ If you want to test it locally, see [Docker](#docker).
## Configuration ## Configuration
| Parameter | Description | Default | | Parameter | Description | Default |
|:---------------------------------------- |:----------------------------------------------------------------------------- |:-------------- | |:---------------------------------------- |:----------------------------------------------------------------------------- |:-------------- |
| `debug` | Whether to enable debug logs | `false` | | `debug` | Whether to enable debug logs | `false` |
@ -178,7 +173,6 @@ If you want to test it locally, see [Docker](#docker).
### Conditions ### Conditions
Here are some examples of conditions you can use: Here are some examples of conditions you can use:
| Condition | Description | Passing values | Failing values | | Condition | Description | Passing values | Failing values |
@ -205,7 +199,6 @@ Here are some examples of conditions you can use:
#### Placeholders #### Placeholders
| Placeholder | Description | Example of resolved value | | Placeholder | Description | Example of resolved value |
|:-------------------------- |:--------------------------------------------------------------- |:------------------------- | |:-------------------------- |:--------------------------------------------------------------- |:------------------------- |
| `[STATUS]` | Resolves into the HTTP status of the request | 404 | `[STATUS]` | Resolves into the HTTP status of the request | 404
@ -230,7 +223,6 @@ Here are some examples of conditions you can use:
### Alerting ### Alerting
Gatus supports multiple alerting providers, such as Slack and PagerDuty, and supports different alerts for each Gatus supports multiple alerting providers, such as Slack and PagerDuty, and supports different alerts for each
individual services with configurable descriptions and thresholds. individual services with configurable descriptions and thresholds.
@ -274,7 +266,6 @@ ignored.
#### Configuring Slack alerts #### Configuring Slack alerts
```yaml ```yaml
alerting: alerting:
slack: slack:
@ -306,7 +297,6 @@ Here's an example of what the notifications look like:
#### Configuring Discord alerts #### Configuring Discord alerts
```yaml ```yaml
alerting: alerting:
discord: discord:
@ -329,7 +319,6 @@ services:
#### Configuring PagerDuty alerts #### Configuring PagerDuty alerts
It is highly recommended to set `services[].alerts[].send-on-resolved` to `true` for alerts It is highly recommended to set `services[].alerts[].send-on-resolved` to `true` for alerts
of type `pagerduty`, because unlike other alerts, the operation resulting from setting said of type `pagerduty`, because unlike other alerts, the operation resulting from setting said
parameter to `true` will not create another incident, but mark the incident as resolved on parameter to `true` will not create another incident, but mark the incident as resolved on
@ -359,7 +348,6 @@ services:
#### Configuring Twilio alerts #### Configuring Twilio alerts
```yaml ```yaml
alerting: alerting:
twilio: twilio:
@ -386,7 +374,6 @@ services:
#### Configuring Mattermost alerts #### Configuring Mattermost alerts
```yaml ```yaml
alerting: alerting:
mattermost: mattermost:
@ -441,7 +428,6 @@ services:
#### Configuring Telegram alerts #### Configuring Telegram alerts
```yaml ```yaml
alerting: alerting:
telegram: telegram:
@ -467,7 +453,6 @@ Here's an example of what the notifications look like:
#### Configuring custom alerts #### Configuring custom alerts
While they're called alerts, you can use this feature to call anything. While they're called alerts, you can use this feature to call anything.
For instance, you could automate rollbacks by having an application that keeps tracks of new deployments, and by For instance, you could automate rollbacks by having an application that keeps tracks of new deployments, and by
@ -525,7 +510,6 @@ As a result, the `[ALERT_TRIGGERED_OR_RESOLVED]` in the body of first example of
#### Setting a default provider alert #### Setting a default provider alert
While you can specify the alert configuration directly in the service definition, it's tedious and may lead to a very While you can specify the alert configuration directly in the service definition, it's tedious and may lead to a very
long configuration file. long configuration file.
@ -578,7 +562,6 @@ services:
### Kubernetes (ALPHA) ### Kubernetes (ALPHA)
> **WARNING**: This feature is in ALPHA. This means that it is very likely to change in the near future, which means that > **WARNING**: This feature is in ALPHA. This means that it is very likely to change in the near future, which means that
> while you can use this feature as you see fit, there may be breaking changes in future releases. > while you can use this feature as you see fit, there may be breaking changes in future releases.
@ -597,7 +580,6 @@ services:
#### Auto Discovery #### Auto Discovery
Auto discovery works by reading all `Service` resources from the configured `namespaces` and appending the `hostname-suffix` as Auto discovery works by reading all `Service` resources from the configured `namespaces` and appending the `hostname-suffix` as
well as the configured `target-path` to the service name and making an HTTP call. well as the configured `target-path` to the service name and making an HTTP call.
@ -636,13 +618,14 @@ Note that `hostname-suffix` could also be something like `.yourdomain.com`, in w
monitored would be `potato.example.com/health`, assuming you have a service named `potato` and a matching ingress monitored would be `potato.example.com/health`, assuming you have a service named `potato` and a matching ingress
to map `potato.example.com` to the `potato` service. to map `potato.example.com` to the `potato` service.
#### Deploying For a full example, see [example/kubernetes-with-auto-discovery](example/kubernetes-with-auto-discovery)
See [example/kubernetes-with-auto-discovery](example/kubernetes-with-auto-discovery)
## Docker ## Deployment
Many examples can be found in the [example](example) folder, but this section will focus on the most popular ways of deploying Gatus.
### Docker
To run Gatus locally with Docker: To run Gatus locally with Docker:
``` ```
docker run -p 8080:8080 --name gatus twinproduction/gatus docker run -p 8080:8080 --name gatus twinproduction/gatus
@ -665,12 +648,12 @@ To build the image locally:
docker build . -t twinproduction/gatus docker build . -t twinproduction/gatus
``` ```
## Helm Chart
### Helm Chart
[Helm](https://helm.sh) must be installed to use the chart. [Helm](https://helm.sh) must be installed to use the chart.
Please refer to Helm's [documentation](https://helm.sh/docs/) to get started. Please refer to Helm's [documentation](https://helm.sh/docs/) to get started.
Once Helm is set up properly, add the repo as follows: Once Helm is set up properly, add the repository as follows:
```console ```console
helm repo add gatus https://avakarev.github.io/gatus-chart helm repo add gatus https://avakarev.github.io/gatus-chart
@ -679,22 +662,19 @@ helm repo add gatus https://avakarev.github.io/gatus-chart
To get more details, please check chart's [configuration](https://github.com/avakarev/gatus-chart#configuration) To get more details, please check chart's [configuration](https://github.com/avakarev/gatus-chart#configuration)
and [helmfile example](https://github.com/avakarev/gatus-chart#helmfileyaml-example) and [helmfile example](https://github.com/avakarev/gatus-chart#helmfileyaml-example)
## Running the tests
## Running the tests
``` ```
go test ./... -mod vendor go test ./... -mod vendor
``` ```
## Using in Production ## Using in Production
See the [Deployment](#deployment) section.
See the [example](example) folder.
## FAQ ## FAQ
### Sending a GraphQL request ### Sending a GraphQL request
By setting `services[].graphql` to true, the body will automatically be wrapped by the standard GraphQL `query` parameter. By setting `services[].graphql` to true, the body will automatically be wrapped by the standard GraphQL `query` parameter.
For instance, the following configuration: For instance, the following configuration:
@ -725,9 +705,8 @@ will send a `POST` request to `http://localhost:8080/playground` with the follow
### Recommended interval ### Recommended interval
> **NOTE**: This does not _really_ apply if `disable-monitoring-lock` is set to `true`, as the monitoring lock is what
**NOTE**: This does not _really_ apply if `disable-monitoring-lock` is set to `true`, as the monitoring lock is what > tells Gatus to only evaluate one service at a time.
tells Gatus to only evaluate one service at a time.
To ensure that Gatus provides reliable and accurate results (i.e. response time), Gatus only evaluates one service at a time To ensure that Gatus provides reliable and accurate results (i.e. response time), Gatus only evaluates one service at a time
In other words, even if you have multiple services with the exact same interval, they will not execute at the same time. In other words, even if you have multiple services with the exact same interval, they will not execute at the same time.
@ -757,7 +736,6 @@ simple health checks used for alerting (PagerDuty/Twilio) to `30s`.
### Default timeouts ### Default timeouts
| Protocol | Timeout | | Protocol | Timeout |
|:-------- |:------- | |:-------- |:------- |
| HTTP | 10s | HTTP | 10s
@ -786,7 +764,6 @@ established.
### Monitoring a service using ICMP ### Monitoring a service using ICMP
By prefixing `services[].url` with `icmp:\\`, you can monitor services at a very basic level using ICMP, or more By prefixing `services[].url` with `icmp:\\`, you can monitor services at a very basic level using ICMP, or more
commonly known as "ping" or "echo": commonly known as "ping" or "echo":
@ -803,7 +780,6 @@ You can specify a domain prefixed by `icmp://`, or an IP address prefixed by `ic
### Monitoring a service using DNS queries ### Monitoring a service using DNS queries
Defining a `dns` configuration in a service will automatically mark that service as a service of type DNS: Defining a `dns` configuration in a service will automatically mark that service as a service of type DNS:
```yaml ```yaml
services: services:
@ -825,7 +801,6 @@ There are two placeholders that can be used in the conditions for services of ty
### Monitoring a service using STARTTLS ### Monitoring a service using STARTTLS
If you have an email server that you want to ensure there are no problems with, monitoring it through STARTTLS If you have an email server that you want to ensure there are no problems with, monitoring it through STARTTLS
will serve as a good initial indicator: will serve as a good initial indicator:
```yaml ```yaml
@ -840,7 +815,6 @@ services:
### Basic authentication ### Basic authentication
You can require Basic authentication by leveraging the `security.basic` configuration: You can require Basic authentication by leveraging the `security.basic` configuration:
```yaml ```yaml
security: security:
@ -853,7 +827,6 @@ The example above will require that you authenticate with the username `john.doe
### disable-monitoring-lock ### disable-monitoring-lock
Setting `disable-monitoring-lock` to `true` means that multiple services could be monitored at the same time. Setting `disable-monitoring-lock` to `true` means that multiple services could be monitored at the same time.
While this behavior wouldn't generally be harmful, conditions using the `[RESPONSE_TIME]` placeholder could be impacted While this behavior wouldn't generally be harmful, conditions using the `[RESPONSE_TIME]` placeholder could be impacted
@ -867,7 +840,6 @@ technically, if you create 100 services with a 1 seconds interval, Gatus will se
### Reloading configuration on the fly ### Reloading configuration on the fly
For the sake on convenience, Gatus automatically reloads the configuration on the fly if the loaded configuration file For the sake on convenience, Gatus automatically reloads the configuration on the fly if the loaded configuration file
is updated while Gatus is running. is updated while Gatus is running.
@ -891,7 +863,6 @@ the same as restarting the application.
### Service groups ### Service groups
Service groups are used for grouping multiple services together on the dashboard. Service groups are used for grouping multiple services together on the dashboard.
```yaml ```yaml
@ -937,7 +908,6 @@ The configuration above will result in a dashboard that looks like this:
### Exposing Gatus on a custom port ### Exposing Gatus on a custom port
By default, Gatus is exposed on port `8080`, but you may specify a different port by setting the `web.port` parameter: By default, Gatus is exposed on port `8080`, but you may specify a different port by setting the `web.port` parameter:
```yaml ```yaml
web: web: