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.
Send an entry to the journal.
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...
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.
Open a stream to journal by calling sd_journal_stream_fd(3).
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.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(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:
>>> JournalHandler(SYSLOG_IDENTIFIER='my-cool-app')
<systemd.journal.JournalHandler object at ...>
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]).
_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.
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.
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 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”.
Free resources allocated by this Reader object. This method invokes sd_journal_close(). See man:sd_journal_close(3).
True iff journal is closed
Threshold for field size truncation in bytes.
Fields longer than this will be truncated to the threshold size. Defaults to 64Kb.
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).
Clear all current match filters.
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).
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.
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.
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.
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 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.
Return a set of unique values appearing in journal for the given field. Note this does not respect any journal matches.
Returns True iff the journal can be polled reliably. This method invokes sd_journal_reliable_fd(). See man:sd_journal_reliable_fd(3).
Seek to journal entry by given unique reference cursor.
Jump to the beginning of the journal. This method invokes sd_journal_seek_head(). See man:sd_journal_seek_head(3).
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 to nearest matching journal entry to realtime. Argument realtime in specified in seconds.
Jump to the end of the journal. This method invokes sd_journal_seek_tail(). See man:sd_journal_seek_tail(3).
Test whether the cursor string matches current journal entry.
Wraps sd_journal_test_cursor(). See man:sd_journal_test_cursor(3).
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.
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:
>>> 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.
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.
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.
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 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”.
Free resources allocated by this Reader object. This method invokes sd_journal_close(). See man:sd_journal_close(3).
True iff journal is closed
Threshold for field size truncation in bytes.
Fields longer than this will be truncated to the threshold size. Defaults to 64Kb.
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).
Clear all current match filters.
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).
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.
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.
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).
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.
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.
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).
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 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.
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.
Returns True iff the journal can be polled reliably. This method invokes sd_journal_reliable_fd(). See man:sd_journal_reliable_fd(3).
Seek to journal entry by given unique reference cursor.
Jump to the beginning of the journal. This method invokes sd_journal_seek_head(). See man:sd_journal_seek_head(3).
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 to a matching journal entry nearest to realtime time.
Argument realtime must be either an integer unix timestamp or datetime.datetime instance.
Jump to the end of the journal. This method invokes sd_journal_seek_tail(). See man:sd_journal_seek_tail(3).
Test whether the cursor string matches current journal entry.
Wraps sd_journal_test_cursor(). See man:sd_journal_test_cursor(3).
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’).
get_catalog(id128) -> str
Retrieve a message catalog entry for the given id. Wraps man:sd_journal_get_catalog_for_message_id(3).
A tuple of (timestamp, bootid) for holding monotonic timestamps
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'}