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, LOG_ALERT,
 111         LOG_CRIT, LOG_ERR, LOG_WARNING, LOG_NOTICE, LOG_INFO, LOG_DEBUG.
 112
 113         level_prefix is a boolean. If true, kernel-style log priority
 114         level prefixes (such as '<1>') are interpreted. See
 115         sd-daemon(3) for more information.
 116         """
 117
 118         fd = stream_fd(identifier, priority, level_prefix)
 119         return _os.fdopen(fd, 'w', 1)
 120
 121 class JournalHandler(_logging.Handler):
 122         """Journal handler class for the Python logging framework.
 123
 124         Please see the Python logging module documentation for an
 125         overview: http://docs.python.org/library/logging.html.
 126
 127         To create a custom logger whose messages go only to journal:
 128
 129         >>> log = logging.getLogger('custom_logger_name')
 130         >>> log.propagate = False
 131         >>> log.addHandler(journal.JournalHandler())
 132         >>> log.warn("Some message: %s", detail)
 133
 134         Note that by default, message levels INFO and DEBUG are ignored
 135         by the logging framework. To enable those log levels:
 136
 137         >>> log.setLevel(logging.DEBUG)
 138
 139         To attach journal MESSAGE_ID, an extra field is supported:
 140
 141         >>> import uuid
 142         >>> mid = uuid.UUID('0123456789ABCDEF0123456789ABCDEF')
 143         >>> log.warn("Message with ID", extra={'MESSAGE_ID': mid})
 144
 145         To redirect all logging messages to journal regardless of where
 146         they come from, attach it to the root logger:
 147
 148         >>> logging.root.addHandler(journal.JournalHandler())
 149
 150         For more complex configurations when using dictConfig or
 151         fileConfig, specify 'systemd.journal.JournalHandler' as the
 152         handler class.  Only standard handler configuration options
 153         are supported: level, formatter, filters.
 154
 155         The following journal fields will be sent:
 156
 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