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.

Install

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

pip install -e .

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

Command line

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

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

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.