Metadata-Version: 2.4
Name: chu4hel-plogger
Version: 0.1.0
Summary: PLogger: A Python logging utility for CSV files with intelligent, metric-based rotation strategies to preserve significant data.
License: MIT
License-File: LICENSE
Author: Chu4hel
Author-email: 106600877+Chu4hel@users.noreply.github.com
Requires-Python: >=3.10
Classifier: License :: OSI Approved :: MIT License
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
Description-Content-Type: text/markdown

# PLogger: An Intelligent Logger for Preserving What Matters Most

[Русская версия README](docs/README_RU.md)

**PLogger** is a universal Python logger designed for collecting and analyzing performance metrics, experimental
results, or any other structured data. Its main feature is intelligent rotation strategies that allow you to preserve
the most unique and interesting records (outliers) while removing redundant data.

Unlike standard loggers that simply delete old entries, PLogger analyzes the data and retains those that stand out most
from the rest.

## Key Features

- **Intelligent Rotation**: Built-in strategies (`by_metric`, `by_group_metric`) to preserve the most significant data
  when the log limit is reached.
- **Thread-Safety**: Secure logging from multiple threads without the risk of data corruption.
- **Ease of Use**: A concise API for quick integration into any project.
- **CSV Logging**: Data is stored in a universal and easily readable CSV format.
- **Zero Configuration**: Automatic creation of log directories and files.

## Installation

```bash
pip install plogger
```

*(Note: After you publish the package to PyPI)*

## Basic Usage

```python
from pathlib import Path
from plogger import PLogger

# Initialize the logger
# Retain up to 100 entries, then remove the "least interesting" based on 'latency_ms' metric
logger = PLogger(
    log_path=Path("performance_logs.csv"),
    header=["request_id", "latency_ms", "status_code"],
    max_entries=100,
    rotation_strategy='by_metric',
    metric_column='latency_ms'
)

# Log regular requests
logger.log({"request_id": "abc-123", "latency_ms": 52, "status_code": 200})
logger.log({"request_id": "def-456", "latency_ms": 55, "status_code": 200})

# ...after many entries...

# Log an unusually long request.
# Thanks to the 'by_metric' strategy, this record is highly likely
# to be preserved in the log even after rotation.
logger.log({"request_id": "xyz-789", "latency_ms": 5300, "status_code": 500})
```

## Rotation Strategies

- `fifo`: Standard "first-in, first-out" strategy. Removes the oldest entry.
- `by_metric`: Finds a pair of entries with the smallest difference in a numerical metric (`metric_column`) and removes
  the older one from that pair. Ideal for preserving outliers and unique values.
- `by_group_metric`: First finds the largest group of entries (by `group_column`), and then applies the `by_metric`
  logic within that group. Useful when you need to analyze anomalies within the context of a specific category.

## License

The project is distributed under the [MIT License](LICENSE).

