apv

- 🐍 advanced python logging 📔
git clone git://git.acid.vegas/apv.git
README.md (4990B)
      1 # Advanced Python Logging (APV)
      2 > Flexible & powerful logging solution for Python applications
      3 
      4 ![](./.screens/preview.png)
      5 
      6 ## Table of Contents
      7 - [Introduction](#introduction)
      8 - [Requirements](#requirements)
      9 - [Installation](#installation)
     10 - [Features](#features)
     11 - [Configuration Options](#configuration-options)
     12 - [Usage](#usage)
     13     - [Basic Console Logging](#basic-console-logging)
     14     - [Console Logging with Details](#console-logging-with-details)
     15     - [File Logging with Rotation](#file-logging-with-rotation)
     16     - [File Logging with Compression and JSON Format](#file-logging-with-compression-and-json-format)
     17     - [Mixing it all together](#mixing-it-all-together)
     18 
     19 ## Introduction
     20 APV emerged from a simple observation: despite the abundance of logging solutions, there's a glaring lack of standardization in application logging. APV is my response to this challenge – a logging library that doesn't aim to revolutionize the field, but rather to streamline it.
     21 
     22 ## Requirements
     23 - Python 3.10+
     24 
     25 ## Installation
     26 
     27 ### From PyPI
     28 ```bash
     29 pip install apv
     30 ```
     31 
     32 ### From Source
     33 ```bash
     34 git clone https://github.com/acidvegas/apv
     35 cd apv
     36 pip install .
     37 ```
     38 
     39 ## Features
     40 - **Console Logging with Colors**: Enhanced readability with colored log messages in the console.
     41 - **File Logging**: Write logs to files with support for log rotation based on size and number of backups.
     42 - **Log Compression**: Automatically compress old log files using gzip to save disk space.
     43 - **JSON Logging**: Output logs in JSON format for better structure and integration with log management systems.
     44 - **Detailed Log Messages**: Option to include module name, function name, and line number in log messages.
     45 
     46 ## Configuration Options
     47 
     48 The `setup_logging` function accepts the following keyword arguments to customize logging behavior:
     49 
     50 | Name              | Default                  | Description                                                                   |
     51 |-------------------|--------------------------|-------------------------------------------------------------------------------|
     52 | `level`           | `INFO`                   | The logging level. *(`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`)*        |
     53 | `date_format`     | `'%Y-%m-%d %H:%M:%S'`    | The date format for log messages.                                             |
     54 | `log_to_disk`     | `False`                  | Whether to log to disk.                                                       |
     55 | `max_log_size`    | `10*1024*1024` *(10 MB)* | The maximum size of log files before rotation *(in bytes)*.                   |
     56 | `max_backups`     | `7`                      | The maximum number of backup log files to keep.                               |
     57 | `log_file_name`   | `'app'`                  | The base name of the log file.                                                |
     58 | `json_log`        | `False`                  | Whether to log in JSON format.                                                |
     59 | `show_details`    | `False`                  | Whether to include module name, function name, & line number in log messages. |
     60 | `compress_backups`| `False`                  | Whether to compress old log files using gzip.                                 |
     61 
     62 ## Usage
     63 
     64 ### Basic Console Logging
     65 
     66 ```python
     67 import logging
     68 import apv
     69 
     70 # Set up basic console logging
     71 apv.setup_logging(level='INFO')
     72 
     73 logging.info('This is an info message.')
     74 logging.error('This is an error message.')
     75 ```
     76 
     77 ### Console Logging with Details
     78 
     79 ```python
     80 import logging
     81 import apv
     82 
     83 # Set up console logging with detailed information
     84 apv.setup_logging(level='DEBUG', show_details=True)
     85 
     86 logging.debug('Debug message with details.')
     87 ```
     88 
     89 ### File Logging with Rotation
     90 
     91 ```python
     92 import logging
     93 import apv
     94 
     95 # Set up file logging with log rotation
     96 apv.setup_logging(
     97     level='INFO',
     98     log_to_disk=True,
     99     max_log_size=10*1024*1024,  # 10 MB
    100     max_backups=5,
    101     log_file_name='application_log'
    102 )
    103 
    104 logging.info('This message will be logged to a file.')
    105 ```
    106 
    107 ### File Logging with Compression and JSON Format
    108 
    109 ```python
    110 import logging
    111 import apv
    112 
    113 # Set up file logging with compression and JSON format
    114 apv.setup_logging(
    115     level='DEBUG',
    116     log_to_disk=True,
    117     max_log_size=5*1024*1024,  # 5 MB
    118     max_backups=7,
    119     log_file_name='json_log',
    120     json_log=True,
    121     compress_backups=True
    122 )
    123 
    124 logging.debug('This is a debug message in JSON format.')
    125 ```
    126 
    127 ### Mixing it all together
    128 
    129 ```python
    130 import logging
    131 import apv
    132 
    133 # Set up logging to all handlers
    134 apv.setup_logging(
    135     level='DEBUG',
    136     log_to_disk=True,
    137     max_log_size=10*1024*1024,
    138     max_backups=7,
    139     log_file_name='app',
    140     json_log=True,
    141     compress_backups=True,
    142     show_details=True
    143 )
    144 ```
    145 
    146 ---
    147 
    148 ###### Mirrors: [acid.vegas](https://git.acid.vegas/apv) • [SuperNETs](https://git.supernets.org/acidvegas/apv) • [GitHub](https://github.com/acidvegas/apv) • [GitLab](https://gitlab.com/acidvegas/apv) • [Codeberg](https://codeberg.org/acidvegas/apv)