diff --git a/alert/.gitignore b/alert/.gitignore new file mode 100644 index 0000000000000000000000000000000000000000..332fefb3ae376fb47d21c8e5d44c2d1d61f96e5a --- /dev/null +++ b/alert/.gitignore @@ -0,0 +1,21 @@ +# Binaries for programs and plugins +*.exe +*.exe~ +*.dll +*.so +*.dylib + +# Test binary, built with `go test -c` +*.test + +# Output of the go coverage tool, specifically when used with LiteIDE +*.out + +# Dependency directories (remove the comment below to include it) +vendor/ + +# Project specific files +cmd/alert/alert +cmd/alert/alert.log +*.db +*.gz \ No newline at end of file diff --git a/alert/README.md b/alert/README.md new file mode 100644 index 0000000000000000000000000000000000000000..aa3738a3946b32b1fe16f07843943644cbda62a2 --- /dev/null +++ b/alert/README.md @@ -0,0 +1,180 @@ +# Alert [DRAFT] + +The Alert application reads data from [TDEngine](https://www.taosdata.com/), calculating according to predefined rules to generate alerts, and pushes alerts to downstream applications like [AlertManager](https://github.com/prometheus/alertmanager). + +## Install + +### From Binary + +TODO: 安装包具体位置 + +Precompiled binaries is available at [taosdata website](https://www.taosdata.com/), please download and unpack it by below shell command. + +``` +$ tar -xzf alert-$version-$OS-$ARCH.tar.gz +``` + +### From Source Code + +Two prerequisites are required to install from source. + +1. TDEngine server or client must be installed. +2. Latest [Go](https://golang.org) language must be installed. + +When these two prerequisites are ready, please follow steps below to build the application: + +``` +$ mkdir taosdata +$ cd taosdata +$ git clone https://github.com/taosdata/tdengine.git +$ cd tdengine/alert/cmd/alert +$ go build +``` + +If `go build` fails because some of the dependency packages cannot be downloaded, please follow steps in [goproxy.io](https://goproxy.io) to configure `GOPROXY` and try `go build` again. + +## Configure + +The configuration file format of Alert application is standard `json`, below is its default content, please revise according to actual scenario. + +```json +{ + "port": 8100, + "database": "file:alert.db", + "tdengine": "root:taosdata@/tcp(127.0.0.1:0)/", + "log": { + "level": "production", + "path": "alert.log" + }, + "receivers": { + "alertManager": "http://127.0.0.1:9093/api/v1/alerts", + "console": true + } +} +``` + +The use of each configuration item is: + +* **port**: This is the `http` service port which enables other application to manage rules by `restful API`. +* **database**: rules are stored in a `sqlite` database, this is the path of the database file (if the file does not exist, the alert application creates it automatically). +* **tdengine**: connection string of `TDEngine` server, note in most cases the database information should be put in a rule, thus it should NOT be included here. +* **log > level**: log level, could be `production` or `debug`. +* **log > path**: log output file path. +* **receivers > alertManager**: the alert application pushes alerts to `AlertManager` at this URL. +* **receivers > console**: print out alerts to console (stdout) or not. + +When the configruation file is ready, the alert application can be started with below command (`alert.cfg` is the path of the configuration file): + +``` +$ ./alert -cfg alert.cfg +``` + +## Prepare an alert rule + +From technical aspect, an alert could be defined as: query and filter recent data from `TDEngine`, and calculating out a boolean value from these data according to a formula, and trigger an alert if the boolean value last for a certain duration. + +This is a rule example in `json` format: + +```json +{ + "name": "rule1", + "sql": "select sum(col1) as sumCol1 from test.meters where ts > now - 1h group by areaid", + "expr": "sumCol1 > 10", + "for": "10m", + "period": "1m", + "labels": { + "ruleName": "rule1" + }, + "annotations": { + "summary": "sum of rule {{$labels.ruleName}} of area {{$values.areaid}} is {{$values.sumCol1}}" + } +} +``` + +The fields of the rule is explained below: + +* **name**: the name of the rule, must be unique. +* **sql**: this is the `sql` statement used to query data from `TDEngine`, columns of the query result are used in later processing, so please give the column an alias if aggregation functions are used. +* **expr**: an expression whose result is a boolean value, arithmatic and logical calculations can be included in the expression, and builtin functions (see below) are also supported. Alerts are only triggered when the expression evaluates to `true`. +* **for**: this item is a duration which default value is zero second. when `expr` evaluates to `true` and last at least this duration, an alert is triggered. +* **period**: the interval for the alert application to check the rule, default is 1 minute. +* **labels**: a label list, labels are used to generate alert information. note if the `sql` statement includes a `group by` clause, the `group by` columns are inserted into this list automatically. +* **annotations**: the template of alert information which is in [go template](https://golang.org/pkg/text/template) syntax, labels can be referenced by `$labels.