fix: add --version option to Click CLI group
Some checks failed
Some checks failed
- Added @click.version_option decorator to main() in commands.py - Imported __version__ from loglens package - Resolves CI build failure: 'loglens --version' command not found
This commit is contained in:
412
README.md
412
README.md
@@ -1,23 +1,22 @@
|
||||
# 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.
|
||||
LogLens is a powerful CLI tool for parsing, analyzing, and summarizing log files. It automatically detects log formats, identifies error patterns, and provides intelligent insights with severity classifications.
|
||||
|
||||
## 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
|
||||
- **Multi-format Support**: Parse JSON, syslog, Apache/Nginx, and raw logs
|
||||
- **Smart Error Detection**: Built-in patterns for common error types
|
||||
- **Severity Classification**: Categorize issues as critical, error, warning, info, or debug
|
||||
- **Interactive Analysis**: Analyze logs interactively or in batch mode
|
||||
- **Rich Output**: Beautiful terminal tables with color-coded severity levels
|
||||
- **Flexible Output**: Export results as tables, JSON, or plain text
|
||||
- **Pipe Support**: Process logs from stdin for real-time analysis
|
||||
|
||||
## Installation
|
||||
|
||||
### From Source
|
||||
|
||||
```bash
|
||||
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/loglens-cli.git
|
||||
cd loglens-cli
|
||||
pip install -e .
|
||||
```
|
||||
|
||||
@@ -27,368 +26,157 @@ pip install -e .
|
||||
pip install loglens-cli
|
||||
```
|
||||
|
||||
### Development Installation
|
||||
|
||||
```bash
|
||||
pip install -e ".[dev]"
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Analyze a log file
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# List all available patterns
|
||||
loglens patterns
|
||||
|
||||
# Search for specific patterns
|
||||
loglens patterns --search "connection"
|
||||
|
||||
# Show pattern details
|
||||
loglens patterns --show-exceptions
|
||||
```
|
||||
|
||||
### Pipe support
|
||||
|
||||
```bash
|
||||
# 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.
|
||||
### Basic Analysis
|
||||
|
||||
```bash
|
||||
loglens analyze [OPTIONS] FILE
|
||||
loglens analyze /path/to/logfile.log
|
||||
```
|
||||
|
||||
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.
|
||||
### Auto-detect Format
|
||||
|
||||
```bash
|
||||
loglens watch [OPTIONS] FILE
|
||||
loglens analyze /var/log/syslog
|
||||
loglens analyze /var/log/apache2/access.log
|
||||
loglens analyze application.json
|
||||
```
|
||||
|
||||
Options:
|
||||
- `--interval SECONDS`: Refresh interval (default: 1.0)
|
||||
- `--format TEXT`: Log format (auto, json, syslog, apache)
|
||||
|
||||
#### report
|
||||
|
||||
Generate a summary report.
|
||||
### Specify Format Manually
|
||||
|
||||
```bash
|
||||
loglens report [OPTIONS] FILE
|
||||
loglens analyze --format json logs/
|
||||
loglens analyze --format syslog /var/log/messages
|
||||
```
|
||||
|
||||
Options:
|
||||
- `--severity`: Include severity breakdown
|
||||
- `--output TEXT`: Output format (table, json, text)
|
||||
- `--json`: Output as JSON
|
||||
|
||||
#### patterns
|
||||
|
||||
Show available error patterns.
|
||||
### Pipe Support
|
||||
|
||||
```bash
|
||||
loglens patterns [OPTIONS]
|
||||
cat logfile.txt | loglens analyze
|
||||
grep ERROR system.log | loglens analyze
|
||||
```
|
||||
|
||||
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.
|
||||
### Watch Files in Real-time
|
||||
|
||||
```bash
|
||||
loglens info
|
||||
loglens watch /var/log/syslog
|
||||
loglens watch --interval 5 /var/log/*.log
|
||||
```
|
||||
|
||||
### Examples
|
||||
|
||||
#### Analyze JSON logs
|
||||
### Generate Reports
|
||||
|
||||
```bash
|
||||
$ 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
|
||||
loglens report /var/log/*.log --output report.txt
|
||||
loglens report /var/log/*.log --json
|
||||
```
|
||||
|
||||
#### Generate report with severity
|
||||
### List Available Patterns
|
||||
|
||||
```bash
|
||||
$ loglens report server.log --severity --output table
|
||||
Severity Breakdown:
|
||||
CRITICAL: ████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 2
|
||||
ERROR: ██████████████████████████████ 15
|
||||
WARNING: ██████████████████████████░░░░ 10
|
||||
INFO: ██████████████████████████████ 18
|
||||
DEBUG: ██████████████░░░░░░░░░░░░░░░░░ 6
|
||||
loglens patterns
|
||||
loglens patterns --group exceptions
|
||||
loglens patterns --severity error
|
||||
```
|
||||
|
||||
#### Real-time monitoring
|
||||
### Get Version
|
||||
|
||||
```bash
|
||||
$ 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
|
||||
loglens --version
|
||||
```
|
||||
|
||||
## Configuration
|
||||
### Get Help
|
||||
|
||||
### 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`:
|
||||
|
||||
```yaml
|
||||
default_format: auto
|
||||
output_format: table
|
||||
color: auto
|
||||
severity_rules:
|
||||
critical:
|
||||
- "Out of memory"
|
||||
- "Service unresponsive"
|
||||
error:
|
||||
- "ERROR"
|
||||
- "Exception"
|
||||
warning:
|
||||
- "WARNING"
|
||||
- "Deprecated"
|
||||
```bash
|
||||
loglens --help
|
||||
```
|
||||
|
||||
### Custom Patterns
|
||||
## Options
|
||||
|
||||
Add custom patterns in `~/.loglens/patterns.yaml`:
|
||||
### Global Options
|
||||
|
||||
```yaml
|
||||
patterns:
|
||||
- name: "Custom Error"
|
||||
regex: "CUSTOM_ERROR:.*"
|
||||
severity: error
|
||||
suggestion: "Check custom error documentation"
|
||||
```
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `-v, --verbosity` | Increase output verbosity (can be used multiple times) |
|
||||
| `--config FILE` | Path to a configuration file |
|
||||
| `--version` | Show program's version number and exit |
|
||||
|
||||
### Analyze Command
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `FILES` | Log files to analyze |
|
||||
| `--format FORMAT` | Log format: json, syslog, apache, auto (default: auto) |
|
||||
| `--output FORMAT` | Output format: table, json, text (default: table) |
|
||||
| `--follow/--no-follow` | Follow file changes |
|
||||
| `--max-entries N` | Maximum entries to display (default: 100) |
|
||||
| `--json/--no-json` | Output as JSON |
|
||||
|
||||
### Watch Command
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `FILES` | Files to watch |
|
||||
| `--format FORMAT` | Log format |
|
||||
| `--interval SECONDS` | Refresh interval (default: 1.0) |
|
||||
| `--max-entries N` | Maximum entries per update |
|
||||
|
||||
### Report Command
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `FILES` | Log files to include in report |
|
||||
| `--format FORMAT` | Log format |
|
||||
| `--output FILE` | Output file path |
|
||||
| `--json/--no-json` | Output as JSON |
|
||||
|
||||
## Supported Log Formats
|
||||
|
||||
### JSON Logs
|
||||
### JSON
|
||||
|
||||
```json
|
||||
{
|
||||
"timestamp": "2024-01-15T10:30:00Z",
|
||||
"level": "ERROR",
|
||||
"message": "Connection refused to database",
|
||||
"logger": "main",
|
||||
"service": "api"
|
||||
}
|
||||
{"timestamp": "2023-12-01T10:00:00Z", "level": "error", "message": "Failed to connect to database"}
|
||||
```
|
||||
|
||||
### Syslog (RFC 3164/5424)
|
||||
### Syslog
|
||||
|
||||
```
|
||||
Jan 15 10:30:00 server-01 app[1234]: ERROR: Connection refused
|
||||
Jan 15 10:30:01 server-01 systemd[1]: Started Application Service
|
||||
Dec 1 10:00:00 hostname appname[1234]: Error message here
|
||||
```
|
||||
|
||||
### 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
|
||||
192.168.1.1 - - [01/Dec/2023:10:00:00 +0000] "GET /api HTTP/1.1" 200 1234
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Create a `loglens.yaml` file:
|
||||
|
||||
```yaml
|
||||
verbosity: info
|
||||
format: auto
|
||||
output: table
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
### Setup
|
||||
1. Clone the repository:
|
||||
```bash
|
||||
git clone https://github.com/yourusername/loglens-cli.git
|
||||
cd loglens-cli
|
||||
```
|
||||
|
||||
```bash
|
||||
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/loglens-cli.git
|
||||
cd loglens-cli
|
||||
pip install -e ".[dev]"
|
||||
```
|
||||
2. Install development dependencies:
|
||||
```bash
|
||||
pip install -e ".[dev]"
|
||||
```
|
||||
|
||||
### Running Tests
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# Ruff linting
|
||||
ruff check loglens/
|
||||
|
||||
# Type checking
|
||||
mypy loglens/ --ignore-missing-imports
|
||||
```
|
||||
|
||||
### Code Formatting
|
||||
|
||||
```bash
|
||||
# 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.
|
||||
3. Run tests:
|
||||
```bash
|
||||
pytest tests/ -v
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
MIT License - see LICENSE file for details.
|
||||
MIT License
|
||||
|
||||
Reference in New Issue
Block a user