LogAnalyzer CLI

A powerful, TypeScript-based command-line tool for analyzing, filtering, and monitoring log files. Supports multiple log formats and provides insightful statistics and visualizations.

Features

• 🔍 Multiple Format Support: JSON, plain text, syslog, and auto-detection
• ⚡ Fast Filtering: Filter by level, time range, patterns, and more
• 📊 Statistical Analysis: Generate insights, error rates, and trends
• 🎨 Beautiful Output: Colored console output, JSON, CSV, and HTML exports
• 🔎 Pattern Search: Regex-based searching with case sensitivity options
• 📈 Real-time Monitoring: Tail and follow log files
• 🎯 Error Detection: Identify and group common errors
• 📝 Export Options: Save filtered results in multiple formats

Installation

From Source

# Clone or download the project
cd telementry

# Install dependencies
npm install

# Build the project
npm run build

# Link globally (optional)
npm link

# Now you can use 'telementry' from anywhere

As a Library

You can also use LogAnalyzer as a library in your Node.js/TypeScript projects:

import { LogParser, LogFilter, LogAnalyzer } from './src';

const parser = new LogParser();
const entries = parser.parseLines(logLines);
const analysis = LogAnalyzer.analyze(entries);

Usage

Basic Commands

Analyze Logs

Generate comprehensive statistics about your log file:

telementry analyze app.log
telementry analyze app.log --format json
telementry analyze app.log --output json > report.json
telementry analyze app.log --output html > report.html

Filter Logs

Filter logs by various criteria:

# Filter by log level
telementry filter app.log --level ERROR

# Filter by time range
telementry filter app.log --since "2h ago"
telementry filter app.log --since "2024-01-29" --until "2024-01-30"

# Filter by pattern
telementry filter app.log --pattern "database"
telementry filter app.log --exclude "health check"

# Combine filters
telementry filter app.log --level ERROR --since "1h ago" --limit 50

# Export filtered results
telementry filter app.log --level ERROR --output errors.json --format json
telementry filter app.log --pattern "timeout" --output timeouts.html --format html

Search Logs

Search for specific text:

# Basic search
telementry search app.log "connection timeout"

# Case-sensitive search
telementry search app.log "Error" --no-ignore-case

# Count matches only
telementry search app.log "database" --count

# Limit results
telementry search app.log "error" --limit 20

Show Statistics

Display detailed performance metrics:

telementry stats app.log
telementry stats app.log --format json

View Recent Logs

Show last N lines (like tail):

# Show last 100 lines (default)
telementry tail app.log

# Show last 50 lines
telementry tail app.log --lines 50

# Follow log file in real-time
telementry tail app.log --follow

Show Errors Only

Focus on errors and fatal logs:

# Show all errors
telementry errors app.log

# Show top 5 most common errors
telementry errors app.log --top 5

File Information

Get metadata about log file:

telementry info app.log

Supported Log Formats

JSON Format

{"timestamp":"2024-01-29T10:30:45.123Z","level":"ERROR","message":"Database connection failed"}

Plain Text Format

2024-01-29 10:30:45 ERROR Database connection failed
2024-01-29T10:30:45.123Z [ERROR] Database connection failed
10:30:45 ERROR: Database connection failed
ERROR: Database connection failed

Syslog Format

Jan 29 10:30:45 hostname app[12345]: Database connection failed

The tool automatically detects the format, or you can specify it with --format.

Time Specifications

The --since and --until options support multiple formats:

• Relative: 1h ago, 30m ago, 2d ago, 1w ago
• Absolute: 2024-01-29, 2024-01-29T10:30:00
• ISO 8601: 2024-01-29T10:30:45.123Z

Output Formats

• console (default): Colored, human-readable output
• json: Machine-readable JSON format
• csv: Comma-separated values
• html: Standalone HTML report

Integration Examples

As a Post-Processing Tool

# Analyze application logs after deployment
./deploy.sh && telementry analyze /var/log/app.log

# Check for errors in recent logs
telementry filter app.log --level ERROR --since "10m ago" --count

In CI/CD Pipelines

# .github/workflows/test.yml
- name: Analyze test logs
  run: |
    npm test 2>&1 | tee test.log
    telementry errors test.log --top 10

With Docker

FROM node:18
COPY telementry /usr/local/lib/telementry
RUN cd /usr/local/lib/telementry && npm install && npm run build
RUN ln -s /usr/local/lib/telementry/dist/index.js /usr/local/bin/telementry

# Use in your application
CMD ["sh", "-c", "node app.js 2>&1 | tee /var/log/app.log"]

As a Node.js Library

import { LogParser, LogFilter, LogAnalyzer } from 'telementry';
import * as fs from 'fs';

async function analyzeAppLogs() {
  const content = await fs.promises.readFile('app.log', 'utf-8');
  const lines = content.split('\n');
  
  const parser = new LogParser({ format: 'auto' });
  const entries = parser.parseLines(lines);
  
  // Filter errors from last hour
  const recentErrors = LogFilter.filter(entries, {
    level: LogLevel.ERROR,
    since: '1h ago'
  });
  
  // Analyze
  const analysis = LogAnalyzer.analyze(entries);
  console.log(`Error rate: ${analysis.errorRate.toFixed(2)}%`);
  
  // Find patterns
  const patterns = LogAnalyzer.findPatterns(recentErrors);
  console.log('Common error patterns:', patterns);
}

Monitoring Script

#!/bin/bash
# monitor.sh - Alert on high error rates

ERROR_COUNT=$(telementry filter app.log --level ERROR --since "5m ago" | wc -l)

if [ $ERROR_COUNT -gt 10 ]; then
  echo "⚠️  High error rate detected: $ERROR_COUNT errors in last 5 minutes"
  telementry errors app.log --top 5
  # Send alert (email, Slack, etc.)
fi

Architecture

telementry/
├── src/
│   ├── index.ts              # CLI entry point
│   ├── types.ts              # TypeScript interfaces
│   ├── parsers/
│   │   └── LogParser.ts      # Multi-format log parsing
│   ├── filters/
│   │   └── LogFilter.ts      # Filtering engine
│   ├── analyzers/
│   │   └── LogAnalyzer.ts    # Statistical analysis
│   ├── formatters/
│   │   └── Formatters.ts     # Output formatting
│   └── utils/
│       ├── helpers.ts        # Utility functions
│       └── FileReader.ts     # File I/O operations
├── package.json
└── tsconfig.json

Performance

• Streaming: Handles large files efficiently without loading everything into memory
• Fast Parsing: Optimized regex patterns for common log formats
• Minimal Dependencies: Only essential libraries included

API Reference

LogParser

const parser = new LogParser({ 
  format: 'auto',     // 'json' | 'plain' | 'syslog' | 'auto'
  multiline: true     // Handle multi-line logs (stack traces)
});

const entries = parser.parseLines(lines);

LogFilter

// Filter logs
const filtered = LogFilter.filter(entries, {
  level: LogLevel.ERROR,
  since: '1h ago',
  pattern: /database/i,
  limit: 100
});

// Search
const results = LogFilter.search(entries, 'connection timeout');

// Group by level
const byLevel = LogFilter.groupByLevel(entries);

// Group by hour
const byHour = LogFilter.groupByHour(entries);

LogAnalyzer

// Comprehensive analysis
const analysis = LogAnalyzer.analyze(entries);

// Calculate metrics
const metrics = LogAnalyzer.calculateMetrics(entries);

// Find anomalies
const anomalies = LogAnalyzer.detectAnomalies(entries);

// Detect patterns
const patterns = LogAnalyzer.findPatterns(entries);

Development

# Install dependencies
npm install

# Run in development mode
npm run dev -- analyze example.log

# Build
npm run build

# Run tests (if configured)
npm test

Contributing

Contributions are welcome! Feel free to submit issues and pull requests.

License

MIT

Tips & Tricks

1. Combine with other tools:

   telementry filter app.log --level ERROR | grep "database"

2. Generate daily reports:

   telementry analyze app.log --output html > report-$(date +%Y%m%d).html

3. Monitor multiple files:

   for log in /var/log/*.log; do
     echo "Analyzing $log"
     telementry stats "$log"
   done

4. Export for external analysis:

   telementry filter app.log --since "24h ago" --format csv > daily.csv

Support

For issues, questions, or feature requests, please open an issue on the project repository.