Documentation improvement.

This commit is contained in:
Stanislav Nikitin 2020-12-23 21:33:39 +05:00
parent 084de1520f
commit cdfa948b7d
Signed by: pztrn
GPG Key ID: 1E944A0F0568B550
4 changed files with 105 additions and 5 deletions

95
docs/API.md Normal file
View File

@ -0,0 +1,95 @@
# Metricator's API
This page describes Metricator's API.
## URL forming
API URLs are formed like: `/api/vX/TYPE/OTHER_DATA`, where:
* `vX` is a version (e.g. `v1`).
* `TYPE` - request type (see below).
* `OTHER_DATA` - other data that is needed to properly process request of `TYPE`.
## Versions
Metricator's API currently supports API version 1.
## Handlers
### Get Metricator's build info
**URL**: `/api/vX/info`
Returns a JSON with build info with following items:
* `Branch` for git branch.
* `Build` for commit **number**.
* `CommitHash` for git commit hash.
* `Version` for tagged (or not tagged) build.
Caveats:
1. `Version` contains string formed with [Semantic Versioning](https://semver.org/spec/v2.0.0.html) in mind, so there is either "X.Y.Z" for tagged release or "X.Y.Z-dev` for development (built not from tag) release.
Example:
```json
{"Branch":"master","Build":"24","CommitHash":"095e24a2b0b908d790153a4ed0bee51d9dba7685","Version":"0.1.0-dev"}
```
### Get registered applications list
**URL**: `/api/vX/apps_list`
Returns a JSON with all known applications.
Example:
```json
["app1", "app2", "gw1", "gw2"]
```
### Get all known metrics for application
**URL**: `/api/vX/metrics/APP_NAME`
Where:
* `APP_NAME` is a name of registered application.
Example:
```json
[
{
"Name":"dnsdist_frontend_tcpgaveup/frontend:127.0.0.1:53/proto:TCP/thread:0",
"Description":"Amount of TCP connections terminated after too many attempts to get a connection to the backend",
"Type":"counter",
"Value":"0",
"Params":null
},
{
"Name":"dnsdist_frontend_queries/frontend:127.0.0.1:53/proto:UDP/thread:0",
"Description":"Amount of queries received by this frontend",
"Type":"counter",
"Value":"0",
"Params":null
},
{
"Name":"dnsdist_frontend_queries/frontend:127.0.0.1:53/proto:UDP/thread:0",
"Description":"Amount of queries received by this frontend",
"Type":"counter",
"Value":"53842",
"Params":null,
}
]
```
### Get single metric data
**URL**: `/api/vX/metrics/APP_NAME/METRIC_NAME`
Where:
* `APP_NAME` is a name of registered application.
* `METRIC_NAME` is a name of metric exposed by this application.

View File

@ -10,9 +10,13 @@ This page describes every configuration value.
| applications > APPNAME > headers > MAP | map | Headers which should be added to request. See example below. | | applications > APPNAME > headers > MAP | map | Headers which should be added to request. See example below. |
| applications > APPNAME > time_between_requests | string | time.Duration-compatible string which represents timeout between requests. | | applications > APPNAME > time_between_requests | string | time.Duration-compatible string which represents timeout between requests. |
Where:
* `APPNAME` is a custom name for application.
## Headers map example ## Headers map example
``` ```yaml
applications: applications:
example: example:
headers: headers:

View File

@ -16,13 +16,13 @@ Metricator instead acts like Prometheus itself from monitored software PoV: it p
Also Metricator "reformats" metric names and parameters to be more easily parsed if needed, so: Also Metricator "reformats" metric names and parameters to be more easily parsed if needed, so:
``` ```prometheus
dnsdist_frontend_responses{frontend="127.0.0.1:53",proto="UDP",thread="0"} dnsdist_frontend_responses{frontend="127.0.0.1:53",proto="UDP",thread="0"}
``` ```
became: became:
``` ```prometheus
dnsdist_frontend_responses/frontend:127.0.0.1:53/proto:UDP/thread:0 dnsdist_frontend_responses/frontend:127.0.0.1:53/proto:UDP/thread:0
``` ```
@ -30,3 +30,4 @@ dnsdist_frontend_responses/frontend:127.0.0.1:53/proto:UDP/thread:0
* [Installation](INSTALL.md) * [Installation](INSTALL.md)
* [Configuration](CONFIGURE.md) * [Configuration](CONFIGURE.md)
* [API](API.md)

View File

@ -12,7 +12,7 @@ This page describes all of them.
To run Metricator in Docker simply run: To run Metricator in Docker simply run:
``` ```bash
docker run -v $(pwd)/metricator.yaml:/config.yaml -p 8080:34421 registry.gitlab.pztrn.name/pztrn/metricator:latest docker run -v $(pwd)/metricator.yaml:/config.yaml -p 8080:34421 registry.gitlab.pztrn.name/pztrn/metricator:latest
``` ```
@ -20,7 +20,7 @@ Don't forget to create configuration file as described [here](CONFIGURE.md)!
### docker-compose ### docker-compose
``` ```docker-compose
version: "2.4" version: "2.4"
services: services: