initial code

Author: AttilaGombosER

.fpm

@@ -0,0 +1,7 @@
+-s python
+-t deb
+--package dist
+--force
+--log warn
+--python-bin python3
+--python-package-name-prefix python3

.github/workflows/python-release.yml

@@ -0,0 +1,33 @@
+name: Python release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  publish-and-release:
+    name: Publish and release distributions
+
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+      discussions: write
+
+    env:
+      GITHUB_TOKEN: ${{ secrets.ACTION_ACCESS_TOKEN }}
+
+    outputs:
+      artifact_id: ${{ steps.publish.outputs.artifact-id }}
+      artifact_url: ${{ steps.publish.outputs.artifact-url }}
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+      - name: Package and publish
+        uses: EffectiveRange/python-package-github-action@v1
+        with:
+          debian-dist-type: 'library'
+      - name: Release
+        uses: EffectiveRange/version-release-github-action@v1

.github/workflows/python-test.yml

@@ -0,0 +1,29 @@
+name: Python test
+
+on:
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  build:
+    name: Build and test
+
+    runs-on: ubuntu-latest
+
+    permissions:
+      # Gives the action the necessary permissions for publishing new
+      # comments in pull requests.
+      pull-requests: write
+      contents: read
+
+    env:
+      GITHUB_TOKEN: ${{ secrets.ACTION_ACCESS_TOKEN }}
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+      - name: Verify changes
+        uses: EffectiveRange/python-verify-github-action@v1
+        with:
+          add-coverage-comment: 'false'
+          coverage-threshold: '95'

.gitignore

@@ -160,3 +160,8 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
+
+# IntelliJ project files
+*.iml
+
+tests/logs/

README.md

@@ -1,2 +1,103 @@
 # python-context-logger
-Contextual structured logging library for Python
+Contextual structured logging library for Python.
+
+Uses [structlog](https://www.structlog.org/en/stable/) to provide structured logging with minimal setup.
+
+## Table of contents
+- [Features](#features)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Usage](#usage)
+- [New in 1.1.0](#new-in-110)
+
+## Features
+
+- Structured logging
+- Contextual logging
+- Colorized console output
+- JSON line file output
+- Easy setup
+- [New in 1.1.0](#new-in-110) Standard library log messages are also captured, enriched and formatted
+
+Contextual information is added to each structured log message on any thread, including:
+- Application name
+- Application version
+- Hostname
+- Logger name
+- Log level
+- Timestamp
+- [New in 1.1.0](#new-in-110) Optional call information (module name, filename, line number, function name, process name, thread name)
+
+Custom fields can be added to each log message
+
+## Requirements
+
+- [Python3](https://www.python.org/downloads/)
+- [structlog](https://www.structlog.org/en/stable/)
+
+## Installation
+
+### Install from source root directory
+
+```bash
+pip install .
+```
+
+### Install from source distribution
+
+1. Create source distribution
+    ```bash
+    pip setup.py sdist
+    ```
+
+2. Install from distribution file
+    ```bash
+    pip install dist/python_context_logger-1.0.0.tar.gz
+    ```
+   
+3. Install from GitHub repository
+    ```bash
+    pip install git+https://github.com/EffectiveRange/python-context-logger.git@latest
+    ```
+
+## Usage
+Example usage:
+```python
+from context_logger import get_logger, setup_logging
+
+log = get_logger('ExampleClass')
+
+setup_logging('example-app', 'INFO', 'logs/example.log')
+
+log.info('This is a simple message')
+log.error('This is an error message', error_message='Something terrible happened', error_code=1234)
+```
+Console output (colored):
+```
+2024-02-16T12:49:41.733384Z [info     ] This is a simple message       [ExampleClass] app_version=0.0.1 application=example-app hostname=example-host
+2024-02-16T12:49:41.734073Z [error    ] This is an error message       [ExampleClass] app_version=0.0.1 application=example-app error_code=1234 error_message=Something terrible happened hostname=example-host
+```
+File output (logs/example.log):
+```
+{"logger": "ExampleClass", "level": "info", "timestamp": "2024-02-16T12:49:41.733384Z", "message": "This is a simple message", "hostname": "example-host", "app_version": "0.0.1", "application": "example-app"}
+{"error_message": "Something terrible happened", "error_code": 1234, "logger": "ExampleClass", "level": "error", "timestamp": "2024-02-16T12:49:41.734073Z", "message": "This is an error message", "hostname": "example-host", "app_version": "0.0.1", "application": "example-app"}
+```
+### New in 1.1.0
+Example usage with call information and standard library logging:
+```python
+import logging
+from context_logger import get_logger, setup_logging
+
+setup_logging('example-app', add_call_info=True)
+
+log = get_logger('ExampleClass')
+stdlib_log = logging.getLogger('StdLibClass')
+
+log.info('This is a simple message')
+stdlib_log.info('This is a simple message')
+```
+Console output (colored):
+```
+2024-02-26T14:55:40.320668Z [info     ] This is a simple message       [ExampleClass] app_version=0.0.1 application=example-app func_name=test_file_logging hostname=example-host lineno=27 module=test_logger pathname=/home/attila/Work/context-logger/tests/test_logger.py process_name=MainProcess thread_name=MainThread
+2024-02-26T14:55:40.326201Z [info     ] This is a simple message       [StdLibClass] app_version=0.0.1 application=example-app func_name=test_file_logging hostname=example-host lineno=28 module=test_logger pathname=/home/attila/Work/context-logger/tests/test_logger.py process_name=MainProcess thread_name=MainThread
+```

context_logger/__init__.py

@@ -0,0 +1,2 @@
+from .filter import *
+from .logger import *

context_logger/filter.py

@@ -0,0 +1,55 @@
+# Copyright (C) 2024  Ferenc Nandor Janky
+# Copyright (C) 2024  Attila Gombos
+# Contact: info@effective-range.com
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 2.1 of the License, or (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this library; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301
+# USA
+import socket
+from importlib.metadata import version, PackageNotFoundError
+from logging import Filter, LogRecord
+
+
+class ContextSetupFilter(Filter):
+
+    def __init__(self, application_name: str):
+        super().__init__()
+        self._application_name = application_name
+
+    def filter(self, record: LogRecord) -> bool:
+        if not isinstance(record.msg, dict):
+            self._convert_stdlib_record(record)
+
+        if isinstance(record.msg, dict):
+            record.msg['hostname'] = socket.gethostname()
+            record.msg['application'] = self._application_name
+            record.msg['app_version'] = self._get_application_version()
+
+            if 'process_name' in record.msg:
+                record.msg['process_name'] = record.processName
+
+        return True
+
+    def _convert_stdlib_record(self, record: LogRecord) -> None:
+        if record.args:
+            record.msg = record.msg % record.args
+            record.args = ()
+
+        record.msg = {'message': record.msg}
+
+    def _get_application_version(self) -> str:
+        try:
+            return version(self._application_name)
+        except PackageNotFoundError:
+            return 'none'

context_logger/logger.py

@@ -0,0 +1,153 @@
+# Copyright (C) 2024  Ferenc Nandor Janky
+# Copyright (C) 2024  Attila Gombos
+# Contact: info@effective-range.com
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 2.1 of the License, or (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this library; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301
+# USA
+import logging
+import logging.handlers
+import os
+import sys
+import warnings
+from logging.handlers import RotatingFileHandler
+from typing import Any, Optional
+
+import structlog
+from structlog._log_levels import add_log_level
+from structlog.dev import ConsoleRenderer
+from structlog.processors import JSONRenderer, StackInfoRenderer, TimeStamper, EventRenamer, format_exc_info, \
+    UnicodeDecoder, CallsiteParameterAdder
+from structlog.stdlib import ProcessorFormatter, LoggerFactory, BoundLogger, PositionalArgumentsFormatter, \
+    add_logger_name
+
+from context_logger import ContextSetupFilter
+
+STRUCTURED_LOGGER = None
+
+
+def get_logger(logger_name: str) -> Any:
+    return structlog.get_logger(logger_name)
+
+
+def setup_logging(application_name: str, log_level: str = 'INFO',
+                  log_file_path: Optional[str] = None, max_bytes: int = 1024 * 1024, backup_count: int = 5,
+                  add_call_info: bool = False, message_field: str = 'message') -> None:
+    global STRUCTURED_LOGGER
+
+    if STRUCTURED_LOGGER is not None:
+        warnings.warn('Logging has already been set up, overwriting existing configuration.', UserWarning)
+
+    STRUCTURED_LOGGER = StructuredLogger(application_name, log_level, log_file_path, max_bytes, backup_count,
+                                         add_call_info, message_field)
+
+
+class StructuredLogger(object):
+
+    def __init__(self, application_name: str, log_level: str, log_file_path: Optional[str], max_bytes: int,
+                 backup_count: int, add_call_info: bool, message_field: str) -> None:
+        self._application_name = application_name
+        self._log_level = logging.getLevelName(log_level.upper())
+        self._max_bytes = max_bytes
+        self._backup_count = backup_count
+        self._message_field = message_field
+        self._add_call_info = add_call_info
+
+        self._shared_processors: Any = [
+            add_log_level,
+            add_logger_name,
+            PositionalArgumentsFormatter(),
+            StackInfoRenderer(),
+            TimeStamper(fmt='iso'),
+            format_exc_info,
+            UnicodeDecoder()
+        ]
+
+        if self._add_call_info:
+            self._add_call_info_processor()
+
+        self._shared_processors.append(EventRenamer(self._message_field))
+
+        root = logging.getLogger()
+        root.setLevel(self._log_level)
+
+        self._clear_handlers(root)
+
+        console_handler = self._create_console_handler()
+        root.addHandler(console_handler)
+
+        if log_file_path is not None:
+            file_handler = self._create_file_handler(log_file_path)
+            root.addHandler(file_handler)
+
+        structlog.configure(
+            processors=self._shared_processors + [ProcessorFormatter.wrap_for_formatter],
+            logger_factory=LoggerFactory(),
+            wrapper_class=BoundLogger,
+            cache_logger_on_first_use=True
+        )
+
+    def _add_call_info_processor(self) -> None:
+        self._shared_processors.append(CallsiteParameterAdder(
+            {
+                structlog.processors.CallsiteParameter.MODULE,
+                structlog.processors.CallsiteParameter.PATHNAME,
+                structlog.processors.CallsiteParameter.FUNC_NAME,
+                structlog.processors.CallsiteParameter.LINENO,
+                structlog.processors.CallsiteParameter.PROCESS_NAME,
+                structlog.processors.CallsiteParameter.THREAD_NAME
+            }
+        ))
+
+    def _clear_handlers(self, root: logging.Logger) -> None:
+        for handler in root.handlers:
+            if isinstance(handler, logging.StreamHandler) or isinstance(handler, RotatingFileHandler):
+                root.removeHandler(handler)
+
+    def _create_console_handler(self) -> logging.Handler:
+        formatter = ProcessorFormatter(
+            foreign_pre_chain=self._shared_processors + [self._enrich_stdlib_log],
+            processors=[ProcessorFormatter.remove_processors_meta, ConsoleRenderer(event_key=self._message_field)]
+        )
+
+        handler = logging.StreamHandler(sys.stdout)
+        handler.setFormatter(formatter)
+        handler.addFilter(ContextSetupFilter(self._application_name))
+
+        return handler
+
+    def _create_file_handler(self, log_file_path: str) -> RotatingFileHandler:
+        formatter = ProcessorFormatter(
+            foreign_pre_chain=self._shared_processors + [self._enrich_stdlib_log],
+            processors=[ProcessorFormatter.remove_processors_meta, JSONRenderer()]
+        )
+
+        self._ensure_directory_exists(log_file_path)
+
+        handler = RotatingFileHandler(log_file_path, maxBytes=self._max_bytes, backupCount=self._backup_count)
+        handler.setFormatter(formatter)
+        handler.addFilter(ContextSetupFilter(self._application_name))
+
+        return handler
+
+    def _ensure_directory_exists(self, log_file_path: str) -> None:
+        directory = os.path.dirname(log_file_path)
+
+        if not os.path.exists(directory):
+            os.makedirs(directory)
+
+    def _enrich_stdlib_log(self, _: logging.Logger, __: str, event_dict: dict[Any, Any]) -> dict[Any, Any]:
+        event_dict.update(event_dict['_record'].msg)
+
+        return event_dict