From 6f623f9a96400eebbb3a7a61913314d7fa1327b6 Mon Sep 17 00:00:00 2001 From: erenJag <64777133+erenJag@users.noreply.github.com> Date: Wed, 29 Jul 2020 15:57:33 +0200 Subject: [PATCH] Update doc : metrics (#158) * update metrics documentation Co-authored-by: erenJag --- docs/getting_started/crowdsec-tour.md | 2 +- docs/guide/crowdsec/acquisition.md | 2 +- .../{metrics.md => command_line.md} | 61 +--------------- docs/observability/overview.md | 4 +- docs/observability/prometheus.md | 73 +++++++++++++++++++ mkdocs.yml | 7 +- 6 files changed, 85 insertions(+), 64 deletions(-) rename docs/observability/{metrics.md => command_line.md} (62%) create mode 100644 docs/observability/prometheus.md diff --git a/docs/getting_started/crowdsec-tour.md b/docs/getting_started/crowdsec-tour.md index 5be76b0e5..5f5a13445 100644 --- a/docs/getting_started/crowdsec-tour.md +++ b/docs/getting_started/crowdsec-tour.md @@ -12,7 +12,7 @@ A collection can be installed by typing `cscli install collection crowdsecurity/ In the same spirit, the [crowdsecurity/sshd](https://hub.crowdsec.net/author/crowdsecurity/collections/sshd)'s collection will fit most sshd setups ! -While {{crowdsec.name}} is running, a quick look at [`cscli metrics`](/observability/metrics/) should help you ensure that your log sources are correctly parsed. +While {{crowdsec.name}} is running, a quick look at [`cscli metrics`](/observability/command_line/) should help you ensure that your log sources are correctly parsed. ## List installed configurations diff --git a/docs/guide/crowdsec/acquisition.md b/docs/guide/crowdsec/acquisition.md index 11e66f76e..b7d728d78 100644 --- a/docs/guide/crowdsec/acquisition.md +++ b/docs/guide/crowdsec/acquisition.md @@ -78,6 +78,6 @@ INFO[0000] Acquisition Metrics: !!! info - All these metrics are actually coming from {{crowdsec.name}}'s prometheus agent. See [prometheus](/observability/metrics/) directly for more insights. + All these metrics are actually coming from {{crowdsec.name}}'s prometheus agent. See [prometheus](/observability/prometheus/) directly for more insights. diff --git a/docs/observability/metrics.md b/docs/observability/command_line.md similarity index 62% rename from docs/observability/metrics.md rename to docs/observability/command_line.md index 0cbafbb0d..f775f7371 100644 --- a/docs/observability/metrics.md +++ b/docs/observability/command_line.md @@ -1,11 +1,8 @@ - -## metrics via {{cli.name}} - ```bash {{cli.name}} metrics ``` -This command provides an overview of {{crowdsec.name}} statistics. By default it assumes that the {{crowdsec.name}} is installed on the same machine. +This command provides an overview of {{crowdsec.name}} statistics provided by [prometheus client](/observability/prometheus/). By default it assumes that the {{crowdsec.name}} is installed on the same machine. The metrics are split in 3 main sections : @@ -61,58 +58,4 @@ INFO[0000] Parser Metrics: +--------------------------------+--------+--------+----------+ ``` - - - -## metrics via {{crowdsec.name}} prometheus - -{{crowdsec.name}} can expose a prometheus endpoint for collection (on `http://127.0.0.1:6060/metrics` by default). - -The goal of this endpoint, besides the usual resources consumption monitoring, aims at offering a view of {{crowdsec.name}} "applicative" behavior : - - - is it processing a lot of logs ? is it parsing them successfully ? - - are a lot of scenarios being triggered ? - - are a lot of IPs banned ? - - etc. - -All the counters are "since {{crowdsec.name}} start". - -### Scenarios - - - `cs_bucket_created_total` : number of instantiation of each scenario - - `cs_bucket_overflowed_total` : number of overflow of each scenario - - `cs_bucket_underflowed_total` : number of underflow of each scenario (bucket was created but expired because of lack of events) - - `cs_bucket_poured_total` : number of event poured to each scenario with source as complementary key : - -``` -#2030 lines from `/var/log/nginx/access.log` were poured to `crowdsecurity/http-scan-uniques_404` scenario -cs_bucket_poured_total{name="crowdsecurity/http-scan-uniques_404",source="/var/log/nginx/access.log"} 2030 -``` - - -### Parsers - - `cs_node_hits_total` : how many time an event from a specific source was processed by a parser node : - -``` -# 235 lines from `auth.log` were processed by the `crowdsecurity/dateparse-enrich` parser -cs_node_hits_total{name="crowdsecurity/dateparse-enrich",source="/var/log/auth.log"} 235 -``` - - - `cs_node_hits_ko_total` : how many times an event from a specific was unsuccessfully parsed by a specific parser - -``` -# 2112 lines from `error.log` failed to be parsed by `crowdsecurity/http-logs` -cs_node_hits_ko_total{name="crowdsecurity/http-logs",source="/var/log/nginx/error.log"} 2112 -``` - - - `cs_node_hits_ok_total` : how many times an event from a specific source was successfully parsed by a specific parser - - - `cs_parser_hits_total` : how many times an event from a source has hit the parser - - `cs_parser_hits_ok_total` : how many times an event from a source was successfully parsed - - `cs_parser_hits_ko_total` : how many times an event from a source was unsuccessfully parsed - - -### Acquisition - - - `cs_reader_hits_total` : how many events were read from a specific source - + \ No newline at end of file diff --git a/docs/observability/overview.md b/docs/observability/overview.md index 194a09e11..9abed3188 100644 --- a/docs/observability/overview.md +++ b/docs/observability/overview.md @@ -4,8 +4,8 @@ Observability in security software is crucial, especially when this software mig We attempt to provide good observability of {{crowdsec.name}}'s behavior : - - {{crowdsec.name}} itself exposes a [prometheus instrumentation](/observability/metrics/#metrics-via-crowdsec-prometheus) - - {{cli.Name}} allows you to view part of prometheus metrics in [cli (`{{cli.bin}} metrics`)](/observability/metrics/) + - {{crowdsec.name}} itself exposes a [prometheus instrumentation](/observability/prometheus/) + - {{cli.Name}} allows you to view part of prometheus metrics in [cli (`{{cli.bin}} metrics`)](/observability/command_line/) - {{crowdsec.name}} logging is contextualized for easy processing - for **humans**, {{cli.name}} allows you to trivially start a service [exposing dashboards](/observability/dashboard/) (using [metabase](https://www.metabase.com/)) diff --git a/docs/observability/prometheus.md b/docs/observability/prometheus.md new file mode 100644 index 000000000..dcd384d22 --- /dev/null +++ b/docs/observability/prometheus.md @@ -0,0 +1,73 @@ +{{crowdsec.name}} can expose a {{prometheus.htmlname}} endpoint for collection (on `http://127.0.0.1:6060/metrics` by default). + +The goal of this endpoint, besides the usual resources consumption monitoring, aims at offering a view of {{crowdsec.name}} "applicative" behavior : + + - is it processing a lot of logs ? is it parsing them successfully ? + - are a lot of scenarios being triggered ? + - are a lot of IPs banned ? + - etc. + +All the counters are "since {{crowdsec.name}} start". + +### Scenarios + + - `cs_buckets` : number of scenario that currently exist + - `cs_bucket_created_total` : total number of instantiation of each scenario + - `cs_bucket_overflowed_total` : total number of overflow of each scenario + - `cs_bucket_underflowed_total` : total number of underflow of each scenario (bucket was created but expired because of lack of events) + - `cs_bucket_poured_total` : total number of event poured to each scenario with source as complementary key + +
+ example + + +``` +#2030 lines from `/var/log/nginx/access.log` were poured to `crowdsecurity/http-scan-uniques_404` scenario +cs_bucket_poured_total{name="crowdsecurity/http-scan-uniques_404",source="/var/log/nginx/access.log"} 2030 +``` + +
+ + +### Parsers + - `cs_node_hits_total` : how many time an event from a specific source was processed by a parser node : + + +
+ example + + +``` +# 235 lines from `auth.log` were processed by the `crowdsecurity/dateparse-enrich` parser +cs_node_hits_total{name="crowdsecurity/dateparse-enrich",source="/var/log/auth.log"} 235 +``` + +
+ + - `cs_node_hits_ko_total` : how many times an event from a specific was unsuccessfully parsed by a specific parser + +
+ example + + +``` +# 2112 lines from `error.log` failed to be parsed by `crowdsecurity/http-logs` +cs_node_hits_ko_total{name="crowdsecurity/http-logs",source="/var/log/nginx/error.log"} 2112 +``` + +
+ + - `cs_node_hits_ok_total` : how many times an event from a specific source was successfully parsed by a specific parser + + - `cs_parser_hits_total` : how many times an event from a source has hit the parser + - `cs_parser_hits_ok_total` : how many times an event from a source was successfully parsed + - `cs_parser_hits_ko_total` : how many times an event from a source was unsuccessfully parsed + + +### Acquisition + + - `cs_reader_hits_total` : how many events were read from a specific source + +### Info + + - `cs_info` : Information about {{crowdsec.name}} (software version) \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 520d1ec0e..36a8b02f6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -22,7 +22,9 @@ nav: - Observability: - Overview: observability/overview.md - Logs: observability/logs.md - - Metrics: observability/metrics.md + - Metrics: + - Prometheus: observability/prometheus.md + - Command line: observability/command_line.md - Dashboard: observability/dashboard.md - References: - Parsers format: references/parsers.md @@ -248,6 +250,9 @@ extra: Name: Duration htmlname: "[duration](/references/scenarios/#duration)" Htmlname: "[Duration](/references/scenarios/#duration)" + prometheus: + name: prometheus + htmlname: "[prometheus](https://github.com/prometheus/client_golang)" api: name: API htmlname: "[API](TBD)"