Module systemd_journal_formatter

Formatter for systemd_journal_h.

Description

Formatter for systemd_journal_h.

This formatters formats data in the way that is digestible by the journald.

Options

fields :: [field_definition()]

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

Defaults to:

        [message,
         syslog_timestamp,
         syslog_pid,
         syslog_priority,
         {"ERL_PID", pid},
         {"CODE_FILE", file},
         {"CODE_LINE", line},
         {"CODE_MFA", mfa}]
See Fields below.
report_cb :: fun ((Prefix :: field_name(), 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 do not need to be in any encodig, it can even be binary.

Example

        my_formatter(Prefix, #{field := Field}) when is_integer(Field) ->
            [
             {[Prefix,"_FIELD"], io_lib:format("~.16B", [Field]}
            ].
Rememer that all field names MUST be uppercase and 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 user to the implementor to remember about it.
time_designator :: byte()

Timestamps are formatted according to RFC3339, and the time designator is the character used as date and time separator.

Defaults to $T.

The value of this parameter is used as the time_designator option to calendar:system_time_to_rfc3339/2.
time_offset :: integer() | [byte()]

The time offset, either a string or an integer, to be used when formatting the timestamp.

An empty string is interpreted as local time. The values "Z", "z" or 0 are interpreted as Universal Coordinated Time (UTC).

Strings, other than "Z", "z", or "", must be on the form ±[hh]:[mm], for example "-02:00" or "+00:00".

Integers must be in microseconds, meaning that the offset 7200000000 is equivalent to "+02:00".

Defaults to an "Z", meaning that timestamps are displayed in UTC.

The value of this parameter is used as the offset option to calendar:system_time_to_rfc3339/2.

Fields

Fields list contain definition of fields that will be presented in the log message feeded 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 and lists of atoms) in fields list will be sent to the journald as a uppercased atom names, and in case of lists, joined with underscores.

Entries in form of {Name :: field_name(), metakey()} will use Name as the field name. Name will be checked if it is correct journald field name (i.e. contains only uppercase 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.
msg and message
Log message.
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.

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_priority
Will work exactly the same as {"SYSLOG_PRIORITY", priority}.
syslog_pid
Will work exactly the same as {"SYSLOG_PID", os_pid}.
syslog_timestamp
Will work exactly the same as {"SYSLOG_TIMESTAMP", time}.
syslog_facility
Will work exactly the same as {"SYSLOG_FACILITY", facility}.
syslog_identifier
Will work exactly the same as {"SYSLOG_TIMESTAMP", identifier}.

Data Types

field()

field() = {field_name(), iolist()}

field_definition()

field_definition() = metakey() | {field_name(), metakey() | iolist()}

field_name()

field_name() = unicode:chardata()

metakey()

metakey() = atom() | [atom()]

Function Index

format_report/2 Default report formatter used for systemd_journal_formatter.

Function Details

format_report/2

format_report(Prefix::field_name(), Report::logger:report()) -> [field()]

Default report formatter used for systemd_journal_formatter. Output format will be similar to one provided by logger:format_report/1, but this one takes also additional parameter Perfix which should be used as prefix for all generated fields.

Introduced in: 0.3.0


Generated by EDoc