LogScope

A self-hosted CloudWatch Logs troubleshooting dashboard with pattern detection and real-time alerting.

Features

• Interactive Dashboard: HTMX-powered real-time log streaming and filtering with instant search
• Local Cache: SQLite-based offline log analysis and historical pattern detection
• Pattern Recognition: Automated error pattern detection with configurable alert thresholds
• Easy Deployment: Docker-compose setup with simple AWS credential management
• REST API: Dropwizard-powered API for programmatic access to logs and analysis

Quick Start

Using Docker Compose

# Clone the repository
git clone https://github.com/yourorg/logscope.git
cd logscope

# Set AWS credentials
export AWS_ACCESS_KEY_ID=your-access-key
export AWS_SECRET_ACCESS_KEY=your-secret-key
export AWS_REGION=us-east-1

# Start LogScope
docker-compose up -d

# Open dashboard
open http://localhost:8080

Using Maven

# Build
mvn clean package

# Run
java -jar target/logscope-1.0-SNAPSHOT.jar server config.yml

Configuration

Edit config.yml to customize:

aws:
  region: us-east-1
  # Uses AWS credential chain (env vars, profile, IAM role)

database:
  url: jdbc:sqlite:./data/logscope.db

patternDetection:
  enabled: true
  analysisIntervalMinutes: 5

alerting:
  enabled: true

See docs/DEPLOYMENT.md for detailed configuration options.

API Documentation

LogScope provides a REST API for programmatic access:

# List log groups
curl http://localhost:8080/api/logs/groups

# Search logs
curl "http://localhost:8080/api/logs?search=ERROR&limit=100"

# Get detected patterns
curl http://localhost:8080/api/patterns

# List active alerts
curl "http://localhost:8080/api/alerts?status=ACTIVE"

See docs/API.md for complete API documentation.

Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  CloudWatch     │────▶│   LogScope      │────▶│   Dashboard     │
│  Logs           │     │   (Dropwizard)  │     │   (HTMX)        │
└─────────────────┘     └────────┬────────┘     └─────────────────┘
                                 │
                        ┌────────▼────────┐
                        │    SQLite       │
                        │    Cache        │
                        └─────────────────┘

Components

• LogService: Coordinates log fetching, caching, and retrieval
• CloudWatchLogsService: Handles AWS CloudWatch Logs API integration
• LogCacheService: Manages SQLite-based local log storage
• PatternDetectionService: Analyzes logs for recurring patterns
• AlertService: Monitors patterns and triggers alerts based on thresholds

Development

Prerequisites

• Java 17+
• Maven 3.8+
• Docker (optional)

Building

mvn clean package

Running Tests

mvn test

Project Structure

src/main/java/com/logscope/
├── LogScopeApplication.java    # Application entry point
├── LogScopeConfiguration.java  # Dropwizard configuration
├── config/
│   └── AwsConfiguration.java   # AWS settings
├── model/
│   ├── Alert.java              # Alert entity
│   ├── AlertThreshold.java     # Threshold configuration
│   ├── LogEvent.java           # Log event entity
│   └── LogPattern.java         # Detected pattern entity
├── resource/
│   ├── AlertResource.java      # /api/alerts endpoints
│   ├── LogResource.java        # /api/logs endpoints
│   └── PatternResource.java    # /api/patterns endpoints
└── service/
    ├── AlertService.java       # Alert management
    ├── CloudWatchLogsService.java  # AWS integration
    ├── LogCacheService.java    # SQLite caching
    ├── LogService.java         # Log orchestration
    └── PatternDetectionService.java  # Pattern analysis

Roadmap

• Web-based dashboard UI
• Slack/PagerDuty notifications
• Log export functionality
• Multi-region support
• Custom pattern definitions
• User authentication

Contributing

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

License

MIT License - see LICENSE for details.

Support

• Documentation: docs/
• Issues: GitHub Issues
• Discussions: GitHub Discussions