From b2127fd3492122311ea37bf3970eb263f0ab192f Mon Sep 17 00:00:00 2001 From: boyska Date: Sun, 11 Nov 2018 20:06:10 +0100 Subject: [PATCH] update readme to recent enhancements --- README.md | 56 ++++++++++++++++++++++++++++++++++++++----- cmd/circologd/main.go | 7 +----- 2 files changed, 51 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 3f3d6dd..8e79a89 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ A syslog daemon implementing circular buffer, in-memory storage. -This is useful when you want to keep some (heavy detailed) log available, but you don't want to log too many -things to disk. +This is useful when you want to keep some (heavily detailed) log available, but you don't want to log too many +things to disk. Remember: logging is useful, but can be dangerous to your users' privacy! -On your "main" syslog, send some message to this one! +On your "main" syslog, forward (part of the) messages to this one! ## Integration examples @@ -27,15 +27,59 @@ and run `circologd -syslogd-socket /run/circolog-syslog.sock -query-socket /run/ ## Client -`curl` might be enough of a client for most uses. +`circolog` has its own client: `circolog-tail`. It is intended to resemble `tail -f` for the most basic +options; however, it will include filtering options that are common when you want to read logs, because that's +very easy when you have structured logs available. + +However, one design point of circolog is to be usable without having a specific client: so the logs are +offered on both HTTP and websocket. This means that you can use `curl` if you want: curl --unix-socket /run/circolog-query.sock localhost/ -will give you everything that circologd has in memory +will give you everything that circologd has in memory. If you want to "follow" (as in `tail -f`) you need to use the websocket interface. However, I don't know of any websocket client supporting UNIX domain socket, so you have two options: - 1. wait until I write a proper `circolog-tail` client implementing it all + 1. Use `circolog-tail` 2. Use `circologd` with `-query-addr 127.0.0.1:9080`, add some iptables rule to prevent non-root to access that port, and run `ws ws://localhost:9080/ws`. You'll get all the "backlog", and will follow new log messages. + +### HTTP URLs and parameters + +When using HTTP, logs are served on `/`. Valid parameters are: + + * `l`. This is the amount of lines to send. This is essentially the same as the `-n` parameter on tail + Using `l=-1` (the default) means "give me every log message that you have + * `fmt`. This selects the output format. When `fmt=json` is used, each message is returned as JSON structured + data. The format of those JSON messages is still unstable. `fmt=syslog`, the default, outputs messages using "syslog style" (RFC XXXXXX) + +To use websocket, request path `/ws`. The same parameters of `/` are recognized. + +## Control daemon + +Circologd can be controlled, on some aspects, at run-time. It has 2 mechanisms for that: the easiest, and more +limited, is sending a signal with kill; the second, and more powerful, is a control socket, where you can give +commands to it. This control socket is just HTTP, so again `curl` is your friend. In the future a +`circolog-ctl` client will be developed. + +### Pause + +When circologd is paused, every new message it receives is immediately discarded. No exception. The backlog +is, however, preserved. This means that you can trigger the event that you want to investigate, pause +circolog, then analyze the logs. +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. + +### Clear + +When you clear the circologd's buffer, it will discard every message it has, but will keep collecting new +messages. + +You can do that with `POST /logs/clear` diff --git a/cmd/circologd/main.go b/cmd/circologd/main.go index 054b226..b40641c 100644 --- a/cmd/circologd/main.go +++ b/cmd/circologd/main.go @@ -32,7 +32,7 @@ func main() { flag.Parse() interrupt := make(chan os.Signal, 1) - signal.Notify(interrupt, syscall.SIGINT, syscall.SIGHUP, syscall.SIGUSR1, syscall.SIGTERM) + signal.Notify(interrupt, syscall.SIGINT, syscall.SIGUSR1, syscall.SIGTERM) hub := circolog.NewHub(*bufsize) handler := syslog.NewChannelHandler(hub.LogMessages) @@ -106,11 +106,6 @@ func main() { for { select { case sig := <-interrupt: - if sig == syscall.SIGHUP { - hub.Commands <- circolog.HubFullCommand{Command: circolog.CommandClear} - <-hub.Responses - log.Println("Queue cleared") - } if sig == syscall.SIGUSR1 { hub.Commands <- circolog.HubFullCommand{Command: circolog.CommandPauseToggle} resp := <-hub.Responses