Skip to content

Commit 51e9ef7

Browse files
HofiOneHofiOne
authored
Add stats-exporter() doc (#188)
Added description of the new stats-exporter() and stats-exporter-dont-log() sources Doc of changes syslog-ng/syslog-ng#5262 Test build: https://hofione.github.io/syslog-ng.github.io/admin-guide/060_Sources/135_Prometheus/README Depends on #187
2 parents 06b9ccd + 785e624 commit 51e9ef7

File tree

6 files changed

+135
-2
lines changed

6 files changed

+135
-2
lines changed

‎_data/external_links.yml

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1112,6 +1112,11 @@ postgresql:
11121112
url: https://www.postgresql.org/docs/current/runtime-config-logging.html#RUNTIME-CONFIG-LOGGING-CSVLOG
11131113
title: [ "PostgreSQL" ]
11141114

1115+
prometheus-scraper:
1116+
id: prometheus-scraper
1117+
url: https://prometheus.io/docs/prometheus/latest/getting_started/#configure-prometheus-to-monitor-the-sample-targets
1118+
title: [ "/[Pp]rometheus [Ss]craper/" ]
1119+
11151120
qbittorrent:
11161121
id: qbittorrent
11171122
url: https://www.qbittorrent.org/

‎_data/link_aliases.yml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,9 @@ adm-about-glossary#bsd-syslog-protocol:
9999
adm-about-glossary#ietf-syslog-protocol:
100100
aliases: [ "IETF-syslog protocol", "IETF-syslog" ]
101101

102+
adm-src-stats-exporter:
103+
aliases: [ "stats-exporter-dont-log()" ]
104+
102105
adm-src-wild:
103106
aliases: [ "/wildcard-file(?:\\(\\))? source[s]?/" ]
104107

‎_data/navigation.yml

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -255,6 +255,11 @@ admin-guide-nav:
255255
subnav:
256256
- title: "snmptrap() source options"
257257
url: /admin-guide/060_Sources/150_snmptrap/000_snmptrap_options
258+
- title: "stats-exporter"
259+
url: /admin-guide/060_Sources/153_stats_exporter/README
260+
subnav:
261+
- title: "stats-exporter() source options"
262+
url: /admin-guide/060_Sources/153_stats_exporter/000_stats_exporter_source_options
258263
- title: "stdin"
259264
url: /admin-guide/060_Sources/155_stdin/README
260265
subnav:
@@ -302,6 +307,11 @@ admin-guide-nav:
302307
url: /admin-guide/060_Sources/220_unix-stream_unix-dgram/000_Unix_credentials
303308
- title: "unix-stream() and unix-dgram() source options"
304309
url: /admin-guide/060_Sources/220_unix-stream_unix-dgram/001_unixstream_source_options
310+
- title: "webhook"
311+
url: /admin-guide/060_Sources/240_webhook/README
312+
subnav:
313+
- title: "webhook() source options"
314+
url: /admin-guide/060_Sources/240_webhook/000_webhook_options
305315
- title: "Destinations"
306316
url: /admin-guide/070_Destinations/README
307317
subnav:

‎doc/_admin-guide/060_Sources/153_stats_exporter/000_stats_exporter_source_options.md

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
title: stats-exporter() source options
3+
id: adm-src--stats-exporter-opt
4+
description: >-
5+
The stats-exporter() sources directly can serve the output of syslog-ng-ctl stats and syslog-ng-ctl query to a HTTP Scraper. Unlike the stats-exporter-dont-log() that suppresses log messages from incoming scraper requests, the stats-exporter() logs the unparsed messages, storing incoming scraper HTTP requests in the MSG field.
6+
---
7+
8+
Technically, both sources are specialized versions of the network() source. See the network() source options for details.
9+
10+
>**NOTE:** A destination is not required for this source to work; the `stats-exporter()` sources will respond to the scraper regardless of whether a destination is present in the log path.
11+
{: .notice--info}
12+
13+
These drivers have the following additional options:
14+
15+
## stat-type()
16+
17+
|Accepted values:| query \| stats |
18+
|Default: | stats |
19+
20+
*Description:* The stat type you wish to provide in the response to a HTTP Scraper request, just like for the syslog-ng-ctl command line tool.
21+
22+
## stat-query()
23+
24+
|Accepted values:| regular expression |
25+
|Default: | |
26+
27+
*Description:* The query regex string that can be used to filter the output of a `query` type request.
28+
29+
## stat-format()
30+
31+
|Accepted values:| csv \| kv \| prometheus |
32+
|Default: | prometheus |
33+
34+
*Description:* Specifies the format of the statistics output in HTTP responses, similar to the options available in syslog-ng-ctl. The available formats are:
35+
36+
- csv – comma-separated values format
37+
- kv – key-value pairs, one per line
38+
- prometheus – Prometheus-compatible exposition format
39+
40+
## scrape-pattern()
41+
42+
|Accepted values:| regular expression |
43+
|Default: | GET /metrics* |
44+
45+
*Description:* The pattern used to match the HTTP header of incoming scraping requests. A stat response will be generated and sent only if the header matches the scrape-pattern().
46+
47+
## scrape-freq-limit()
48+
49+
|Accepted values:| number |
50+
|Default: | 0 |
51+
52+
*Description:* Limits the frequency of repeated scraper requests to the specified number of seconds. Any repeated request within this period will be ignored. A value of 0 means no limit.
53+
54+
## single-instance()
55+
56+
|Accepted values:| yes \| no |
57+
|Default: | no |
58+
59+
*Description:* If set to `yes` only one scraper connection and request will be allowed at once.

‎doc/_admin-guide/060_Sources/153_stats_exporter/README.md

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
title: 'stats-exporter: Providing various statistics information to a HTTP Scraper'
3+
short_title: stats-exporter
4+
id: adm-src-stats-exporter
5+
description: >-
6+
The stats-exporter() and stats-exporter-dont-log() sources can directly serve the output of
7+
syslog-ng-ctl stats and syslog-ng-ctl query to an HTTP scraper, such as Prometheus.
8+
---
9+
10+
Example usage for a Prometheus Scraper which logs the HTTP request of the scraper to /var/log/scraper.log:
11+
12+
``` config
13+
@version: 4.9
14+
@include "scl.conf"
15+
16+
source s_prometheus_stat {
17+
stats-exporter(
18+
ip("0.0.0.0")
19+
port(8080)
20+
stat-type("query")
21+
stat-query("*")
22+
scrape-freq-limit(30)
23+
single-instance(yes)
24+
);
25+
};
26+
27+
log {
28+
source(s_prometheus_stat);
29+
destination { file(/var/log/scraper.log); };
30+
};
31+
```
32+
33+
Example usage for a generic HTTP Scraper which sends e.g. the `GET /stats HTTP/1.1` HTTP request to get statistics of {{ site.product.short_name }}, do not want to log or further process the HTTP requests in the log pipe, and needs the response in CSV format:
34+
35+
``` config
36+
@version: 4.9
37+
@include "scl.conf"
38+
39+
source s_scraper_stat {
40+
stats-exporter-dont-log(
41+
ip("0.0.0.0")
42+
port(8080)
43+
stat-type("stats")
44+
stat-format("csv")
45+
scrape-pattern("GET /stats*")
46+
scrape-freq-limit(30)
47+
single-instance(yes)
48+
);
49+
};
50+
51+
log {
52+
source(s_scraper_stat);
53+
};
54+
```
55+
56+
>**NOTE:** A destination is not required for this to work; the `stats-exporter()` sources will respond to the scraper regardless of whether a destination is present in the log path.
57+
{: .notice--info}

‎doc/_admin-guide/150_Statistics_of_syslog-ng/README.md

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,7 @@ description: >-
1212

1313
## Recommended: Structured, selective methods
1414

15-
- Using the syslog-ng-ctl
16-
query command.
15+
- Using the syslog-ng-ctl query command.
1716

1817
For further information about using syslog-ng-ctl commands, see
1918
The {{ site.product.short_name }} manual pages.

0 commit comments

Comments
 (0)