Overview

Ejournald: An Interface to systemd's journald

Copyright © Travelping GmbH <info@travelping.com>

Overview

Ejournald is an Erlang interface for systemd's journald. It provides advanced write and read support.

Using the I/O server

By default an I/O-server named ejournald_io_server is started together with ejournald. The log level (by default info) and other options are fixed for one I/O-server. Thus if you need other options (e.g. another log level) you need to start your own one. Note that the 'name' option (a string) is mandatory and you have to deliver a unique name for every server. This name will appear as a prefix in the journal.

Using the high level query API

Note that using the API requires you to start an 'ejournald_reader' on the journal of your interest. By default a reader is started on the standard journal. The API queries this reader for retrieving logs.

The high-level API for reading logs consists of the two function get_logs() and log_notify(). The first one will enable you to retrieve logs based on time-frames and other options. The latter one is intended to deliver new logs as they appear in the journal. Logs are always delivered in the form

    {Timestamp, LogLevel, LogData}

where Timestamp is of type calendar:datetime1970(), LogLevel is one of the eight journald log levels and LogData is a string or a list of strings. For example

    LastLogs = ejournald:get_logs([{at_most, 10}, {message, true}]),
    {ok, NotifyPid} = ejournald:log_notify(self(), [{message, true}]),
    flush(). % some new logs might appear here

is roughly equivalent to 'journalctl -f' giving you the last 10 logs in message-only format (just one string per log) and following the journal if new logs appear. Leaving the 'message'-option would give you whole logs (a list of strings per log). The 'Options' parameter is always intended to filter the choice of logs. Just ejournald:get_logs([ ]) would reproduce the whole journal. To restrict the time-frame for get_logs() you can use the options 'since' and 'until'. The order of logs is always destined by the 'direction'-option (by default 'descending' - from newest to oldest). Another example:

    Logs = ejournald:get_logs([{direction, ascending}, {since, {{2013,12,31},{12,0,0}} }]).

This gives you full logs in the order 'oldest to newest' since lunchtime of last silvester. Note that you must use UTC-time. If possible filtering should be done by ejournald since the used C-API in the background is much faster at handling this. You can use as many different log_notify()'s as you want at the same time. Different filters will be handled properly. A process handling new logs has the following layout:

    loop() ->
        receive 
            {'EXIT', FromPid, Reason} ->
                % end your process;
                % ejournald automatically links a worker process to your pid.
                % Thus if you end your process it will also end this worker.
            {Timestamp, LogLevel, LogData} ->
                % do something here
                loop();
            journal_invalidate ->
                % maybe a new journal file was appended, refresh your monitors!
                loop()
        end.

You can also provide a function for working on the logs. Both get_logs() and log_notify() support regular expressions (see 'regex' option) according to the erlang re module. It is possible to search only through the 'message' part of a log or to search every single field through.

The lager_journald_backend is capable of storing Erlang meta information in journald. These can also be used to filter logs by application or other data:

    Logs = ejournald:get_logs([{application, my_app}, {at_most, 5}]).

Overview

Generated by EDoc