systemd.journal module

systemd.journal.send(MESSAGE, MESSAGE_ID=None, CODE_FILE=None, CODE_LINE=None, CODE_FUNC=None, **kwargs)

Send a message to the journal.

>>> from systemd import journal
>>> journal.send('Hello world')
>>> journal.send('Hello, again, world', FIELD2='Greetings!')
>>> journal.send('Binary message', BINARY=b'\xde\xad\xbe\xef')

Value of the MESSAGE argument will be used for the MESSAGE= field. MESSAGE must be a string and will be sent as UTF-8 to the journal.

MESSAGE_ID can be given to uniquely identify the type of message. It must be a string or a uuid.UUID object.

CODE_LINE, CODE_FILE, and CODE_FUNC can be specified to identify the caller. Unless at least on of the three is given, values are extracted from the stack frame of the caller of send(). CODE_FILE and CODE_FUNC must be strings, CODE_LINE must be an integer.

Additional fields for the journal entry can only be specified as keyword arguments. The payload can be either a string or bytes. A string will be sent as UTF-8, and bytes will be sent as-is to the journal.

Other useful fields include PRIORITY, SYSLOG_FACILITY, SYSLOG_IDENTIFIER, SYSLOG_PID.

systemd.journal.sendv('FIELD=value', 'FIELD=value', ...) → None

Send an entry to the journal.

systemd.journal.stream(identifier=None, priority=6, level_prefix=False)

Return a file object wrapping a stream to journal.

Log messages written to this file as simple newline sepearted text strings are written to the journal.

The file will be line buffered, so messages are actually sent after a newline character is written.

>>> from systemd import journal
>>> stream = journal.stream('myapp')                       
>>> res = stream.write('message...\n')                     

will produce the following message in the journal:

PRIORITY=7
SYSLOG_IDENTIFIER=myapp
MESSAGE=message...

If identifier is None, a suitable default based on sys.argv[0] will be used.

This interface can be used conveniently with the print function:

>>> from __future__ import print_function
>>> stream = journal.stream()                              
>>> print('message...', file=stream)                       

priority is the syslog priority, one of LOG_EMERG, LOG_ALERT, LOG_CRIT, LOG_ERR, LOG_WARNING, LOG_NOTICE, LOG_INFO, LOG_DEBUG.

level_prefix is a boolean. If true, kernel-style log priority level prefixes (such as ‘<1>’) are interpreted. See sd-daemon(3) for more information.

systemd.journal.stream_fd(identifier, priority, level_prefix) → fd

Open a stream to journal by calling sd_journal_stream_fd(3).

JournalHandler class

class systemd.journal.JournalHandler(level=0, sender_function=<function send>, **kwargs)

Journal handler class for the Python logging framework.

Please see the Python logging module documentation for an overview: http://docs.python.org/library/logging.html.

To create a custom logger whose messages go only to journal:

>>> import logging
>>> log = logging.getLogger('custom_logger_name')
>>> log.propagate = False
>>> log.addHandler(JournalHandler())
>>> log.warning("Some message: %s", 'detail')

Note that by default, message levels INFO and DEBUG are ignored by the logging framework. To enable those log levels:

>>> log.setLevel(logging.DEBUG)

To redirect all logging messages to journal regardless of where they come from, attach it to the root logger:

>>> logging.root.addHandler(JournalHandler())

For more complex configurations when using dictConfig or fileConfig, specify systemd.journal.JournalHandler as the handler class. Only standard handler configuration options are supported: level, formatter, filters.

To attach journal MESSAGE_ID, an extra field is supported:

>>> import uuid
>>> mid = uuid.UUID('0123456789ABCDEF0123456789ABCDEF')
>>> log.warning("Message with ID", extra={'MESSAGE_ID': mid})

Fields to be attached to all messages sent through this handler can be specified as keyword arguments. This probably makes sense only for SYSLOG_IDENTIFIER and similar fields which are constant for the whole program:

>>> JournalHandler(SYSLOG_IDENTIFIER='my-cool-app')
<...JournalHandler ...>

The following journal fields will be sent: MESSAGE, PRIORITY, THREAD_NAME, CODE_FILE, CODE_LINE, CODE_FUNC, LOGGER (name as supplied to getLogger call), MESSAGE_ID (optional, see above), SYSLOG_IDENTIFIER (defaults to sys.argv[0]).

The function used to actually send messages can be overridden using the sender_function parameter.

Accessing the Journal

class systemd.journal._Reader([flags | path | files | namespace])

_Reader allows filtering and retrieval of Journal entries. Note: this is a low-level interface, and probably not what you want, use systemd.journal.Reader instead.

Argument flags sets open flags of the journal, which can be one of, or an ORed combination of constants: LOCAL_ONLY (default) opens journal on local machine only; RUNTIME_ONLY opens only volatile journal files; and SYSTEM opens journal files of system services and the kernel, CURRENT_USER opens files of the current user; and OS_ROOT is used to open the journal from directories relative to the specified directory path or file descriptor.

If namespace argument is specified, the specific journal namespace will be open (supported since systemd v245). Instead of opening the system journal, argument path may specify a directory which contains the journal. It maybe be either a file system path (a string), or a file descriptor (an integer). Alternatively, argument files may specify a list of journal file names. Note that flags, path, files, directory_fd, namespace are exclusive.

_Reader implements the context manager protocol: the journal will be closed when exiting the block.

add_conjunction() → None

Inserts a logical AND between matches added since previous add_disjunction() or add_conjunction() and the next add_disjunction() or add_conjunction().

See sd_journal_add_disjunction(3) for explanation.

add_disjunction() → None

Inserts a logical OR between matches added since previous add_disjunction() or add_conjunction() and the next add_disjunction() or add_conjunction().

See sd_journal_add_disjunction(3) for explanation.

add_match(match) → None

Add a match to filter journal log entries. All matches of different fields are combined with logical AND, and matches of the same field are automatically combined with logical OR. Match is a string of the form “FIELD=value”.

close() → None

Free resources allocated by this Reader object. This method invokes sd_journal_close(). See sd_journal_close(3).

closed

True iff journal is closed

data_threshold

Threshold for field size truncation in bytes.

Fields longer than this will be truncated to the threshold size. Defaults to 64Kb.

enumerate_fields(field) → a set of values

Return a set of field names appearing in the journal. See sd_journal_enumerate_fields(3).

fileno() → int

Get a file descriptor to poll for changes in the journal. This method invokes sd_journal_get_fd(). See sd_journal_get_fd(3).

When the file descriptor returned by this function is used a poll loop, .process() should be used to process events and reset the readability state of the file descriptor.

flush_matches() → None

Clear all current match filters.

get_catalog() → str

Retrieve a message catalog entry for the current journal entry. Will throw IndexError if the entry has no MESSAGE_ID and KeyError is the id is specified, but hasn’t been found in the catalog.

Wraps sd_journal_get_catalog(3).

get_events() → int

Returns a mask of poll() events to wait for on the file descriptor returned by .fileno().

See sd_journal_get_events(3) for further discussion.

get_timeout() → int or None

Returns a timeout value for usage in poll(), the time since the epoch of clock_gettime(2) in microseconds, or None if no timeout is necessary.

The return value must be converted to a relative timeout in milliseconds if it is to be used as an argument for poll(). See sd_journal_get_timeout(3) for further discussion.

get_timeout_ms() → int

Returns a timeout value suitable for usage in poll(), the value returned by .get_timeout() converted to relative ms, or -1 if no timeout is necessary.

get_usage() → int

Returns the total disk space currently used by journal files (in bytes). If SD_JOURNAL_LOCAL_ONLY was passed when opening the journal this value will only reflect the size of journal files of the local host, otherwise of all hosts.

This method invokes sd_journal_get_usage(). See sd_journal_get_usage(3).

has_persistent_files(str) → bool

Returns true if persistent journal files have been found.

See sd_journal_test_cursor(3).

has_runtime_files(str) → bool

Returns true if runtime journal files have been found.

See sd_journal_test_cursor(3).

process() -> state change (integer)

Process events and reset the readability state of the file descriptor returned by .fileno().

Will return constants: NOP if no change; APPEND if new entries have been added to the end of the journal; and INVALIDATE if journal files have been added or removed.

See sd_journal_process(3) for further discussion.

query_unique(field) → a set of values

Return a set of unique values appearing in journal for the given field. Note this does not respect any journal matches. See sd_journal_query_unique(3).

reliable_fd() → bool

Returns True iff the journal can be polled reliably. This method invokes sd_journal_reliable_fd(). See sd_journal_reliable_fd(3).

seek_cursor(cursor) → None

Seek to journal entry by given unique reference cursor.

seek_head() → None

Jump to the beginning of the journal. This method invokes sd_journal_seek_head(). See sd_journal_seek_head(3).

seek_monotonic(monotonic[, bootid]) → None

Seek to nearest matching journal entry to monotonic. Argument monotonic is an timestamp from boot in microseconds. Argument bootid is a string representing which boot the monotonic time is reference to. Defaults to current bootid.

seek_realtime(realtime) → None

Seek to nearest matching journal entry to realtime. Argument realtime in specified in seconds.

seek_tail() → None

Jump to the end of the journal. This method invokes sd_journal_seek_tail(). See sd_journal_seek_tail(3).

test_cursor(str) → bool

Test whether the cursor string matches current journal entry.

Wraps sd_journal_test_cursor(). See sd_journal_test_cursor(3).

wait([timeout]) -> state change (integer)

Wait for a change in the journal. Argument timeout specifies the maximum number of microseconds to wait before returning regardless of whether the journal has changed. If timeout is -1, then block forever.

Will return constants: NOP if no change; APPEND if new entries have been added to the end of the journal; and INVALIDATE if journal files have been added or removed.

See sd_journal_wait(3) for further discussion.

class systemd.journal.Reader(flags=None, path=None, files=None, converters=None, namespace=None)

Access systemd journal entries.

Entries are subject to filtering and limits, see add_match, this_boot, this_machine functions and the data_treshold attribute.

Note that in order to access the system journal, a non-root user must have the necessary privileges, see journalctl(1) for details. Unprivileged users can access only their own journal.

Example usage to print out all informational or higher level messages for systemd-udevd for this boot:

>>> from systemd import journal
>>> j = journal.Reader()
>>> j.this_boot()
>>> j.log_level(journal.LOG_INFO)
>>> j.add_match(_SYSTEMD_UNIT="systemd-udevd.service")
>>> for entry in j:                                 
...    print(entry['MESSAGE'])
starting version ...

See systemd.journal-fields(7) for more info on typical fields found in the journal.

__init__(flags=None, path=None, files=None, converters=None, namespace=None)

Create a new Reader.

Argument flags defines the open flags of the journal, which can be one of, or ORed combination of constants: LOCAL_ONLY (default) opens journal on local machine only; RUNTIME_ONLY opens only volatile journal files; and SYSTEM_ONLY opens only journal files of system services and the kernel.

Argument path is the directory of journal files, either a file system path or a file descriptor. Specify namespace to read from specific journal namespace. Note that flags, path, files and namespace are exclusive.

Argument converters is a dictionary which updates the DEFAULT_CONVERTERS to convert journal field values. Field names are used as keys into this dictionary. The values must be single argument functions, which take a bytes object and return a converted value. When there’s no entry for a field name, then the default UTF-8 decoding will be attempted. If the conversion fails with a ValueError, unconverted bytes object will be returned. (Note that ValueEror is a superclass of UnicodeDecodeError).

Reader implements the context manager protocol: the journal will be closed when exiting the block.

add_conjunction() → None

Inserts a logical AND between matches added since previous add_disjunction() or add_conjunction() and the next add_disjunction() or add_conjunction().

See sd_journal_add_disjunction(3) for explanation.

add_disjunction() → None

Inserts a logical OR between matches added since previous add_disjunction() or add_conjunction() and the next add_disjunction() or add_conjunction().

See sd_journal_add_disjunction(3) for explanation.

add_match(*args, **kwargs)

Add one or more matches to the filter journal log entries.

All matches of different field are combined with logical AND, and matches of the same field are automatically combined with logical OR. Matches can be passed as strings of form “FIELD=value”, or keyword arguments FIELD=”value”.

close() → None

Free resources allocated by this Reader object. This method invokes sd_journal_close(). See sd_journal_close(3).

closed

True iff journal is closed

data_threshold

Threshold for field size truncation in bytes.

Fields longer than this will be truncated to the threshold size. Defaults to 64Kb.

enumerate_fields(field) → a set of values

Return a set of field names appearing in the journal. See sd_journal_enumerate_fields(3).

fileno() → int

Get a file descriptor to poll for changes in the journal. This method invokes sd_journal_get_fd(). See sd_journal_get_fd(3).

When the file descriptor returned by this function is used a poll loop, .process() should be used to process events and reset the readability state of the file descriptor.

flush_matches() → None

Clear all current match filters.

get_catalog() → str

Retrieve a message catalog entry for the current journal entry. Will throw IndexError if the entry has no MESSAGE_ID and KeyError is the id is specified, but hasn’t been found in the catalog.

Wraps sd_journal_get_catalog(3).

get_end()

get_events() → int

Returns a mask of poll() events to wait for on the file descriptor returned by .fileno().

See sd_journal_get_events(3) for further discussion.

get_next(skip=1)

Return the next log entry as a dictionary.

Entries will be processed with converters specified during Reader creation.

Optional skip value will return the skip-th log entry.

Currently a standard dictionary of fields is returned, but in the future this might be changed to a different mapping type, so the calling code should not make assumptions about a specific type.

get_previous(skip=1)

Return the previous log entry.

Equivalent to get_next(-skip).

Optional skip value will return the -skip-th log entry.

Entries will be processed with converters specified during Reader creation.

Currently a standard dictionary of fields is returned, but in the future this might be changed to a different mapping type, so the calling code should not make assumptions about a specific type.

get_start()

get_timeout() → int or None

Returns a timeout value for usage in poll(), the time since the epoch of clock_gettime(2) in microseconds, or None if no timeout is necessary.

The return value must be converted to a relative timeout in milliseconds if it is to be used as an argument for poll(). See sd_journal_get_timeout(3) for further discussion.

get_timeout_ms() → int

Returns a timeout value suitable for usage in poll(), the value returned by .get_timeout() converted to relative ms, or -1 if no timeout is necessary.

get_usage() → int

Returns the total disk space currently used by journal files (in bytes). If SD_JOURNAL_LOCAL_ONLY was passed when opening the journal this value will only reflect the size of journal files of the local host, otherwise of all hosts.

This method invokes sd_journal_get_usage(). See sd_journal_get_usage(3).

has_persistent_files(str) → bool

Returns true if persistent journal files have been found.

See sd_journal_test_cursor(3).

has_runtime_files(str) → bool

Returns true if runtime journal files have been found.

See sd_journal_test_cursor(3).

log_level(level)

Set maximum log level by setting matches for PRIORITY.

messageid_match(messageid)

Add match for log entries with specified messageid.

messageid can be string of hexadicimal digits or a UUID instance. Standard message IDs can be found in systemd.id128.

Equivalent to add_match(MESSAGE_ID=`messageid`).

process() -> state change (integer)

Process events and reset the readability state of the file descriptor returned by .fileno().

Will return constants: NOP if no change; APPEND if new entries have been added to the end of the journal; and INVALIDATE if journal files have been added or removed.

See sd_journal_process(3) for further discussion.

query_unique(field)

Return a list of unique values appearing in the journal for the given field.

Note this does not respect any journal matches.

Entries will be processed with converters specified during Reader creation.

reliable_fd() → bool

Returns True iff the journal can be polled reliably. This method invokes sd_journal_reliable_fd(). See sd_journal_reliable_fd(3).

seek_cursor(cursor) → None

Seek to journal entry by given unique reference cursor.

seek_head() → None

Jump to the beginning of the journal. This method invokes sd_journal_seek_head(). See sd_journal_seek_head(3).

seek_monotonic(monotonic, bootid=None)

Seek to a matching journal entry nearest to monotonic time.

Argument monotonic is a timestamp from boot in either seconds or a datetime.timedelta instance. Argument bootid is a string or UUID representing which boot the monotonic time is reference to. Defaults to current bootid.

seek_realtime(realtime)

Seek to a matching journal entry nearest to timestamp time.

Argument realtime must be either an integer UNIX timestamp (in microseconds since the beginning of the UNIX epoch), or an float UNIX timestamp (in seconds since the beginning of the UNIX epoch), or a datetime.datetime instance. The integer form is deprecated.

>>> import time
>>> from systemd import journal

>>> yesterday = time.time() - 24 * 60**2
>>> j = journal.Reader()
>>> j.seek_realtime(yesterday)

seek_tail() → None

Jump to the end of the journal. This method invokes sd_journal_seek_tail(). See sd_journal_seek_tail(3).

test_cursor(str) → bool

Test whether the cursor string matches current journal entry.

Wraps sd_journal_test_cursor(). See sd_journal_test_cursor(3).

this_boot(bootid=None)

Add match for _BOOT_ID for current boot or the specified boot ID.

If specified, bootid should be either a UUID or a 32 digit hex number.

Equivalent to add_match(_BOOT_ID=’bootid’).

this_machine(machineid=None)

Add match for _MACHINE_ID equal to the ID of this machine.

If specified, machineid should be either a UUID or a 32 digit hex number.

Equivalent to add_match(_MACHINE_ID=’machineid’).

wait(timeout=None)

Wait for a change in the journal.

timeout is the maximum time in seconds to wait, or None which means to wait forever.

Returns one of NOP (no change), APPEND (new entries have been added to the end of the journal), or INVALIDATE (journal files have been added or removed).

systemd.journal._get_catalog()

get_catalog(id128) -> str

Retrieve a message catalog entry for the given id. Wraps sd_journal_get_catalog_for_message_id(3).

systemd.journal.get_catalog(mid)

Return catalog entry for the specified ID.

mid should be either a UUID or a 32 digit hex number.

class systemd.journal.Monotonic(iterable=(), /)

A tuple of (timestamp, bootid) for holding monotonic timestamps

journal.DEFAULT_CONVERTERS = {'CODE_LINE': <class 'int'>, 'COREDUMP': <class 'bytes'>, 'COREDUMP_GID': <class 'int'>, 'COREDUMP_PID': <class 'int'>, 'COREDUMP_SESSION': <class 'int'>, 'COREDUMP_SIGNAL': <class 'int'>, 'COREDUMP_TIMESTAMP': <function _convert_timestamp>, 'COREDUMP_UID': <class 'int'>, 'ERRNO': <class 'int'>, 'EXIT_STATUS': <class 'int'>, 'INITRD_USEC': <class 'int'>, 'KERNEL_USEC': <class 'int'>, 'LEADER': <class 'int'>, 'MESSAGE_ID': <function _convert_uuid>, 'PRIORITY': <class 'int'>, 'SESSION_ID': <class 'int'>, 'SYSLOG_FACILITY': <class 'int'>, 'SYSLOG_PID': <class 'int'>, 'USERSPACE_USEC': <class 'int'>, '_AUDIT_LOGINUID': <class 'int'>, '_AUDIT_SESSION': <class 'int'>, '_BOOT_ID': <function _convert_uuid>, '_GID': <class 'int'>, '_MACHINE_ID': <function _convert_uuid>, '_PID': <class 'int'>, '_SOURCE_MONOTONIC_TIMESTAMP': <function _convert_source_monotonic>, '_SOURCE_REALTIME_TIMESTAMP': <function _convert_timestamp>, '_SYSTEMD_OWNER_UID': <class 'int'>, '_SYSTEMD_SESSION': <class 'int'>, '_UID': <class 'int'>, '__CURSOR': <function _convert_trivial>, '__MONOTONIC_TIMESTAMP': <function _convert_monotonic>, '__REALTIME_TIMESTAMP': <function _convert_realtime>}

Example: polling for journal events

This example shows that journal events can be waited for (using e.g. poll). This makes it easy to integrate Reader in an external event loop:

>>> import select
>>> from systemd import journal
>>> j = journal.Reader()
>>> j.seek_tail()
>>> journal.send('testing 1,2,3')   # make sure we have something to read
>>> j.add_match('MESSAGE=testing 1,2,3')
>>> p = select.poll()
>>> p.register(j, j.get_events())
>>> p.poll()                        
[(3, 1)]
>>> j.get_next()                    
{'_AUDIT_LOGINUID': 1000,
 '_CAP_EFFECTIVE': '0',
 '_SELINUX_CONTEXT': 'unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023',
 '_GID': 1000,
 'CODE_LINE': 1,
 '_HOSTNAME': '...',
 '_SYSTEMD_SESSION': 52,
 '_SYSTEMD_OWNER_UID': 1000,
 'MESSAGE': 'testing 1,2,3',
 '__MONOTONIC_TIMESTAMP':
    journal.Monotonic(timestamp=datetime.timedelta(2, 76200, 811585),
                      bootid=UUID('958b7e26-df4c-453a-a0f9-a8406cb508f2')),
 'SYSLOG_IDENTIFIER': 'python3',
 '_UID': 1000,
 '_EXE': '/usr/bin/python3',
 '_PID': 7733,
 '_COMM': '...',
 'CODE_FUNC': '<module>',
 'CODE_FILE': '<doctest journal.rst[4]>',
 '_SOURCE_REALTIME_TIMESTAMP':
     datetime.datetime(2015, 9, 5, 13, 17, 4, 944355),
 '__CURSOR': 's=...',
 '_BOOT_ID': UUID('958b7e26-df4c-453a-a0f9-a8406cb508f2'),
 '_CMDLINE': '/usr/bin/python3 ...',
 '_MACHINE_ID': UUID('263bb31e-3e13-4062-9bdb-f1f4518999d2'),
 '_SYSTEMD_SLICE': 'user-1000.slice',
 '_AUDIT_SESSION': 52,
 '__REALTIME_TIMESTAMP': datetime.datetime(2015, 9, 5, 13, 17, 4, 945110),
 '_SYSTEMD_UNIT': 'session-52.scope',
 '_SYSTEMD_CGROUP': '/user.slice/user-1000.slice/session-52.scope',
 '_TRANSPORT': 'journal'}

Journal access types

journal.LOCAL_ONLY = 1

journal.RUNTIME_ONLY = 2

journal.SYSTEM = 4

journal.CURRENT_USER = 8

journal.OS_ROOT = 16

Journal event types

journal.NOP = 0

journal.APPEND = 1

journal.INVALIDATE = 2