chore: Cleanup README

mr-karan · Jan 16, 2019 · 41dda1f · 41dda1f
1 parent 230e0a8
commit 41dda1f
Showing 1 changed file with 72 additions and 29 deletions.
diff --git a/README.md b/README.md
@@ -4,61 +4,102 @@
 
 ## Overview [![GoDoc](https://godoc.org/github.com/mr-karan/calert?status.svg)](https://godoc.org/github.com/mr-karan/calert) [![Go Report Card](https://goreportcard.com/badge/github.com/mr-karan/calert)](https://goreportcard.com/report/github.com/mr-karan/calert)
 
+[![GitHub tag](https://img.shields.io/github/tag/mr-karan/calert.svg)](https://github.com/mr-karan/calert/releases/)
+
 `calert` is a lightweight binary to push [Alertmanager](https://github.com/prometheus/alertmanager) notifications to [Google Chat](http://chat.google.com) via webhook integration.
 
-## Install
+## Table of Contents
 
-There are various ways of installing calert.
+-   [Getting Started](#getting-started-quickstart)
 
-### Precompiled binaries
+    -   [How it Works](#how-it-works)
+    -   [Installation](#installation)
+    -   [Quickstart](#quickstart)
+    -   [Testing a sample alert](#testing-a-sample-alert)
 
-Precompiled binaries for released versions are available in the [_Releases_ section](https://github.com/mr-karan/calert/releases/).
+-   [Advanced Section](#advanced-section)
 
-### Compiling the binary
+    -   [Configuration options](#configuation-options)
+    -   [API Usage](#api-usage)
+    -   [Setting up Prometheus](#setting-up-prometheus)
 
-You can checkout the source code and build manually:
+-   [Ansible Playbook](#ansible-playbook) <_Coming Soon_>
 
-```
-$ mkdir -p $GOPATH/src/github.com/mr-karan/
-$ cd $GOPATH/src/github.com/mr-karan
-$ git clone https://github.com/mr-karan/calert.git
-$ cd calert
-$ make build
-$ cp config.toml.sample config.toml
-$ ./calert
-```
+## Getting Started (Quickstart)
 
-## How to Use
+### How it Works
+
+![](images/calert.svg)
 
 `calert` uses Alertmanager [webhook receiver](https://prometheus.io/docs/alerting/configuration/#webhook_config) to receive alerts payload, and pushes this data to Google Chat [webhook](https://developers.google.com/hangouts/chat/how-tos/webhooks) endpoint.
 
--   Download the binary and [sample config file](config.toml.sample) and place them in one folder.
+### Installation
+
+There are two ways of installing calert.
+
+-   ### Precompiled binaries
+
+    Precompiled binaries for released versions are available in the [_Releases_ section](https://github.com/mr-karan/calert/releases/).
+
+-   ### Compiling the binary
+
+    You can checkout the source code and build manually:
+
+    ```
+    $ mkdir -p $GOPATH/src/github.com/mr-karan/
+    $ cd $GOPATH/src/github.com/mr-karan
+    $ git clone https://github.com/mr-karan/calert.git
+    $ cd calert
+    $ make build
+    $ cp config.toml.sample config.toml
+    $ ./calert
+    ```
+
+### Quickstart
 
 ```sh
-mkdir calert-example && cd calert-example/
+mkdir calert-example && cd calert-example/ # copy the binary and config.toml.sample in this folder
 cp config.toml.sample config.toml # change the settings like hostname, address, google chat webhook url, timeouts etc in this file.
-./calert.bin # this command starts a web server and is ready to receive events from alertmanager
+./calert.bin # this command starts a web server (calert API) and is ready to receive events from alertmanager
 ```
 
 -   Set the webhook URL from Google Chat in `[app.chat.<yourRoomName>.notification_url]` section of `config.toml`. You can refer to the [official documentation](https://developers.google.com/hangouts/chat/quickstart/incoming-bot-python#step_1_register_the_incoming_webhook) for more details.
 
--   Configure Alertmanager config file (`alertmanager.yml`) and give the address of calert web-server. You can refer to the [official documentation](https://prometheus.io/docs/alerting/configuration/#webhook_config) for more details.
-
 You are now ready to send alerts to Google Chat!
 
+### Testing a sample alert
+
+To help you quickly get started, you can `POST` a dummy payload which is similar to `Alertmanager` payload, present in [examples/send_alert.sh](examples/send_alert.sh).
+
 ![](images/gchat.png)
 
-## Configuration
+## Advanced Section
 
--   You can configure the default template for notification and create your own. Create a [template](https://golang.org/pkg/text/template/) file, similar to [message.tmpl](message.tmpl) and set the path of this file in `[app.template_file]` section of `config.toml`
+### Configuration Options
 
--   Alertmanager has the ability of group similar alerts together and fire only one event, clubbing all the alerts data into one event. `calert` leverages this and sends all alerts in one message by looping over the alerts and passing data in the template. You can configure the rules for grouping the alerts in `alertmanager.yml` config. You can read more about it [here](https://github.com/prometheus/docs/blob/master/content/docs/alerting/alertmanager.md#grouping)
+-   **[server]**
 
--   You can use `--config.file` parameter to supply a custom config file path while running `calert`.
+    -   **address**: Port which the server listens to.
+    -   **socket**: _Optional_, if you want to connect to the server using unix socket.
+    -   **name**: _Optional_, human identifier for the server.
+    -   **read_timeout**: Duration (in milliseconds) for the request body to be fully read) Read this [blog](https://blog.cloudflare.com/the-complete-guide-to-golang-net-http-timeouts/) for more info.
+    -   **write_timeout**: Duration (in milliseconds) for the response body to be written.
+    -   **keepalive_timeout**: Duration (in milliseconds) the server waits for the connection to be re-used in case the request is sent with Keep-Alive header.
 
-## API
+-   **[app]**
 
--   POST `/create?room_name=<>` (Used to receive new alerts and push to Google Chat)
+    -   **template_file**: Path to template file used for parsing Alertmanager payload to Google Chat message. You can configure the default template for notification and create your own. Create a [template](https://golang.org/pkg/text/template/) file, similar to [message.tmpl](message.tmpl) and set the path of this file in this setting.
+    -   **http_client**
+        -   **max_idle_conns**: _Optional_, human identifier for the server.
+        -   **request_timeout**: Duration (in milliseconds) to wait for the response.
+    -   **chat.your_room_name**
+        -   **notification_url**: Webhook URL of Google Chat Room where Incoming Webhooks are configured.
+
+**NOTE**: You can use `--config.file` parameter to supply a custom config file path while running `calert`.
+
+### API Usage
+
+-   POST `/create?room_name=<>` (Used to receive new alerts and push to Google Chat.)
 
 ```sh
 # example request. (See examples/send_alert.sh)
@@ -75,9 +116,11 @@ _`room_name`_ param is required. The same `room_name` should be present in `app.
 {"status":"success","data":{"buildVersion":"025a3a3 (2018-12-26 22:04:46 +0530)","buildDate":"2018-12-27 10:41:52","ping":"pong"}}
 ```
 
-## Examples
+### Setting Up Prometheus
 
-To help you quickly get started, you can `POST` a dummy payload which is similar to `Alertmanager` payload, present in [examples/send_alert.sh](examples/send_alert.sh).
+-   Alertmanager has the ability of group similar alerts together and fire only one event, clubbing all the alerts data into one event. `calert` leverages this and sends all alerts in one message by looping over the alerts and passing data in the template. You can configure the rules for grouping the alerts in `alertmanager.yml` config. You can read more about it [here](https://github.com/prometheus/docs/blob/master/content/docs/alerting/alertmanager.md#grouping).
+
+*   Configure Alertmanager config file (`alertmanager.yml`) and give the address of calert web-server. You can refer to the [official documentation](https://prometheus.io/docs/alerting/configuration/#webhook_config) for more details.
 
 ## Contribution