Index · Directives · Python · libudev · gudev systemd 216

systemd.journal module

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

Send a message to the 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, priority=7, level_prefix=False)[source]

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.

>>> stream = journal.stream('myapp')
>>> stream
<open file '<fdopen>', mode 'w' at 0x...>
>>> stream.write('message...\n')

will produce the following message in the journal:

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

Using the interface with print might be more convinient:

>>> from __future__ import print_function
>>> 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, **kwargs)[source]

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:

>>> log = logging.getLogger('custom_logger_name')
>>> log.propagate = False
>>> log.addHandler(journal.JournalHandler())
>>> log.warn("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(journal.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.warn("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:

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

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]).

Accessing the Journal

class systemd.journal._Reader

_Reader([flags | path | files]) -> ...

_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 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, and CURRENT_USER opens files of the current user.

Argument path is the directory of journal files. Argument files is a list of files. Note that flags, path, and files 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 man: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 man: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 man: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.

fileno() → int

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

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 man: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 man: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 man: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 man:sd_journal_get_usage(3).

process() -> state change (integer)

Process events and reset the readable 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 man: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.

reliable_fd() → bool

Returns True iff the journal can be polled reliably. This method invokes sd_journal_reliable_fd(). See man: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 man: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 man:sd_journal_seek_tail(3).

test_cursor(str) → bool

Test whether the cursor string matches current journal entry.

Wraps sd_journal_test_cursor(). See man: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 wheter 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 man:sd_journal_wait(3) for further discussion.

class systemd.journal.Reader(flags=0, path=None, files=None, converters=None)[source]

Reader allows the access and filtering of systemd journal entries. Note that in order to access the system journal, a non-root user must be in the systemd-journal group.

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

>>> 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'])

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

__init__(flags=0, path=None, files=None, converters=None)[source]

Create an instance of Reader, which allows filtering and return of journal entries.

Argument flags sets 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. Note that flags and path 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 man: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 man:sd_journal_add_disjunction(3) for explanation.

add_match(self, *args, **kwargs)[source]

Add one or more matches to the filter journal log entries. All matches of different field are combined in a logical AND, and matches of the same field are automatically combined in a 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 man: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.

fileno() → int

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

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 man: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 man:sd_journal_get_events(3) for further discussion.

get_next(self, skip=1)[source]

Return the next log entry as a mapping type, currently a standard dictionary of fields.

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

Entries will be processed with converters specified during Reader creation.

get_previous(self, skip=1)[source]

Return the previous log entry as a mapping type, currently a standard dictionary of fields.

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

Entries will be processed with converters specified during Reader creation.

Equivalent to get_next(-skip).

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 man: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 man:sd_journal_get_usage(3).

log_level(self, level)[source]

Set maximum log level by setting matches for PRIORITY.

messageid_match(self, messageid)[source]

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 readable 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 man:sd_journal_process(3) for further discussion.

query_unique(self, field)[source]

Return unique values appearing in the journal for 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 man: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 man:sd_journal_seek_head(3).

seek_monotonic(self, monotonic, bootid=None)[source]

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(self, realtime)[source]

Seek to a matching journal entry nearest to realtime time.

Argument realtime must be either an integer unix timestamp or datetime.datetime instance.

seek_tail() → None

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

test_cursor(str) → bool

Test whether the cursor string matches current journal entry.

Wraps sd_journal_test_cursor(). See man:sd_journal_test_cursor(3).

this_boot(self, bootid=None)[source]

Add match for _BOOT_ID equal to current boot ID 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(self, machineid=None)[source]

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(self, timeout=None)[source]

Wait for a change in the journal. timeout is the maximum time in seconds to wait, or None, 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 man:sd_journal_get_catalog_for_message_id(3).

systemd.journal.get_catalog(mid)[source]
class systemd.journal.Monotonic

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

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

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()
>>> p = select.poll()
>>> p.register(j, j.get_events())
>>> p.poll()
[(3, 1)]
>>> j.get_next()

Journal access types

journal.LOCAL_ONLY = 1
journal.RUNTIME_ONLY = 2
journal.SYSTEM = 4
journal.CURRENT_USER = 8

Journal event types

journal.NOP = 0
journal.APPEND = 1
journal.INVALIDATE = 2