cysystemd 1.1.1

SystemD wrapper on Cython

Python systemd wrapper using Cython

Table of contents

• Installation

  • Debian/Ubuntu

  • Centos 7

  • Installation from sources

• Usage examples

  • Writing to journald

    • Logging handler for python logger

    • Systemd daemon notification

  • Reading journald

    • Reading all systemd records

    • Read only cron logs

    • Polling records

    • JournalD open modes

    • JournalD entry

    • JournalD reader

Installation

All packages available on github releases.

Debian/Ubuntu

Install repository key

wget -qO - 'https://bintray.com/user/downloadSubjectPublicKey?username=bintray' | \
   apt-key add -

Install the repository file

Debian Jessie:

echo "deb http://dl.bintray.com/mosquito/cysystemd jessie main" > /etc/apt/sources.list.d/cysystemd.list
apt-get update
apt-get install python-cysystemd python3-cysystemd

Ubuntu Xenial:

echo "deb http://dl.bintray.com/mosquito/cysystemd xenial main" > /etc/apt/sources.list.d/cysystemd.list
apt-get update
apt-get install python-cysystemd python3-cysystemd

Ubuntu Bionic:

echo "deb http://dl.bintray.com/mosquito/cysystemd bionic main" > /etc/apt/sources.list.d/cysystemd.list
apt-get update
apt-get install python-cysystemd python3-cysystemd

Centos 7

yum localinstall \
   https://github.com/mosquito/cysystemd/releases/download/0.17.1/python-cysystemd-0.17.1-1.centos7.x86_64.rpm

Installation from sources

You should install systemd headers

For debian users:

apt-get install build-essential \
    libsystemd-journal-dev \
    libsystemd-daemon-dev \
    libsystemd-dev

For CentOS/RHEL

yum install gcc systemd-devel

And install it from pypi

pip install cysystemd

Usage examples

Writing to journald

Logging handler for python logger

from cysystemd import journal
import logging
import uuid

logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger()
logger.addHandler(journal.JournaldLogHandler())

try:
    log.info("Trying to do something")
    raise Exception('foo')
except:
    logger.exception("Test Exception %s", 1)

Systemd daemon notification

from cysystemd.daemon import notify, Notification

# Send READY=1
notify(Notification.READY)

# Send status
notify(Notification.STATUS, "I'm fine.")

# Send stopping
notify(Notification.STOPPING)

Write message into Systemd journal

from cysystemd import journal


journal.write("Hello Lennart")

# Or send structured data
journal.send(
    message="Hello Lennart",
    priority=journal.Priority.INFO,
    some_field='some value',
)

Reading journald

Reading all systemd records

from cysystemd.reader import JournalReader, JournalOpenMode

journal_reader = JournalReader()
journal_reader.open(JournalOpenMode.SYSTEM)
journal_reader.seek_head()

for record in journal_reader:
   print(record.data['MESSAGE'])

Read only cron logs

from cysystemd.reader import JournalReader, JournalOpenMode, Rule


rules = (
   Rule("SYSLOG_IDENTIFIER", "CRON") &
   Rule("_SYSTEMD_UNIT", "crond.service") |
   Rule("_SYSTEMD_UNIT", "cron.service")
)

cron_reader = JournalReader()
cron_reader.open(JournalOpenMode.SYSTEM)
cron_reader.seek_head()
cron_reader.add_filter(rules)

for record in cron_reader:
   print(record.data['MESSAGE'])

Polling records

from cysystemd.reader import JournalReader, JournalOpenMode


reader = JournalReader()
reader.open(JournalOpenMode.SYSTEM)
reader.seek_tail()

poll_timeout = 255

while True:
   reader.wait(poll_timeout)

   for record in reader:
      print(record.data['MESSAGE'])

JournalD open modes

• CURRENT_USER

• LOCAL_ONLY

• RUNTIME_ONLY

• SYSTEM

• SYSTEM_ONLY

from cysystemd.reader import JournalReader, JournalOpenMode

reader = JournalReader()
reader.open(JournalOpenMode.CURRENT_USER)

JournalD entry

JournalEntry class has some special properties and methods:

• data - journal entry content (dict)

• date - entry timestamp (datetime instance)

• cursor - systemd identification bytes for this entry

• boot_id() - returns bootid

• get_realtime_sec() - entry epoch (float)

• get_realtime_usec() - entry epoch (int microseconds)

• get_monotonic_sec() - entry monotonic time (float)

• get_monotonic_usec() - entry monotonic time (int microseconds)

• __getitem__(key) - shoutcut for entry.data[key]

JournalD reader

JournalReader class has some special properties and methods:

• open(flags=JournalOpenMode.CURRENT_USER) - opening journald with selected mode

• open_directory(path) - opening journald from path

• open_files(*filename) - opening journald from files

• data_threshold - may be used to get or set the data field size threshold for data returned by fething entry data.

• closed - returns True when journal reader closed

• locked - returns True when journal reader locked

• idle - returns True when journal reader opened

• seek_head - move reader pointer to the first entry

• seek_tail - move reader pointer to the last entry

• seek_monotonic_usec - seeks to the entry with the specified monotonic timestamp, i.e. CLOCK_MONOTONIC. Since monotonic time restarts on every reboot a boot ID needs to be specified as well.

• seek_realtime_usec - seeks to the entry with the specified realtime (wallclock) timestamp, i.e. CLOCK_REALTIME. Note that the realtime clock is not necessarily monotonic. If a realtime timestamp is ambiguous, it is not defined which position is sought to.

• seek_cursor - seeks to the entry located at the specified cursor (see JournalEntry.cursor).

• wait(timeout) - It will synchronously wait until the journal gets changed. The maximum time this call sleeps may be controlled with the timeout_usec parameter.

• __iter__ - returns JournalReader object

• __next__ - calls next() or raise StopIteration

• next(skip=0) - returns the next JournalEntry. The skip parameter skips some entries.

• previous(skip=0) - returns the previous JournalEntry. The skip parameter skips some entries.

• skip_next(skip) - skips next entries.

• skip_previous(skip) - skips next entries.

• add_filter(rule) - adding filter rule. See read-only-cron-logs as example.

• clear_filter - reset all filters

• fd - returns a special file descriptor

• events - returns EPOLL events

• timeout - returns internal timeout

• process_events() - After each poll() wake-up process_events() needs to be called to process events. This call will also indicate what kind of change has been detected.

• get_catalog() - retrieves a message catalog entry for the current journal entry. This will look up an entry in the message catalog by using the “MESSAGE_ID=” field of the current journal entry. Before returning the entry all journal field names in the catalog entry text enclosed in “@” will be replaced by the respective field values of the current entry. If a field name referenced in the message catalog entry does not exist, in the current journal entry, the “@” will be removed, but the field name otherwise left untouched.

• get_catalog_for_message_id(message_id: UUID) - works similar to get_catalog() but the entry is looked up by the specified message ID (no open journal context is necessary for this), and no field substitution is performed.