Metadata-Version: 2.4
Name: peeklog
Version: 0.1.0
Summary: Streaming log-file analyzer with anomaly detection and rich terminal reports
Project-URL: Homepage, https://github.com/abhishek-tiwari-nitrr/Loglens
Project-URL: Issues, https://github.com/abhishek-tiwari-nitrr/Loglens/issues
Author-email: Abhishek Tiwari <abhishek.tiwari.nitrr@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: anomaly-detection,cli,log-analysis,logging,observability
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Logging
Requires-Python: >=3.11
Requires-Dist: rich>=13.0
Description-Content-Type: text/markdown

# LogLens

A streaming log-file analyzer for Python. Point it at a log file (plain or `.gz`) and get level breakdowns, top errors/warnings, minute/hour/day timelines, source stats, statistical anomaly detection, and a Rich terminal report either as a library or from the command line.

> **Status:** early / incomplete. This README only documents the parts that
> are actually implemented today. See [What's not finished yet](#whats-not-finished-yet).

## Install

Not yet published to PyPI. Install locally from the project directory:

```bash
pip install -e .
```

(or `pip install .` for a normal, non-editable install)

## Command line

```bash
loglens app.log                          # one-page summary
loglens app.log --full                   # full report: timeline, sources, samples...
loglens app.log --timeline               # timeline-only view
loglens app.log --level ERROR --level CRITICAL
loglens app.log --pattern "database"     # only lines matching a regex
loglens app.log --from 2026-08-22 --to "2026-08-22 12:00:00"
loglens app.log --json out.json          # also dump the full result as JSON
loglens app.log --no-anomalies           # skip anomaly detection
loglens app.log --no-progress            # disable the progress bar
```

Run `loglens --help` for the full list of options.

## Library

```python
from loglens import LogAnalyzer, AnomalyDetector, ReportGenerator

result = LogAnalyzer().analyze("app.log")
result.anomalies = [a.to_dict() for a in AnomalyDetector().detect(result)]

ReportGenerator().print_summary(result)   # or print_full_report(result)

print(result.error_rate)        # % of parsed lines that were ERROR/CRITICAL
print(result.summary_stats)     # compact dict of the headline numbers
result.to_dict()                # full, JSON-serializable result
```

Supported log formats are auto-detected line by line: ISO-8601 / Python `logging`-style application logs, Apache combined log format, Nginx error logs, and syslog. You can also pass a custom compiled regex with `level`, `time` and `message` named groups to `LogParser(custom_pattern=...)` for anything else.

### Logging helper

```python
from loglens import get_logger

log = get_logger("etl")
log.info("starting run")
```

Attaches a console handler plus a rotating, gzip-compressing file handler
(`./logs/<name>.log`) - see `loglens.constants.config` for the defaults.

## What's implemented

- `loglens.parser` - `LogParser`, `LogEntry`, `LogLevel`: streaming, multi-format parsing
- `loglens.analyzer` - `LogAnalyzer`, `AnalysisResult`: aggregation & stats
- `loglens.anomalies` - `AnomalyDetector`, `Anomaly`: z-score spikes, IQR outliers, silence gaps, error bursts
- `loglens.reports` - `ReportGenerator`: Rich terminal reports
- `loglens.logger` / `loglens.rotation` - configurable logging with compressed rotation
- `loglens.exceptions` - `ApplicationException`
- `loglens.cli` - the `loglens` command above

## What's not finished yet

These modules exist as placeholders in the source tree but have no implementation, and are **not** exposed from `import loglens`:

- `loglens.exporters` - JSON/CSV/HTML export helpers (use `result.to_dict()` + `json.dump` for now, or `loglens --json`)
- `loglens.frames` - pandas bridge
- `loglens.decorators` - instrumentation decorators for data-science code

## License

Apache-2.0 - see [LICENSE](LICENSE).
