README.md

logger_journald
===============

OTP [logger](http://erlang.org/doc/apps/kernel/logger_chapter.html) backend that sends log
events to Systemd's journald service.
Pure Erlang implementation (no C dependencies).

Usage
-----

Add to your `rebar.config`

```erlang
{deps, [logger_journald]}.
```

to your `sys.config`

```erlang
{kernel, [
    {logger, [
        {handler, my_handler, logger_journald_h, #{
            level => info,
            config => #{
              socket_path => "/run/systemd/journal/socket",  % optional
              defaults => #{"MY_KEY" => "My value",          % optional
                            "SYSLOG_IDENTIFIER" => my_release}
            }
        }}
    ]}
]}
```

or do this somewhere in your code

```erlang
logger:add_handler(my_handler, logger_journald_h,
                   #{config => #{defaults => #{"SYSLOG_IDENTIFIER" => my_release}}}).
```

I'd recommend to add at least one key to `defaults` to uniquely identify your application. The
recommended key name for that is `SYSLOG_IDENTIFIER`.

Other `logger:handler_config()` options (`level`, `filters`) should also work, but not
`formatter`, because format of `journald` packet is restricted.

Then start your app and send some logs. They can be seen, eg, like this (see `man journalctl`):

```bash
$ journalctl -f -o verbose _COMM=beam.smp SYSLOG_IDENTIFIER=my_release
```

Multiple instances of `logger_journald_h` handler can be started.

It's not currently possible to set `logger_journald_h` as `default` handler via `sys.config`,
because `sys.config` is applied at `kernel` application start time and `logger_journald`
application depends on `kernel` application (sort of cyclic dependency). However, disabling
`default` handler and installing just `logger_journald_d` works fine (but you might miss some
of early start-up related logs)
`[{handler, default, undefined}, {handler, my_handler, logger_journald_d, #{}}]`.

There is also [journald_sock](src/journald_sock.erl) module available, which provides a thin wrapper
with limited API for journald's control socket.

How it works?
-------------

When `logger_journald` application is started, it creates an empty supervisor.
When `logger:add_handler/3` is called, `logger_journald` starts a new `gen_server` under
this supervisor, which holds open `gen_udp` UNIX-socket open to journald and some internal state.

When you call `logger:log` (or use `?LOG*` macro), your log message is converted to be a flat
key-value structure in the same process where `log` is called and then sent to this `gen_server`,
which writes it to journld's socket via `gen_udp`.

Be careful! All the log messages targeting one handler are sent through the single gen_server!
There is no backpressure support at the moment!

The way [logger:log_event()](http://erlang.org/doc/man/logger.html#type-log_event) is converted
to a journald flat key-value structure is following:

* `msg` is sent as `MESSAGE` field
  * If `msg` is a `{report, logger:report()}`, then it is converted to a string with
    `logger:report_cb()` function provided in `meta`.
  * If `msg` is `{io:format(), [any()]}`, it is converted to a string with `io_lib:format/2`
* `level` is converted to syslog's numerical value between 0 ("emergency") and 7 ("debug") and is
  sent as `PRIORITY` field
* `meta` fields are encoded in a following way
  * `file`, `line` and `mfa` are encoded as `CODE_FILE`, `CODE_LINE` and `CODE_FUNC` (in
    `Module:Function/Arity` form)
  * `time` is encoded in RFC-3339 format and sent as `SYSLOG_TIMESTAMP` field
  * `pid` is encoded as a string and sent as `ERL_PID` field
  * `gl` is encoded the same as `pid` and sent as `ERL_GROUP_LEADER`
  * `domain` is encoded as dot-separated string (eg `[otp, sasl]` -> `otp.sasl`) and sent as
    `ERL_DOMAIN`
  * all the custom metadata field names are converted to uppercase string and values are formatted
    with `io_lib:format("~p", [Value])`

Encoder works quite well with iolists / iodata values (they are sent as is), but it's slightly
more optimized for a binary values.

Development
-----------

Please, run the following before committing

```
rebar3 as dev fmt
rebar3 as dev lint
rebar3 eunit
rebar3 edoc
rebar3 dialyzer
```