Metadata-Version: 2.4
Name: log-lens-cli
Version: 1.0.0
Summary: Parse, analyze, and visualize application logs — detect error patterns, frequency spikes, latency issues, and generate HTML dashboards
Project-URL: Homepage, https://github.com/SanjaySundarMurthy/log-lens
Project-URL: Repository, https://github.com/SanjaySundarMurthy/log-lens
Project-URL: Issues, https://github.com/SanjaySundarMurthy/log-lens/issues
Author-email: Sanjay S <sanjaysundarmurthy@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: analyzer,cli,dashboard,devops,errors,latency,log,monitoring,observability,parser
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Logging
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# log-lens

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

[![PyPI version](https://badge.fury.io/py/log-lens-cli.svg)](https://pypi.org/project/log-lens-cli/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

---

## 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

```bash
pip install log-lens-cli
```

---

## Quick Start

```bash
# 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

```bash
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

```bash
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

```bash
log-lens timeline PATH
```

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

### `http` — HTTP Traffic Analysis

```bash
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

```bash
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
```json
{"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:

```bash
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:

```bash
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
```bash
$ 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
```bash
$ 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

```bash
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](https://github.com/SanjaySundarMurthy)
- Email: sanjaysundarmurthy@gmail.com

---

## License

MIT License — see [LICENSE](LICENSE) for details.
