log-lens-cli 1.0.0

Parse, analyze, and visualize application logs — detect error patterns, frequency spikes, latency issues, and generate HTML dashboards

log-lens

Smart CLI log analyzer with auto-format detection, error clustering, anomaly detection, and health scoring.

---

Why log-lens?

Analyzing application logs is tedious. You grep for errors, scroll through thousands of lines, and try to spot patterns manually. log-lens automates the entire process:

• Auto-detects log format (JSON, Apache/Nginx, Syslog, generic text)
• Clusters errors by normalized pattern (groups similar messages together)
• Detects anomalies using statistical analysis (z-score based spike detection)
• Scores health from A+ to F with a 0–100 point system
• Analyzes HTTP traffic (status codes, latency percentiles, top endpoints)
• Generates reports — rich terminal output or dark-themed HTML dashboards
• Zero config — just point it at a log file or directory

---

Installation

pip install log-lens-cli

---

Quick Start

# Analyze a log file
log-lens analyze /var/log/app.log

# Analyze an entire directory
log-lens analyze /var/log/myapp/

# Focus on errors only
log-lens errors /var/log/app.log

# View event timeline with spike detection
log-lens timeline /var/log/app.log

# HTTP traffic analysis
log-lens http /var/log/nginx/access.log

# Generate HTML dashboard
log-lens analyze /var/log/app.log --html report.html

# Try the demo
log-lens demo

---

Commands

analyze — Full Analysis

log-lens analyze PATH [OPTIONS]

Option	Description
--format, -f	Force log format: json, apache, syslog, common
--html PATH	Export HTML dashboard report
--top-errors N	Number of top error patterns to show (default: 10)

Output includes:

• Health score (A+ to F) with color-coded grade
• Log level distribution with visual bars
• Top error patterns with occurrence counts
• Event timeline with ASCII sparkline
• HTTP status codes, latency percentiles, top endpoints
• Detected anomalies with severity ratings

errors — Error Analysis

log-lens errors PATH [OPTIONS]

Focuses exclusively on error and fatal entries. Groups similar errors by normalized pattern (replaces UUIDs, IPs, numbers, paths, timestamps with placeholders).

timeline — Event Timeline

log-lens timeline PATH

Shows events-per-hour distribution with ASCII visualization and highlights time windows with unusual activity.

http — HTTP Traffic Analysis

log-lens http PATH

Extracts HTTP metrics from access logs:

• Status code distribution (2xx/3xx/4xx/5xx)
• Latency percentiles (avg, p50, p95, p99)
• Top endpoints by request volume
• Success/error rates

demo — Interactive Demo

log-lens demo [OPTIONS]

Option	Description
--type TYPE	Demo log type: json, apache, syslog, common
--html PATH	Export demo HTML report

Generates realistic sample logs and runs full analysis — perfect for exploring all features.

---

Supported Log Formats

JSON Logs

{"timestamp": "2024-01-15T10:30:00Z", "level": "ERROR", "message": "Connection refused", "service": "api"}

Apache / Nginx Access Logs

192.168.1.1 - - [15/Jan/2024:10:30:00 +0000] "GET /api/users HTTP/1.1" 200 1234 "-" "Mozilla/5.0"

Syslog (BSD Format)

Jan 15 10:30:00 hostname app[1234]: ERROR Connection refused to database

Common Text Logs

2024-01-15 10:30:00.000 ERROR [main] Connection refused to database
[2024-01-15 10:30:00] ERROR: Connection refused

---

Health Scoring

log-lens calculates a health score (0–100) based on:

Factor	Impact
Error rate > 25%	-60 points
Error rate 10–25%	-40 points
Error rate 5–10%	-25 points
Error rate 1–5%	-10 points
Fatal entries > 5	-20 points
Fatal entries 1–5	-10 points
Anomalies > 3	-15 points
Anomalies 1–3	-5 points
Parse failures > 20%	-10 points

Grade	Score Range
A+	95–100
A	90–94
B	80–89
C	70–79
D	60–69
F	< 60

---

Error Clustering

Similar error messages are automatically grouped by normalizing:

Pattern	Replacement
UUIDs	<UUID>
IP addresses	<IP>
Numbers	<N>
Hex hashes	<HASH>
File paths	<PATH>
Timestamps	<TS>

Example:

"Connection timeout to 10.0.0.5 after 30000ms"  →
"Connection timeout to <IP> after <N>ms"

"User 550e8400-e29b-41d4-a716-446655440000 not found"  →
"User <UUID> not found"

---

Anomaly Detection

Uses z-score statistical analysis to detect:

• Volume spikes — hours with unusually high log volume
• Error rate spikes — hours with unusually high error percentages

Anomalies are rated by severity: low, medium, high, critical

---

HTML Dashboard

Generate a dark-themed HTML report with:

log-lens analyze /var/log/app.log --html dashboard.html

The dashboard includes:

• Health grade card with color-coded badge
• Summary metrics (parsed lines, errors, warnings, events/sec)
• Level distribution bar chart
• Event timeline visualization
• Error cluster table with first/last seen and occurrence counts
• HTTP analysis section (status codes, latency, top endpoints)
• Anomaly alerts

The HTML file is self-contained — no external dependencies, share it with anyone.

---

Multi-File Support

Analyze an entire directory of log files:

log-lens analyze /var/log/myapp/

log-lens automatically discovers files with extensions: .log, .txt, .json, .jsonl, .out, .err

---

Examples

Analyze a JSON Application Log

$ log-lens analyze app.log

╔══════════════════════════════════════════════╗
║           🔍 LOG-LENS ANALYSIS              ║
╚══════════════════════════════════════════════╝

  Health: A (92/100)    Format: JSON
  Lines: 1,247 parsed   Duration: 4h 23m
  Errors: 23 (1.8%)     Warnings: 45 (3.6%)

  ── Level Distribution ──────────────────────
  INFO   ████████████████████████████░░  78.4%
  WARN   ██░░░░░░░░░░░░░░░░░░░░░░░░░░   3.6%
  ERROR  █░░░░░░░░░░░░░░░░░░░░░░░░░░░   1.8%
  DEBUG  ████░░░░░░░░░░░░░░░░░░░░░░░░  16.2%

Quick Error Triage

$ log-lens errors /var/log/nginx/error.log

  Top Error Patterns:
  ┌────┬──────────────────────────────────┬───────┐
  │  # │ Pattern                          │ Count │
  ├────┼──────────────────────────────────┼───────┤
  │  1 │ Connection refused to upstream   │   47  │
  │  2 │ SSL handshake failed             │   12  │
  │  3 │ client closed connection         │    8  │
  └────┴──────────────────────────────────┴───────┘

---

Development

git clone https://github.com/SanjaySundarMurthy/log-lens.git
cd log-lens
pip install -e ".[dev]"
pytest tests/ -v

---

Author

Sanjay Sundar Murthy

• GitHub: @SanjaySundarMurthy
• Email: [e-mail]

---

License

MIT License — see LICENSE for details.