apv

- 🐍 advanced python logging 📔
git clone git://git.acid.vegas/apv.git
README.md (8046B)
      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     - [Graylog Integration](#graylog-integration)
     18     - [AWS CloudWatch Integration](#aws-cloudwatch-integration)
     19     - [Mixing it all together](#mixing-it-all-together)
     20 
     21 ## Introduction
     22 APV emerged from a simple observation: despite the abundance of logging solutions, there's a glaring lack of standardization in application logging. As a developer deeply entrenched in Elasticsearch, AWS, and Graylog ecosystems, I found myself repeatedly grappling with inconsistent log formats and cumbersome integrations. APV is my response to this challenge – a logging library that doesn't aim to revolutionize the field, but rather to streamline it.
     23 
     24 ## Requirements
     25 - Python 3.10+
     26 
     27 ## Installation
     28 
     29 ### From PyPI
     30 ```bash
     31 # Basic installation
     32 pip install apv
     33 
     34 # With CloudWatch support
     35 pip install apv[cloudwatch]
     36 
     37 # With ECS logging support
     38 pip install apv[ecs]
     39 
     40 # With all optional dependencies
     41 pip install "apv[cloudwatch,ecs]"
     42 ```
     43 
     44 ### From Source
     45 ```bash
     46 git clone https://github.com/acidvegas/apv
     47 cd apv
     48 pip install .
     49 ```
     50 
     51 ## Features
     52 - **Console Logging with Colors**: Enhanced readability with colored log messages in the console.
     53 - **File Logging**: Write logs to files with support for log rotation based on size and number of backups.
     54 - **Log Compression**: Automatically compress old log files using gzip to save disk space.
     55 - **JSON Logging**: Output logs in JSON format for better structure and integration with log management systems.
     56 - **ECS Logging**: Output logs in ECS format for better integration with [Elasticsearch](https://www.elastic.co/elasticsearch/)
     57 - **Detailed Log Messages**: Option to include module name, function name, and line number in log messages.
     58 - **Graylog Integration**: Send logs to a [Graylog](https://www.graylog.org/) server using GELF over UDP.
     59 - **AWS CloudWatch Integration**: Send logs to [AWS CloudWatch Logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html).
     60 - **Customizable Logging Levels**: Set the logging level to control verbosity.
     61 
     62 ## Configuration Options
     63 
     64 The `setup_logging` function accepts the following keyword arguments to customize logging behavior:
     65 
     66 | Name                     | Default                  | Description                                                                          |
     67 |--------------------------|--------------------------|--------------------------------------------------------------------------------------|
     68 | `level`                  | `INFO`                   | The logging level. *(`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`)*               |
     69 | `date_format`            | `'%Y-%m-%d %H:%M:%S'`    | The date format for log messages.                                                    |
     70 | `log_to_disk`            | `False`                  | Whether to log to disk.                                                              |
     71 | `max_log_size`           | `10*1024*1024` *(10 MB)* | The maximum size of log files before rotation *(in bytes)*.                          |
     72 | `max_backups`            | `7`                      | The maximum number of backup log files to keep.                                      |
     73 | `log_file_name`          | `'app'`                  | The base name of the log file.                                                       |
     74 | `json_log`               | `False`                  | Whether to log in JSON format.                                                       |
     75 | `ecs_log`                | `False`                  | Whether to log in ECS format.                                                        |
     76 | `show_details`           | `False`                  | Whether to include module name, function name, & line number in log messages.        |
     77 | `compress_backups`       | `False`                  | Whether to compress old log files using gzip.                                        |
     78 | `enable_graylog`         | `False`                  | Whether to enable logging to a Graylog server.                                       |
     79 | `graylog_host`           | `None`                   | The Graylog server host. *(Required if `enable_graylog` is `True`)*                  |
     80 | `graylog_port`           | `None`                   | The Graylog server port. *(Required if `enable_graylog` is `True`)*                  |
     81 | `enable_cloudwatch`      | `False`                  | Whether to enable logging to AWS CloudWatch Logs.                                    |
     82 | `cloudwatch_group_name`  | `None`                   | The name of the CloudWatch log group. *(Required if `enable_cloudwatch` is `True`)*  |
     83 | `cloudwatch_stream_name` | `None`                   | The name of the CloudWatch log stream. *(Required if `enable_cloudwatch` is `True`)* |
     84 
     85 ## Usage
     86 
     87 ### Basic Console Logging
     88 
     89 ```python
     90 import logging
     91 import apv
     92 
     93 # Set up basic console logging
     94 apv.setup_logging(level='INFO')
     95 
     96 logging.info('This is an info message.')
     97 logging.error('This is an error message.')
     98 ```
     99 
    100 ### Console Logging with Details
    101 
    102 ```python
    103 import logging
    104 import apv
    105 
    106 # Set up console logging with detailed information
    107 apv.setup_logging(level='DEBUG', show_details=True)
    108 
    109 logging.debug('Debug message with details.')
    110 ```
    111 
    112 ### File Logging with Rotation
    113 
    114 ```python
    115 import logging
    116 import apv
    117 
    118 # Set up file logging with log rotation
    119 apv.setup_logging(
    120     level='INFO',
    121     log_to_disk=True,
    122     max_log_size=10*1024*1024,  # 10 MB
    123     max_backups=5,
    124     log_file_name='application_log'
    125 )
    126 
    127 logging.info('This message will be logged to a file.')
    128 ```
    129 
    130 ### File Logging with Compression and JSON Format
    131 
    132 ```python
    133 import logging
    134 import apv
    135 
    136 # Set up file logging with compression and JSON format
    137 apv.setup_logging(
    138     level='DEBUG',
    139     log_to_disk=True,
    140     max_log_size=5*1024*1024,  # 5 MB
    141     max_backups=7,
    142     log_file_name='json_log',
    143     json_log=True,
    144     compress_backups=True
    145 )
    146 
    147 logging.debug('This is a debug message in JSON format.')
    148 ```
    149 
    150 ### Graylog Integration
    151 
    152 ```python
    153 import logging
    154 import apv
    155 
    156 # Set up logging to Graylog server
    157 apv.setup_logging(
    158     level='INFO',
    159     enable_graylog=True,
    160     graylog_host='graylog.example.com',
    161     graylog_port=12201
    162 )
    163 
    164 logging.info('This message will be sent to Graylog.')
    165 ```
    166 
    167 ### AWS CloudWatch Integration
    168 
    169 ```python
    170 import logging
    171 import apv
    172 
    173 # Set up logging to AWS CloudWatch Logs
    174 apv.setup_logging(
    175     level='INFO',
    176     enable_cloudwatch=True,
    177     cloudwatch_group_name='my_log_group',
    178     cloudwatch_stream_name='my_log_stream'
    179 )
    180 
    181 logging.info('This message will be sent to AWS CloudWatch.')
    182 ```
    183 
    184 ### ECS Logging
    185 
    186 ```python
    187 import logging
    188 import apv
    189 
    190 # Set up ECS logging
    191 apv.setup_logging(
    192     level='INFO',
    193     ecs_log=True
    194 )
    195 ``` 
    196 
    197 ### Mixing it all together
    198 
    199 ```python
    200 import logging
    201 import apv
    202 
    203 # Set up logging to all handlers
    204 apv.setup_logging(
    205     level='DEBUG',
    206     log_to_disk=True,
    207     max_log_size=10*1024*1024,
    208     max_backups=7,
    209     log_file_name='app',
    210     json_log=True,
    211     compress_backups=True,
    212     enable_graylog=True,
    213     graylog_host='graylog.example.com',
    214     graylog_port=12201,
    215     enable_cloudwatch=True,
    216     cloudwatch_group_name='my_log_group',
    217     cloudwatch_stream_name='my_log_stream',
    218     show_details=True
    219 )
    220 ```
    221 
    222 ---
    223 
    224 ###### 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)