API Reference

Standard send function

journald_send.send(message: str, /, *, priority: Priority | None = None, code_file: str | None = None, code_line: int | None = None, code_func: str | None = None, **kwargs: object) → None[source]

Send a message to journald.

Parameters:

  • message – The log message (MESSAGE field).

  • priority – Log priority level (0–7).

  • code_file – Source file (CODE_FILE field).

  • code_line – Source line (CODE_LINE field).

  • code_func – Function name (CODE_FUNC field).

  • kwargs – Additional fields to include in the journal entry. Field names are uppercased and sanitized per journald conventions. Values are converted to strings. CODE_LINE must be an integer, MESSAGE_ID must be a string or uuid.UUID.

When both an explicit parameter and the corresponding keyword argument (e.g. priority vs PRIORITY) are given, the explicit parameter takes precedence. When the explicit parameter is None, the value from kwargs is used as a fallback.

Raises:

  • OSError – If not on Linux or if sending to journald fails.

  • ValueError – If priority (or PRIORITY in kwargs) is out of range, code_line (or CODE_LINE in kwargs) is not an integer, or MESSAGE_ID in kwargs is not a string or uuid.UUID.

Example:

import journald_send
from journald_send import Priority

journald_send.send('Hello World', priority=Priority.INFO, MY_FIELD='custom')

Compliant send function

journald_send.send_compliant(message: str, /, entries: Sequence[tuple[str, str | bytes]]) → None[source]

Send a compliant message to journald.

This function accepts a message and a list of key-value tuples, allowing for repeated keys, which is compliant with the journald native protocol.

Parameters:

  • message – The log message (MESSAGE field). Required.

  • entries – A list of (key, value) tuples. Keys will be normalized to uppercase. The MESSAGE key, if present, is ignored (use the message parameter instead).

Raises:

OSError – If not on Linux or if sending to journald fails.

Example:

import journald_send
journald_send.send_compliant('Hello World', [
    ('PRIORITY', '6'),
    ('MY_FIELD', b'custom'),
])

The send_compliant function accepts a message and a sequence of key-value tuples, allowing for repeated keys, which is compliant with the journald native protocol. Keys are automatically sanitized and converted to uppercase. The MESSAGE key in entries is ignored (use the message parameter instead). Values can be str (encoded to UTF-8) or bytes.

This function may differ from common Python usage patterns.

import journald_send
journald_send.send_compliant('Hello World', (
    ('PRIORITY', b'6'),
    ('CUSTOM_FIELD', b'custom value'),
))

Standard fields

The following standard journald fields are supported:

  • MESSAGE: The log message (required)

  • MESSAGE_ID: Optional message identifier

  • CODE_FILE: Optional source file path

  • CODE_LINE: Optional source line number

  • CODE_FUNC: Optional function name

Custom fields

Any additional keyword arguments are treated as custom journald fields. Field names are automatically sanitized and converted to uppercase.

import journald_send
journald_send.send(
    'Custom log entry',
    CUSTOM_FIELD='value',
    ANOTHER_FIELD=123
)

Priority enum

class journald_send.Priority(*values)[source]

Integer enum representing journald priority levels.

EMERGENCY = 0
ALERT = 1
CRITICAL = 2
ERROR = 3
WARNING = 4
NOTICE = 5
INFO = 6
DEBUG = 7

Priority levels can be set using the priority parameter with the Priority enum:

import journald_send
from journald_send import Priority

journald_send.send('Error occurred', priority=Priority.ERROR)

Logging handler

class journald_send.log_handler.JournalHandler(level: int | str = 0, *, sender: ~collections.abc.Callable[[...], None] = <function send>, **kwargs: str)[source]

Handler for the Python standard logging framework.

It is model after systemd-python’s JournalHandler, but using our journald_send.send() to forward the logs to journald.

Example usage:

import logging
from journald_send.log_handler import JournalHandler

log = logging.getLogger("my-app")
log.addHandler(JournalHandler(SYSLOG_IDENTIFIER='my-app'))
log.warning('Something happened: %s', 'detail')

Fields attached to all messages can be specified as keyword arguments:

JournalHandler(SYSLOG_IDENTIFIER='my-cool-app')

The following journal fields are automatically included: MESSAGE, PRIORITY, LOGGER, THREAD_NAME, PROCESS_NAME, CODE_FILE, CODE_LINE, CODE_FUNC.

A MESSAGE_ID can be supplied via the extra dict:

import uuid

mid = uuid.UUID("0123456789ABCDEF0123456789ABCDEF")
log.warning('Message with ID', extra={'MESSAGE_ID': mid})
classmethod with_args(config: dict[str, Any] | None = None) → JournalHandler[source]

Create a JournalHandler from a configuration dictionary.

Useful when the logging configuration syntax (e.g. dictConfig) does not allow positional or keyword arguments in the usual way.

Parameters:

config – Dictionary of arguments passed to the JournalHandler constructor.