X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=src%2Fpython-systemd%2Fjournal.py;h=892a56ff23730932bcfdbc16e7a5ad51cedc7b4c;hp=fc57437c28ac60716ab63ff4d3e59d9c97b6b46d;hb=2c07646764384545e5303222729d5ff93dec4347;hpb=927e96326c195ad39a45b091f98e9c635f400982

diff --git a/src/python-systemd/journal.py b/src/python-systemd/journal.py
index fc57437c2..892a56ff2 100644
--- a/src/python-systemd/journal.py
+++ b/src/python-systemd/journal.py
@@ -19,12 +19,238 @@
 #  You should have received a copy of the GNU Lesser General Public License
 #  along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
+import sys as _sys
+import datetime as _datetime
+import functools as _functools
+import uuid as _uuid
 import traceback as _traceback
 import os as _os
+from os import SEEK_SET, SEEK_CUR, SEEK_END
 import logging as _logging
+if _sys.version_info >= (3,):
+    from collections import ChainMap
 from syslog import (LOG_EMERG, LOG_ALERT, LOG_CRIT, LOG_ERR,
                     LOG_WARNING, LOG_NOTICE, LOG_INFO, LOG_DEBUG)
 from ._journal import sendv, stream_fd
+from ._reader import (_Journal, NOP, APPEND, INVALIDATE,
+                      LOCAL_ONLY, RUNTIME_ONLY, SYSTEM_ONLY)
+from . import id128 as _id128
+
+_MONOTONIC_CONVERTER = lambda x: _datetime.timedelta(microseconds=float(x))
+_REALTIME_CONVERTER = lambda x: _datetime.datetime.fromtimestamp(float(x)/1E6)
+DEFAULT_CONVERTERS = {
+    'MESSAGE_ID': _uuid.UUID,
+    '_MACHINE_ID': _uuid.UUID,
+    '_BOOT_ID': _uuid.UUID,
+    'PRIORITY': int,
+    'LEADER': int,
+    'SESSION_ID': int,
+    'USERSPACE_USEC': int,
+    'INITRD_USEC': int,
+    'KERNEL_USEC': int,
+    '_UID': int,
+    '_GID': int,
+    '_PID': int,
+    'SYSLOG_FACILITY': int,
+    'SYSLOG_PID': int,
+    '_AUDIT_SESSION': int,
+    '_AUDIT_LOGINUID': int,
+    '_SYSTEMD_SESSION': int,
+    '_SYSTEMD_OWNER_UID': int,
+    'CODE_LINE': int,
+    'ERRNO': int,
+    'EXIT_STATUS': int,
+    '_SOURCE_REALTIME_TIMESTAMP': _REALTIME_CONVERTER,
+    '__REALTIME_TIMESTAMP': _REALTIME_CONVERTER,
+    '_SOURCE_MONOTONIC_TIMESTAMP': _MONOTONIC_CONVERTER,
+    '__MONOTONIC_TIMESTAMP': _MONOTONIC_CONVERTER,
+    'COREDUMP': bytes,
+    'COREDUMP_PID': int,
+    'COREDUMP_UID': int,
+    'COREDUMP_GID': int,
+    'COREDUMP_SESSION': int,
+    'COREDUMP_SIGNAL': int,
+    'COREDUMP_TIMESTAMP': _REALTIME_CONVERTER,
+}
+
+if _sys.version_info >= (3,):
+    _convert_unicode = _functools.partial(str, encoding='utf-8')
+else:
+    _convert_unicode = _functools.partial(unicode, encoding='utf-8')
+
+class Journal(_Journal):
+    """Journal 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 `adm` group.
+
+    Example usage to print out all error or higher level messages
+    for systemd-udevd for the boot:
+
+    >>> myjournal = journal.Journal()
+    >>> myjournal.add_boot_match(journal.CURRENT_BOOT)
+    >>> myjournal.add_loglevel_matches(journal.LOG_ERR)
+    >>> myjournal.add_match(_SYSTEMD_UNIT="systemd-udevd.service")
+    >>> for entry in myjournal:
+    ...    print(entry['MESSAGE'])
+
+    See systemd.journal-fields(7) for more info on typical fields
+    found in the journal.
+    """
+    def __init__(self, converters=None, flags=LOCAL_ONLY, path=None):
+        """Creates instance of Journal, which allows filtering and
+        return of journal entries.
+        Argument `converters` is a dictionary which updates the
+        DEFAULT_CONVERTERS to convert journal field values.
+        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
+        currently flags are ignored when `path` is present as they are
+        currently not relevant.
+        """
+        super(Journal, self).__init__(flags, path)
+        if _sys.version_info >= (3,3):
+            self.converters = ChainMap()
+            if converters is not None:
+                self.converters.maps.append(converters)
+            self.converters.maps.append(DEFAULT_CONVERTERS)
+        else:
+            self.converters = DEFAULT_CONVERTERS.copy()
+            if converters is not None:
+                self.converters.update(converters)
+
+    def _convert_field(self, key, value):
+        """Convert value based on callable from self.converters
+        based of field/key"""
+        try:
+            result = self.converters[key](value)
+        except:
+            # Default conversion in unicode
+            try:
+                result = _convert_unicode(value)
+            except UnicodeDecodeError:
+                # Leave in default bytes
+                result = value
+        return result
+
+    def _convert_entry(self, entry):
+        """Convert entire journal entry utilising _covert_field"""
+        result = {}
+        for key, value in entry.items():
+            if isinstance(value, list):
+                result[key] = [self._convert_field(key, val) for val in value]
+            else:
+                result[key] = self._convert_field(key, value)
+        return result
+
+    def add_match(self, *args, **kwargs):
+        """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".
+        """
+        args = list(args)
+        args.extend(_make_line(key, val) for key, val in kwargs.items())
+        for arg in args:
+            super(Journal, self).add_match(arg)
+
+    def get_next(self, skip=1):
+        """Return the next log entry as a dictionary of fields.
+
+        Optional skip value will return the `skip`\-th log entry.
+
+        Entries will be processed with converters specified during
+        Journal creation.
+        """
+        return self._convert_entry(
+            super(Journal, self).get_next(skip))
+
+    def query_unique(self, field):
+        """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
+        Journal creation.
+        """
+        return set(self._convert_field(field, value)
+            for value in super(Journal, self).query_unique(field))
+
+    def seek_realtime(self, realtime):
+        """Seek to a matching journal entry nearest to `realtime` time.
+
+        Argument `realtime` must be either an integer unix timestamp
+        or datetime.datetime instance.
+        """
+        if isinstance(realtime, _datetime.datetime):
+            realtime = float(realtime.strftime("%s.%f"))
+        return super(Journal, self).seek_realtime(realtime)
+
+    def seek_monotonic(self, 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.
+        """
+        if isinstance(monotonic, _datetime.timedelta):
+            monotonic = monotonic.totalseconds()
+        if isinstance(bootid, _uuid.UUID):
+            bootid = bootid.get_hex()
+        return super(Journal, self).seek_monotonic(monotonic, bootid)
+
+    def log_level(self, level):
+        """Set maximum log `level` by setting matches for PRIORITY.
+        """
+        if 0 <= level <= 7:
+            for i in range(level+1):
+                self.add_match(PRIORITY="%s" % i)
+        else:
+            raise ValueError("Log level must be 0 <= level <= 7")
+
+    def messageid_match(self, 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`).
+        """
+        if isinstance(messageid, _uuid.UUID):
+            messageid = messageid.get_hex()
+        self.add_match(MESSAGE_ID=messageid)
+
+    def this_boot(self, bootid=None):
+        """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').
+        """
+        if bootid is None:
+            bootid = _id128.get_boot().hex
+        else:
+            bootid = getattr(bootid, 'hex', bootid)
+        self.add_match(_BOOT_ID=bootid)
+
+    def this_machine(self, 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').
+        """
+        if machineid is None:
+            machineid = _id128.get_machine().hex
+        else:
+            machineid = getattr(machineid, 'hex', machineid)
+        self.add_match(_MACHINE_ID=machineid)
+
 
 def _make_line(field, value):
         if isinstance(value, bytes):
@@ -35,24 +261,18 @@ def _make_line(field, value):
 def send(MESSAGE, MESSAGE_ID=None,
          CODE_FILE=None, CODE_LINE=None, CODE_FUNC=None,
          **kwargs):
-        r"""Send a message to journald.
+        r"""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.
+        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.
-
-        Other parts of the message can be specified as keyword
-        arguments.
-
-        Both MESSAGE and MESSAGE_ID, if present, must be strings, and
-        will be sent as UTF-8 to journal. Other arguments can be
-        bytes, in which case they will be sent as-is to journal.
+        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,
@@ -60,6 +280,11 @@ def send(MESSAGE, MESSAGE_ID=None,
         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.
         """
@@ -67,7 +292,8 @@ def send(MESSAGE, MESSAGE_ID=None,
         args = ['MESSAGE=' + MESSAGE]
 
         if MESSAGE_ID is not None:
-                args.append('MESSAGE_ID=' + MESSAGE_ID)
+                id = getattr(MESSAGE_ID, 'hex', MESSAGE_ID)
+                args.append('MESSAGE_ID=' + id)
 
         if CODE_LINE == CODE_FILE == CODE_FUNC == None:
                 CODE_FILE, CODE_LINE, CODE_FUNC = \
@@ -96,19 +322,20 @@ def stream(identifier, priority=LOG_DEBUG, level_prefix=False):
         <open file '<fdopen>', mode 'w' at 0x...>
         >>> stream.write('message...\n')
 
-        will produce the following message in the journal:
+        will produce the following message in the journal::
 
-        PRIORITY=7
-        SYSLOG_IDENTIFIER=myapp
-        MESSAGE=message...
+          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.
+        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
@@ -131,31 +358,31 @@ class JournalHandler(_logging.Handler):
         >>> 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:
+        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 attach journal MESSAGE_ID, an extra field is supported:
 
-        >>> log.warn("Message with ID",
-        >>>     extra={'MESSAGE_ID': '22bb01335f724c959ac4799627d1cb61'})
+        >>> import uuid
+        >>> mid = uuid.UUID('0123456789ABCDEF0123456789ABCDEF')
+        >>> log.warn("Message with ID", extra={'MESSAGE_ID': mid})
 
         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
+        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.
+        are supported: `level`, `formatter`, `filters`.
 
         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).
+        `MESSAGE`, `PRIORITY`, `THREAD_NAME`, `CODE_FILE`, `CODE_LINE`,
+        `CODE_FUNC`, `LOGGER` (name as supplied to getLogger call),
+        `MESSAGE_ID` (optional, see above).
         """
 
         def emit(self, record):