LogLens CLI

A powerful CLI tool for parsing, analyzing, and providing intelligent summaries of log files. LogLens detects error patterns, highlights anomalies, and outputs human-readable reports with severity classifications and suggested fixes.

Features

• Multi-format Log Parsing: Support for JSON, syslog (RFC 3164/5424), and Apache/Nginx logs
• Error Pattern Detection: Built-in library of 20+ patterns for common errors (exceptions, stack traces, connection failures)
• Severity Classification: Automatic classification into Critical, Error, Warning, Info, and Debug levels
• Real-time Analysis: Pipe support for live log streaming with --follow mode
• Human-readable Reports: Beautiful table and text outputs with color coding
• Unix Tool Integration: Works seamlessly with grep, sed, and other command-line tools

Installation

From Source

git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/loglens-cli.git
cd loglens-cli
pip install -e .

Using pip

pip install loglens-cli

Development Installation

pip install -e ".[dev]"

Quick Start

Analyze a log file

# Auto-detect format and analyze
loglens analyze app.log

# Specify format explicitly
loglens analyze app.log --format json
loglens analyze app.log --format syslog
loglens analyze app.log --format apache

# Show detailed output
loglens analyze app.log --verbose

Watch logs in real-time

# Follow log file updates
loglens watch /var/log/app.log

# Follow with auto-refresh
loglens watch /var/log/app.log --interval 2

Generate summary reports

# Generate summary report
loglens report app.log

# Generate report with severity breakdown
loglens report app.log --severity

# JSON output for programmatic use
loglens report app.log --json

Check detected patterns

# List all available patterns
loglens patterns

# Search for specific patterns
loglens patterns --search "connection"

# Show pattern details
loglens patterns --show-exceptions

Pipe support

# Process logs from stdin
tail -f app.log | loglens analyze -

# Chain with grep
grep "ERROR" app.log | loglens analyze -

# Complex pipeline
cat logs/*.log | loglens analyze -

Usage

Commands

analyze

Parse and analyze log files.

loglens analyze [OPTIONS] FILE

Options:

• --format, -f TEXT: Log format (auto, json, syslog, apache)
• --output, -o TEXT: Output format (table, json, text)
• --verbose, -v: Show detailed analysis
• --json: Output as JSON

watch

Monitor a log file in real-time.

loglens watch [OPTIONS] FILE

Options:

• --interval SECONDS: Refresh interval (default: 1.0)
• --format TEXT: Log format (auto, json, syslog, apache)

report

Generate a summary report.

loglens report [OPTIONS] FILE

Options:

• --severity: Include severity breakdown
• --output TEXT: Output format (table, json, text)
• --json: Output as JSON

patterns

Show available error patterns.

loglens patterns [OPTIONS]

Options:

• --search TEXT: Search patterns by name
• --show-exceptions: Show exception patterns
• --show-http: Show HTTP error patterns
• --json: Output as JSON

info

Show tool information and configuration.

loglens info

Examples

Analyze JSON logs

$ loglens analyze application.json --format json
╭──────────────────────────────────────────────────────────────────────────────╮
│ Log Analysis Summary                                                         │
├──────────────────────────────────────────────────────────────────────────────┤
│ Total Lines:    150                                                          │
│ Parsed:         148 (98.7%)                                                  │
│ Errors Found:   12                                                           │
│ Severity:       2 Critical, 5 Error, 3 Warning, 2 Info                       │
╰──────────────────────────────────────────────────────────────────────────────╯

Top Errors:
  [CRITICAL] Database connection failure: 3 occurrences
  [ERROR] NullPointerException: 2 occurrences
  [WARNING] Deprecated API usage: 2 occurrences

Generate report with severity

$ loglens report server.log --severity --output table
Severity Breakdown:
  CRITICAL:  ████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  2
  ERROR:     ██████████████████████████████  15
  WARNING:   ██████████████████████████░░░░  10
  INFO:      ██████████████████████████████  18
  DEBUG:     ██████████████░░░░░░░░░░░░░░░░░  6

Real-time monitoring

$ loglens watch /var/log/app.log --interval 2
Watching: /var/log/app.log
Press Ctrl+C to stop...

Last 5 lines:
[2024-01-15 10:30:45] ERROR: Database connection failed
[2024-01-15 10:30:46] WARNING: High memory usage detected
[2024-01-15 10:30:47] INFO: Connection pool status: healthy
[2024-01-15 10:30:48] ERROR: Request timeout: /api/users
[2024-01-15 10:30:49] CRITICAL: Service unresponsive

Configuration

Environment Variables

Variable	Default	Description
LOGLEVEL	INFO	Default log level for output
LOGLENSMASK	false	Enable PII masking in logs
LOGLENSCOLOR	auto	Color output: auto, always, never

Configuration File

Create ~/.loglens/config.yaml:

default_format: auto
output_format: table
color: auto
severity_rules:
  critical:
    - "Out of memory"
    - "Service unresponsive"
  error:
    - "ERROR"
    - "Exception"
  warning:
    - "WARNING"
    - "Deprecated"

Custom Patterns

Add custom patterns in ~/.loglens/patterns.yaml:

patterns:
  - name: "Custom Error"
    regex: "CUSTOM_ERROR:.*"
    severity: error
    suggestion: "Check custom error documentation"

Supported Log Formats

JSON Logs

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

Syslog (RFC 3164/5424)

Jan 15 10:30:00 server-01 app[1234]: ERROR: Connection refused
Jan 15 10:30:01 server-01 systemd[1]: Started Application Service

Apache/Nginx

192.168.1.1 - - [15/Jan/2024:10:30:00 +0000] "GET /api/users HTTP/1.1" 200 1234
192.168.1.2 - - [15/Jan/2024:10:30:01 +0000] "POST /api/login HTTP/1.1" 401 567

Development

Setup

git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/loglens-cli.git
cd loglens-cli
pip install -e ".[dev]"

Running Tests

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=loglens --cov-report=html

# Run specific test suite
pytest tests/unit/ -v
pytest tests/integration/ -v

Linting

# Ruff linting
ruff check loglens/

# Type checking
mypy loglens/ --ignore-missing-imports

Code Formatting

# Black formatting
black loglens/ tests/

# Import sorting
isort loglens/ tests/

Project Structure

loglens-cli/
├── loglens/
│   ├── __init__.py
│   ├── __main__.py
│   ├── cli/
│   │   ├── __init__.py
│   │   ├── main.py
│   │   └── commands.py
│   ├── parsers/
│   │   ├── __init__.py
│   │   ├── base.py
│   │   ├── json_parser.py
│   │   ├── syslog_parser.py
│   │   ├── apache_parser.py
│   │   └── factory.py
│   ├── analyzers/
│   │   ├── __init__.py
│   │   ├── patterns.py
│   │   ├── severity.py
│   │   └── analyzer.py
│   ├── formatters/
│   │   ├── __init__.py
│   │   ├── base.py
│   │   ├── table_formatter.py
│   │   ├── json_formatter.py
│   │   └── text_formatter.py
│   └── config.yaml
├── tests/
│   ├── __init__.py
│   ├── conftest.py
│   ├── unit/
│   │   ├── __init__.py
│   │   ├── test_parsers.py
│   │   ├── test_analyzer.py
│   │   └── test_cli.py
│   ├── integration/
│   │   ├── __init__.py
│   │   └── test_end_to_end.py
│   └── fixtures/
├── pyproject.toml
├── README.md
├── LICENSE
└── .env.example

Error Patterns

LogLens includes patterns for:

• Exceptions: Python, Java, Node.js stack traces
• HTTP Errors: 5xx server errors, connection failures
• Database Errors: Connection refused, query timeouts
• System Errors: Out of memory, disk space, permissions
• Security Issues: Authentication failures, access denied
• Performance: High latency, slow queries, timeouts

Contributing

Contributions are welcome! Please read the contributing guidelines before submitting PRs.

License

MIT License - see LICENSE file for details.