logger_streaming_backend v0.1.0 LoggerStreamingBackend
Logger
backend that streams logs over HTTP.
Installation
To use, add to mix.exs:
defp deps() do
[{:logger_streaming_backend, "~> 0.1"}]
end
and run mix deps.get
. Then add it as a :logger
backend — for example, in
config/config.exs
:
config :logger,
backends: [:console, LoggerStreamingBackend]
You’ll also need to add the http stream handler to your preferred webserver. A cowboy handler is provided, for cowboy 1.x. To use, it, add
{"/your/preferred/path", LoggerStreamingBackend.HttpStreamHandler, []},
to your cowboy routes.
Currently only cowboy 1.x is supported, as that’s what I use. If you’d like to add a handler for other versions of cowboy / other webservers / Plug middleware etc., please feel free to submit a pull request.
Configuration
LoggerStreamingBackend
supports the following configuration options:
:metadata
- (list of atoms) list of metadata to be attached to the reported message. Defaults to[]
. See theLogger
docs for list of builtins and details of how to use custom metadata.:separator
- (String) separates the key from value in the scope querystring param, e.g. in “file:foobar.ex”. Defaults to “:”, (since equals is already part of the querystring syntax).:default_level
- (atom) The log level to use if none is specified in the querystring params. Defalts to:debug
.:formatter
- (atom) Defaults toLoggerStreamingBackend.Html
. With HTML output, custom formats can be a lot more flexible than with plain text. To customise it, you can supply your own HTML formatter backend, that implements the same format() function.
To configure these (similarly in e.g. config/config.exs
):
config :logger, LoggerStreamingBackend,
metadata: [:module, :line, :some_custom_key]
The HttpStreamHandler supports the following options:
:additional_headers
(list of 2-tuples), if you’d like to add your own headers to the defaults:headers
(list of 2-tuples), to completely replace the defaults:basic
(tuple of username and password) to use basic auth on the log endpoint:req_filter
(tuple of fn : req -> bool, and msg to return on failure) for customisable auth
E.g.
{"/path", LoggerStreamingBackend.HttpStreamHandler, [
additional_headers: [{"X-Custom-Header", "foo"}],
basic: {"username", "password"}
]},
Note that log level (and the metadata filter feature) are not part of the configuration. This is because they’re passed as querystring params, so they can be different for each stream.
Usage
Visit the path you configured, with some querystring parameters: level
, and
scope
. The level
is a log level, the scope
is for setting a metadata
filter, of the form key:value
. For example, if you have some custom
metadata called “appid”, to only show logs for which that metadata has been
set and equals “foo”, you can do:
http://localhost:4000/log?level=debug&scope=appid:foo
Metadata values are matched as strings. Note that that means that if you want
all log lines from a specific mdoule, you need to specify the ‘expanded’
version of the module name atom. For example, MyApp.Foo
is really
:"Elixir.MyApp.Foo"
, so you should do:
http://localhost:4000/log?level=debug&scope=module:Elixir.MyApp.Foo
(Don’t forget, any metadata you want to filter on needs to have been
configured for the backend using config :logger, LoggerStreamingBackend,
metadata: [...]
.)
If the :logger
log level is higher than the level you request, it will
temporarily lower it, then raise it again when you close the stream. This
should all just work with multiple streams, with the level being set to the
lowest of any of the streams currently open.
Make sure you don’t have a compile_time_purge_level
set, or this won’t work
below that level, as all the logger calls below that level will have been
removed at compile time. If you have expensive debug-level logging, you may
wish to consider wrapping them in zero-arity fns — see the Logger
docs for
more information.