src/python-systemd/journal.py

   1 #  -*- Mode: python; coding:utf-8; indent-tabs-mode: nil -*- */
   2 #
   3 #  This file is part of systemd.
   4 #
   5 #  Copyright 2012 David Strauss <david@davidstrauss.net>
   6 #  Copyright 2012 Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl>
   7 #  Copyright 2012 Marti Raudsepp <marti@juffo.org>
   8 #
   9 #  systemd is free software; you can redistribute it and/or modify it
  10 #  under the terms of the GNU Lesser General Public License as published by
  11 #  the Free Software Foundation; either version 2.1 of the License, or
  12 #  (at your option) any later version.
  13 #
  14 #  systemd is distributed in the hope that it will be useful, but
  15 #  WITHOUT ANY WARRANTY; without even the implied warranty of
  16 #  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  17 #  Lesser General Public License for more details.
  18 #
  19 #  You should have received a copy of the GNU Lesser General Public License
  20 #  along with systemd; If not, see <http://www.gnu.org/licenses/>.
  21
  22 import traceback as _traceback
  23 import os as _os
  24 import logging as _logging
  25 from syslog import (LOG_EMERG, LOG_ALERT, LOG_CRIT, LOG_ERR,
  26                     LOG_WARNING, LOG_NOTICE, LOG_INFO, LOG_DEBUG)
  27 from ._journal import sendv, stream_fd
  28
  29 def _make_line(field, value):
  30         if isinstance(value, bytes):
  31                 return field.encode('utf-8') + b'=' + value
  32         else:
  33                 return field + '=' + value
  34
  35 def send(MESSAGE, MESSAGE_ID=None,
  36          CODE_FILE=None, CODE_LINE=None, CODE_FUNC=None,
  37          **kwargs):
  38         r"""Send a message to the journal.
  39
  40         >>> journal.send('Hello world')
  41         >>> journal.send('Hello, again, world', FIELD2='Greetings!')
  42         >>> journal.send('Binary message', BINARY=b'\xde\xad\xbe\xef')
  43
  44         Value of the MESSAGE argument will be used for the MESSAGE=
  45         field. MESSAGE must be a string and will be sent as UTF-8 to
  46         the journal.
  47
  48         MESSAGE_ID can be given to uniquely identify the type of
  49         message. It must be a string or a uuid.UUID object.
  50
  51         CODE_LINE, CODE_FILE, and CODE_FUNC can be specified to
  52         identify the caller. Unless at least on of the three is given,
  53         values are extracted from the stack frame of the caller of
  54         send(). CODE_FILE and CODE_FUNC must be strings, CODE_LINE
  55         must be an integer.
  56
  57         Additional fields for the journal entry can only be specified
  58         as keyword arguments. The payload can be either a string or
  59         bytes. A string will be sent as UTF-8, and bytes will be sent
  60         as-is to the journal.
  61
  62         Other useful fields include PRIORITY, SYSLOG_FACILITY,
  63         SYSLOG_IDENTIFIER, SYSLOG_PID.
  64         """
  65
  66         args = ['MESSAGE=' + MESSAGE]
  67
  68         if MESSAGE_ID is not None:
  69                 id = getattr(MESSAGE_ID, 'hex', MESSAGE_ID)
  70                 args.append('MESSAGE_ID=' + id)
  71
  72         if CODE_LINE == CODE_FILE == CODE_FUNC == None:
  73                 CODE_FILE, CODE_LINE, CODE_FUNC = \
  74                         _traceback.extract_stack(limit=2)[0][:3]
  75         if CODE_FILE is not None:
  76                 args.append('CODE_FILE=' + CODE_FILE)
  77         if CODE_LINE is not None:
  78                 args.append('CODE_LINE={:d}'.format(CODE_LINE))
  79         if CODE_FUNC is not None:
  80                 args.append('CODE_FUNC=' + CODE_FUNC)
  81
  82         args.extend(_make_line(key, val) for key, val in kwargs.items())
  83         return sendv(*args)
  84
  85 def stream(identifier, priority=LOG_DEBUG, level_prefix=False):
  86         r"""Return a file object wrapping a stream to journal.
  87
  88         Log messages written to this file as simple newline sepearted
  89         text strings are written to the journal.
  90
  91         The file will be line buffered, so messages are actually sent
  92         after a newline character is written.
  93
  94         >>> stream = journal.stream('myapp')
  95         >>> stream
  96         <open file '<fdopen>', mode 'w' at 0x...>
  97         >>> stream.write('message...\n')
  98
  99         will produce the following message in the journal::
 100
 101           PRIORITY=7
 102           SYSLOG_IDENTIFIER=myapp
 103           MESSAGE=message...
 104
 105         Using the interface with print might be more convinient:
 106
 107         >>> from __future__ import print_function
 108         >>> print('message...', file=stream)
 109
 110         priority is the syslog priority, one of `LOG_EMERG`,
 111         `LOG_ALERT`, `LOG_CRIT`, `LOG_ERR`, `LOG_WARNING`,
 112         `LOG_NOTICE`, `LOG_INFO`, `LOG_DEBUG`.
 113
 114         level_prefix is a boolean. If true, kernel-style log priority
 115         level prefixes (such as '<1>') are interpreted. See
 116         sd-daemon(3) for more information.
 117         """
 118
 119         fd = stream_fd(identifier, priority, level_prefix)
 120         return _os.fdopen(fd, 'w', 1)
 121
 122 class JournalHandler(_logging.Handler):
 123         """Journal handler class for the Python logging framework.
 124
 125         Please see the Python logging module documentation for an
 126         overview: http://docs.python.org/library/logging.html.
 127
 128         To create a custom logger whose messages go only to journal:
 129
 130         >>> log = logging.getLogger('custom_logger_name')
 131         >>> log.propagate = False
 132         >>> log.addHandler(journal.JournalHandler())
 133         >>> log.warn("Some message: %s", detail)
 134
 135         Note that by default, message levels `INFO` and `DEBUG` are
 136         ignored by the logging framework. To enable those log levels:
 137
 138         >>> log.setLevel(logging.DEBUG)
 139
 140         To attach journal MESSAGE_ID, an extra field is supported:
 141
 142         >>> import uuid
 143         >>> mid = uuid.UUID('0123456789ABCDEF0123456789ABCDEF')
 144         >>> log.warn("Message with ID", extra={'MESSAGE_ID': mid})
 145
 146         To redirect all logging messages to journal regardless of where
 147         they come from, attach it to the root logger:
 148
 149         >>> logging.root.addHandler(journal.JournalHandler())
 150
 151         For more complex configurations when using `dictConfig` or
 152         `fileConfig`, specify `systemd.journal.JournalHandler` as the
 153         handler class.  Only standard handler configuration options
 154         are supported: `level`, `formatter`, `filters`.
 155
 156         The following journal fields will be sent:
 157         `MESSAGE`, `PRIORITY`, `THREAD_NAME`, `CODE_FILE`, `CODE_LINE`,
 158         `CODE_FUNC`, `LOGGER` (name as supplied to getLogger call),
 159         `MESSAGE_ID` (optional, see above).
 160         """
 161
 162         def emit(self, record):
 163                 """Write record as journal event.
 164
 165                 MESSAGE is taken from the message provided by the
 166                 user, and PRIORITY, LOGGER, THREAD_NAME,
 167                 CODE_{FILE,LINE,FUNC} fields are appended
 168                 automatically. In addition, record.MESSAGE_ID will be
 169                 used if present.
 170                 """
 171                 try:
 172                         msg = self.format(record)
 173                         pri = self.mapPriority(record.levelno)
 174                         mid = getattr(record, 'MESSAGE_ID', None)
 175                         send(msg,
 176                              MESSAGE_ID=mid,
 177                              PRIORITY=format(pri),
 178                              LOGGER=record.name,
 179                              THREAD_NAME=record.threadName,
 180                              CODE_FILE=record.pathname,
 181                              CODE_LINE=record.lineno,
 182                              CODE_FUNC=record.funcName)
 183                 except Exception:
 184                         self.handleError(record)
 185
 186         @staticmethod
 187         def mapPriority(levelno):
 188                 """Map logging levels to journald priorities.
 189
 190                 Since Python log level numbers are "sparse", we have
 191                 to map numbers in between the standard levels too.
 192                 """
 193                 if levelno <= _logging.DEBUG:
 194                         return LOG_DEBUG
 195                 elif levelno <= _logging.INFO:
 196                         return LOG_INFO
 197                 elif levelno <= _logging.WARNING:
 198                         return LOG_WARNING
 199                 elif levelno <= _logging.ERROR:
 200                         return LOG_ERR
 201                 elif levelno <= _logging.CRITICAL:
 202                         return LOG_CRIT
 203                 else:
 204                         return LOG_ALERT