{"id":17601022,"url":"https://github.com/acidvegas/apv","last_synced_at":"2025-04-12T12:11:43.903Z","repository":{"id":258991112,"uuid":"876056593","full_name":"acidvegas/apv","owner":"acidvegas","description":"🐍 advanced python logging 📔","archived":false,"fork":false,"pushed_at":"2024-12-12T02:44:12.000Z","size":43,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-26T06:51:11.792Z","etag":null,"topics":["aws","cloudwatch","color","color-log","color-logger","color-logging","graylog","logging"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/acidvegas.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-21T10:25:24.000Z","updated_at":"2024-12-12T02:44:15.000Z","dependencies_parsed_at":"2024-12-10T11:42:21.098Z","dependency_job_id":"8865f5ac-26d1-4682-94f2-77077a9352b8","html_url":"https://github.com/acidvegas/apv","commit_stats":{"total_commits":1,"total_committers":1,"mean_commits":1.0,"dds":0.0,"last_synced_commit":"1f928c4a2fa6ec4d39cc09c8bcefa1d4e7f469e9"},"previous_names":["acidvegas/apv"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acidvegas%2Fapv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acidvegas%2Fapv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acidvegas%2Fapv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acidvegas%2Fapv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/acidvegas","download_url":"https://codeload.github.com/acidvegas/apv/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248565074,"owners_count":21125417,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","cloudwatch","color","color-log","color-logger","color-logging","graylog","logging"],"created_at":"2024-10-22T12:07:49.636Z","updated_at":"2025-04-12T12:11:43.879Z","avatar_url":"https://github.com/acidvegas.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Advanced Python Logging (APV)\n\u003e Flexible \u0026 powerful logging solution for Python applications\n\n![](./.screens/preview.png)\n\n## Table of Contents\n- [Introduction](#introduction)\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Features](#features)\n- [Configuration Options](#configuration-options)\n- [Usage](#usage)\n    - [Basic Console Logging](#basic-console-logging)\n    - [Console Logging with Details](#console-logging-with-details)\n    - [File Logging with Rotation](#file-logging-with-rotation)\n    - [File Logging with Compression and JSON Format](#file-logging-with-compression-and-json-format)\n    - [Graylog Integration](#graylog-integration)\n    - [AWS CloudWatch Integration](#aws-cloudwatch-integration)\n    - [Mixing it all together](#mixing-it-all-together)\n\n## Introduction\nAPV 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.\n\n## Requirements\n- Python 3.10+\n\n## Installation\n\n### From PyPI\n```bash\n# Basic installation\npip install apv\n\n# With CloudWatch support\npip install apv[cloudwatch]\n\n# With ECS logging support\npip install apv[ecs]\n\n# With all optional dependencies\npip install \"apv[cloudwatch,ecs]\"\n```\n\n### From Source\n```bash\ngit clone https://github.com/acidvegas/apv\ncd apv\npip install .\n```\n\n## Features\n- **Console Logging with Colors**: Enhanced readability with colored log messages in the console.\n- **File Logging**: Write logs to files with support for log rotation based on size and number of backups.\n- **Log Compression**: Automatically compress old log files using gzip to save disk space.\n- **JSON Logging**: Output logs in JSON format for better structure and integration with log management systems.\n- **ECS Logging**: Output logs in ECS format for better integration with [Elasticsearch](https://www.elastic.co/elasticsearch/)\n- **Detailed Log Messages**: Option to include module name, function name, and line number in log messages.\n- **Graylog Integration**: Send logs to a [Graylog](https://www.graylog.org/) server using GELF over UDP.\n- **AWS CloudWatch Integration**: Send logs to [AWS CloudWatch Logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html).\n- **Customizable Logging Levels**: Set the logging level to control verbosity.\n\n## Configuration Options\n\nThe `setup_logging` function accepts the following keyword arguments to customize logging behavior:\n\n| Name                     | Default                  | Description                                                                          |\n|--------------------------|--------------------------|--------------------------------------------------------------------------------------|\n| `level`                  | `INFO`                   | The logging level. *(`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`)*               |\n| `date_format`            | `'%Y-%m-%d %H:%M:%S'`    | The date format for log messages.                                                    |\n| `log_to_disk`            | `False`                  | Whether to log to disk.                                                              |\n| `max_log_size`           | `10*1024*1024` *(10 MB)* | The maximum size of log files before rotation *(in bytes)*.                          |\n| `max_backups`            | `7`                      | The maximum number of backup log files to keep.                                      |\n| `log_file_name`          | `'app'`                  | The base name of the log file.                                                       |\n| `json_log`               | `False`                  | Whether to log in JSON format.                                                       |\n| `ecs_log`                | `False`                  | Whether to log in ECS format.                                                        |\n| `show_details`           | `False`                  | Whether to include module name, function name, \u0026 line number in log messages.        |\n| `compress_backups`       | `False`                  | Whether to compress old log files using gzip.                                        |\n| `enable_graylog`         | `False`                  | Whether to enable logging to a Graylog server.                                       |\n| `graylog_host`           | `None`                   | The Graylog server host. *(Required if `enable_graylog` is `True`)*                  |\n| `graylog_port`           | `None`                   | The Graylog server port. *(Required if `enable_graylog` is `True`)*                  |\n| `enable_cloudwatch`      | `False`                  | Whether to enable logging to AWS CloudWatch Logs.                                    |\n| `cloudwatch_group_name`  | `None`                   | The name of the CloudWatch log group. *(Required if `enable_cloudwatch` is `True`)*  |\n| `cloudwatch_stream_name` | `None`                   | The name of the CloudWatch log stream. *(Required if `enable_cloudwatch` is `True`)* |\n\n## Usage\n\n### Basic Console Logging\n\n```python\nimport logging\nimport apv\n\n# Set up basic console logging\napv.setup_logging(level='INFO')\n\nlogging.info('This is an info message.')\nlogging.error('This is an error message.')\n```\n\n### Console Logging with Details\n\n```python\nimport logging\nimport apv\n\n# Set up console logging with detailed information\napv.setup_logging(level='DEBUG', show_details=True)\n\nlogging.debug('Debug message with details.')\n```\n\n### File Logging with Rotation\n\n```python\nimport logging\nimport apv\n\n# Set up file logging with log rotation\napv.setup_logging(\n    level='INFO',\n    log_to_disk=True,\n    max_log_size=10*1024*1024,  # 10 MB\n    max_backups=5,\n    log_file_name='application_log'\n)\n\nlogging.info('This message will be logged to a file.')\n```\n\n### File Logging with Compression and JSON Format\n\n```python\nimport logging\nimport apv\n\n# Set up file logging with compression and JSON format\napv.setup_logging(\n    level='DEBUG',\n    log_to_disk=True,\n    max_log_size=5*1024*1024,  # 5 MB\n    max_backups=7,\n    log_file_name='json_log',\n    json_log=True,\n    compress_backups=True\n)\n\nlogging.debug('This is a debug message in JSON format.')\n```\n\n### Graylog Integration\n\n```python\nimport logging\nimport apv\n\n# Set up logging to Graylog server\napv.setup_logging(\n    level='INFO',\n    enable_graylog=True,\n    graylog_host='graylog.example.com',\n    graylog_port=12201\n)\n\nlogging.info('This message will be sent to Graylog.')\n```\n\n### AWS CloudWatch Integration\n\n```python\nimport logging\nimport apv\n\n# Set up logging to AWS CloudWatch Logs\napv.setup_logging(\n    level='INFO',\n    enable_cloudwatch=True,\n    cloudwatch_group_name='my_log_group',\n    cloudwatch_stream_name='my_log_stream'\n)\n\nlogging.info('This message will be sent to AWS CloudWatch.')\n```\n\n### ECS Logging\n\n```python\nimport logging\nimport apv\n\n# Set up ECS logging\napv.setup_logging(\n    level='INFO',\n    ecs_log=True\n)\n``` \n\n### Mixing it all together\n\n```python\nimport logging\nimport apv\n\n# Set up logging to all handlers\napv.setup_logging(\n    level='DEBUG',\n    log_to_disk=True,\n    max_log_size=10*1024*1024,\n    max_backups=7,\n    log_file_name='app',\n    json_log=True,\n    compress_backups=True,\n    enable_graylog=True,\n    graylog_host='graylog.example.com',\n    graylog_port=12201,\n    enable_cloudwatch=True,\n    cloudwatch_group_name='my_log_group',\n    cloudwatch_stream_name='my_log_stream',\n    show_details=True\n)\n```\n\n---\n\n###### 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)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facidvegas%2Fapv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Facidvegas%2Fapv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facidvegas%2Fapv/lists"}