systemd-logging 1.0.2__py3-none-any.whl

systemd_logging-1.0.2.dist-info/METADATA

@@ -0,0 +1,72 @@
+Metadata-Version: 2.5
+Name: systemd-logging
+Version: 1.0.2
+Summary: Simplifies logging for systemd
+Project-URL: Homepage, https://github.com/idlesign/systemd-logging
+Author-email: Igor Starikov <idlesign@yandex.ru>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: journal,logging,systemd
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Requires-Dist: ctyped>=0.7.1
+Description-Content-Type: text/markdown
+
+# systemd-logging
+
+<https://github.com/idlesign/systemd-logging>
+
+[![release](https://img.shields.io/pypi/v/systemd-logging.svg)](https://pypi.python.org/pypi/systemd-logging)
+[![lic](https://img.shields.io/pypi/l/systemd-logging.svg)](https://pypi.python.org/pypi/systemd-logging)
+[![coverage](https://img.shields.io/coveralls/idlesign/systemd-logging/master.svg)](https://coveralls.io/r/idlesign/systemd-logging)
+
+## Description
+
+*Simplifies logging for systemd*
+
+**Requires Python 3.10+**
+
+* No need to compile (pure Python), uses `libsystemd.so`.
+* Simplified configuration.
+* Just logging. Nothing more.
+
+## Usage
+
+```python
+import logging
+
+from systemdlogging.toolbox import init_systemd_logging
+
+# This one line in most cases would be enough.
+# By default it attaches systemd logging handler to a root Python logger.
+init_systemd_logging()  # Returns True if initialization went fine.
+
+# Now you can use logging as usual.
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.DEBUG)
+
+logger.debug('My debug message')
+
+try:
+    raise ValueError('Log me please')
+
+except ValueError:
+    # Additional context can be passed in extra.context.
+    logger.exception('Something terrible just happened', extra={
+        'message_id': True,  # Generate message ID automatically.
+        'context': {
+            'FIELD1': 'one',
+            'FIELD2': 'two',
+        }
+    }, stack_info=True)
+```

systemd_logging-1.0.2.dist-info/RECORD

@@ -0,0 +1,7 @@
+systemdlogging/__init__.py,sha256=vANbxWqJ8cObeyPJkH6BJy4jnBYu3ExbKEi0OllMAH0,18
+systemdlogging/backend_ctyped.py,sha256=SVOiGY1Sico75GyhPV_k4PHRuF4YEGFR3I-kdr5MXS8,632
+systemdlogging/toolbox.py,sha256=1TkZjn6PaOeLNRkY3mbZKQxFDJNrIh9Brx8GBSzXCnk,6020
+systemd_logging-1.0.2.dist-info/METADATA,sha256=MY4TU3-k8AqPiOdRErAb0mesVcU5mXnpRV6_NkLTWek,2342
+systemd_logging-1.0.2.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+systemd_logging-1.0.2.dist-info/licenses/LICENSE,sha256=-xlA3bnU7uvYqzNxgTYUlDOBlW7_2KyJ1JsvHIGBgAU,1508
+systemd_logging-1.0.2.dist-info/RECORD,,

systemd_logging-1.0.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

systemd_logging-1.0.2.dist-info/licenses/LICENSE

@@ -0,0 +1,28 @@
+Copyright (c) 2019-2026, Igor `idle sign` Starikov
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the systemd-logging nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+

systemdlogging/__init__.py

@@ -0,0 +1 @@
+VERSION = '1.0.2'

systemdlogging/backend_ctyped.py

@@ -0,0 +1,33 @@
+import logging
+
+from ctyped.exceptions import CtypedException
+from ctyped.toolbox import Library
+
+LOGGER = logging.getLogger(__name__)
+
+
+def send_stub(*fmt):  # pragma: nocover
+    """Dummy send function to be used when the real one
+    is not available (e.g. no libsystemd found).
+
+    """
+    return None
+
+
+try:
+    lib = Library('libsystemd.so', prefix='sd_journal_')
+
+except CtypedException:  # pragma: nocover
+
+    send = send_stub
+
+    LOGGER.warning("systemd library is not available and won't be used for logging")
+
+else:
+
+    @lib.function()
+    def send(*fmt) -> int:  # pragma: nocover
+        ...
+
+
+    lib.bind_types()

systemdlogging/toolbox.py

@@ -0,0 +1,193 @@
+import logging
+import os
+import syslog
+import uuid
+
+from .backend_ctyped import send, send_stub
+
+PRIORITY_MAP = {
+    logging.CRITICAL: syslog.LOG_CRIT,
+    logging.ERROR: syslog.LOG_ERR,
+    logging.WARNING: syslog.LOG_WARNING,
+    logging.INFO: syslog.LOG_INFO,
+    logging.DEBUG: syslog.LOG_DEBUG,
+}
+
+
+def log_message(*, level: int, msg: str, context: dict | None = None) -> bool:
+    """Sends a message to systemd.
+
+    .. warning:: Low level function. You may want to
+        use more convenient `init_systemd_logging()` or `SystemdHandler` and `SystemdFormatter`.
+
+    Natively supported fields:
+        http://0pointer.de/public/systemd-man/systemd.journal-fields.html
+
+    :param level: Logging level.
+    :param msg: Message text to send.
+    :param context: Additional context to send within message.
+
+    """
+    args = {
+        'MESSAGE': msg,
+        'PRIORITY': PRIORITY_MAP.get(level, level),
+    }
+
+    args.update(context or {})
+
+    return send(
+        # escape % in values to prevent segfaults
+        # while trying to format things like %s, %d, etc.
+        *[f'{key}={val}'.replace('%', '%%').encode() for key, val in args.items()],
+        None
+    ) == 0
+
+
+class SystemdHandler(logging.Handler):
+    """Allows passing log messages to systemd.
+
+    Additional information may be passed in ``extra`` dictionary:
+
+        * context - Dictionary with additional information to attach to a message.
+        * message_id - Message ID (usually UUID to assign to the message).
+            If ``True`` ID will be generated automatically
+
+    .. code-block: python
+
+        logger.exception('This is my exceptional log entry.', extra={
+            'message_id': True,
+            'context': {
+                'MY_FIELD': 'My value',
+            }
+        }, stack_info=True)
+
+    Fills in the following fields automatically:
+
+        * CODE_FILE - Filename
+        * CODE_LINE - Code line number
+        * CODE_FUNC - Code function name
+        * CODE_MODULE - Python module name
+        * LOGGER - Logger name
+        * THREAD_ID - Thread ID if any
+        * THREAD_NAME - Thread name if any
+        * PROCESS_NAME - Process name if any
+        * PRIORITY - Priority based on logging level
+
+    Optionally fills in:
+        * TRACEBACK - Traceback information if available
+        * STACK - Stacktrace information if available
+        * MESSAGE_ID - Message ID (if context.message_id=True)
+
+    """
+
+    syslog_id: str = ''
+    """SYSLOG_IDENTIFIER to add to message. If not set command name is used."""
+
+    def emit(self, record: logging.LogRecord):
+
+        context = {
+            # Generic
+            'CODE_FILE': record.pathname,
+            'CODE_LINE': record.lineno,
+            'CODE_FUNC': record.funcName,
+            # Custom
+            'CODE_MODULE': record.module,
+            'LOGGER': record.name,
+            'THREAD_ID': record.thread,
+            'THREAD_NAME': record.threadName,
+            'PROCESS_NAME': record.processName,
+        }
+
+        try:
+            exc_info = record.exc_info
+            if exc_info:
+                context['TRACEBACK'] = self.formatter.formatException(exc_info)
+
+            stack_info = record.stack_info
+            if stack_info:
+                context['STACK'] = self.formatter.formatStack(stack_info)
+
+            syslog_id = self.syslog_id
+            if syslog_id:
+                context['SYSLOG_IDENTIFIER'] = syslog_id
+
+            msg = self.format(record)
+
+            message_id = getattr(record, 'message_id', None)
+
+            if message_id:
+
+                if message_id is True:
+                    # Generate message ID automatically.
+                    message_id = uuid.uuid3(uuid.NAMESPACE_OID, '|'.join(str(val) for val in (
+                        msg, record.levelno, record.pathname, record.funcName
+                    ))).hex
+
+                context['MESSAGE_ID'] = message_id
+
+            context_ = getattr(record, 'context', {})
+            context.update(context_)
+
+            log_message(level=record.levelno, msg=msg, context=context)
+
+        except Exception:  # pragma: nocover
+            self.handleError(record)
+
+
+class SystemdFormatter(logging.Formatter):
+    """Formatter for systemd."""
+
+    def format(self, record):
+        # This one is just like its parent just doesn't
+        # append traceback etc. to the message.
+        record.message = record.getMessage()
+        return self.formatMessage(record)
+
+
+def check_for_systemd() -> bool:
+    """Checks whether systemd library is available and
+    the current process is run under systemd (and thus its output
+    is connected to journald).
+
+    """
+    if send is send_stub:
+        return False
+
+    journal_stream = os.environ.get("JOURNAL_STREAM")  # systemd v231+
+
+    if journal_stream:
+        # Output streams might have been replaced by a wrapping process,
+        # so verify that stdout/stderr are still connected to the journal.
+        return any(
+            f"{stat.st_dev}:{stat.st_ino}" == journal_stream
+            for stat in (os.fstat(fd) for fd in (1, 2))
+        )
+
+    return bool(os.environ.get("INVOCATION_ID"))  # Works with systemd v232+
+
+
+def init_systemd_logging(*, logger: logging.Logger | None = None, syslog_id: str = '') -> bool:
+    """Initializes logging to send log messages to systemd.
+
+    Returns boolean indicating initialization went fine (see also `check_for_systemd()`).
+
+    If it wasn't one may either to fallback to another logging handler
+    or leave it as it is possibly sacrificing some log context.
+
+    :param logger: Logger to attach systemd logging handler to.
+        If not set handler is attached to a root logger.
+
+    :param syslog_id: Value to be used in SYSLOG_IDENTIFIER message field.
+
+    """
+    systemd_ok = check_for_systemd()
+
+    if systemd_ok:
+        handler = SystemdHandler()
+        handler.syslog_id = syslog_id
+        handler.setFormatter(SystemdFormatter())
+
+        logger = logger or logging.getLogger()
+        logger.addHandler(handler)
+
+    return systemd_ok