Logger handler for sending messages to systemd's journal.

Usage

Run this after the systemd application is started:

  logger:add_handler(journal, systemd_journal_h, #{}).

Options

fields :: [field_definition()]

Contains list of all fields that will be passed to the journald.

Defaults to:

        [syslog_timestamp,
         syslog_pid,
         syslog_identifier,
         priority,
         {"ERL_PID", pid},
         {"CODE_FILE", file},
         {"CODE_LINE", line},
         {"CODE_MFA", mfa}]

See Fields below.

report_cb :: fun ((logger:report()) -> [field()]

Function that takes Prefix and Logger's report and returns list of 2-ary tuples where first one MUST contain only uppercase ASCII letters, digits and underscore characters, and must not start with underscore. Field name and second one is field value in form of iolist(). It is important to note that value can contain any data, and does not need to be in any encoding; it can even be binary.

Example

        my_formatter(Prefix, #{field := Field}) when is_integer(Field) ->
            [
             {[Prefix,"_FIELD"], io_lib:format("~.16B", [Field]}
            ].

Remember that all field names MUST NOT start with the underscore, otherwise journald can ignore them. Such behaviour is not enforced on data returned by report_cb and it is left up to the implementor to remember it.

Fields

Fields list contain definition of fields that will be presented in the log message fed into journald. Few of them have special meaning and you can see list of them in the systemd.journal-fields(7) manpage.

Metakeys (i.e. atoms) in fields list will be sent to the journald as a uppercased atom names.

Entries in form of {Name :: field_name(), logger_formatter:metakey()} will use Name as the field name. Name will be checked if it is correct journald field name (i.e. contains only ASCII letters, digits, and underscores, additionally do not start with underscore).

Entries in form of {Name :: field_name(), Data :: iolist()} will use Name as field name and will contain Data as a literal.

If entry data is empty or not set then it will be ommited in the output.

Special fields

Special fields availables:

level

Log level presented as string.

priority

Log level presented as decimal representation of syslog level.

os_pid

OS PID for current Erlang process. This is NOT Erlang PID.

mfa

Calling function presented in form Module:Function/Arity.

time

Timestamp of log message presented in RFC3339 format in UTC.

script_id

String in form of {Name} {Vsn} where Name and Vsn are replaced by 1st and 2nd value in tuple returned by init:script_id()

Otherwise field is treated as a entry key where key is equivalent of [key] and is used as a list of atoms to extract data from the metadata map.

Syslog compatibility

To provide better compatibility and user convinience:

syslog_pid

Will work exactly the same as {"SYSLOG_PID", os_pid}.

syslog_timestamp

Will work exactly the same as {"SYSLOG_TIMESTAMP", time}.

syslog_identifier

Will work exactly the saem as {"SYSLOG_IDENTIFIER", script_id}.