From 6f638735910d606984dfefd8276282ab41eeaa72 Mon Sep 17 00:00:00 2001 From: boyska Date: Wed, 26 Dec 2018 02:21:15 +0100 Subject: [PATCH] filtering explained in README.md --- README.md | 32 ++++++++++++++++++++++++++++---- 1 file changed, 28 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 8e79a89..75da52a 100644 --- a/README.md +++ b/README.md @@ -72,10 +72,10 @@ Pausing might be the easiest way to make circologd only run "when needed". When circologd resumes, no previous message is lost. - -To pause circologd with signals , send a `USR1` signal to the main pid. To "resume", send a `USR1` again. - -To pause with HTTP, send a `POST /pause/toggle` to your circologd control socket. +To pause/unpause: + * `circologctl pause` + * `pkill -USR1 circologd` + * `POST /pause/toggle` to your circologd control socket ### Clear @@ -83,3 +83,27 @@ When you clear the circologd's buffer, it will discard every message it has, but messages. You can do that with `POST /logs/clear` + +### Filter + +circologd can drop irrelevant messages using filters. A filter is a sql-like expression (for the exact syntax +you can see [the doc for the underlying library](https://github.com/araddon/qlbridge/blob/master/FilterQL.md), +qlbridge), but just imitating sql where clauses can be enough! + +`circologctl filter message NOT LIKE '%usb%'` will discard everything related to usb. + +The filter will be applied to incoming messages, so messages mentioning usb will not be saved in memory at all. + +You can put zero or one filters at a time. That is, you can not stack more filters... but FilterQL syntax +supports `AND` operators, so this is not an issue. + +To remove filtering (thus accepting every message) run `circologctl filter` + +NOTE: `circolog-tail` supports filters with exactly the same syntax, but they are two different kinds of +filtering: one is server-side, the other is client-side. When you filter server-side with `circologctl +filter`, circologd will refuse messages not matching the filter. If you only filter with `circolog-tail`, the +message you are filtering out will still consume space in memory (and will be available to other clients). + +Filtering brings big dependencies, which will add some 5-6 megabytes to circolog binaries. If you want to +avoid it, install with `go install -tags nofilter git.lattuga.net/boyska/circolog/...` and your binaries will +be a bit smaller.