go-error-vault

A local-first error aggregation and trace analysis tool for developers who value privacy and simplicity.

🎯 Features

• Local-First: All data stored locally in SQLite database, no external services
• Multiple Collection Methods:
  • HTTP API for real-time error reporting
  • File-based collection for batch processing
  • CLI for manual error submission
• Smart Error Grouping: Automatically groups errors by signature (message + stack trace pattern)
• Frequency Tracking: Track error occurrences over time
• Trend Analysis: Visualize error trends with simple charts
• Web UI: Optional web interface for easy browsing
• CLI Tools: Comprehensive command-line interface
• Developer Ergonomics: Simple setup, intuitive commands, minimal configuration

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/BaseMax/go-error-vault.git
cd go-error-vault

# Build the binary
go build -o errorvault ./cmd/errorvault

# Install to PATH (optional)
sudo mv errorvault /usr/local/bin/

Basic Usage

# Initialize configuration
errorvault init

# Start the server (HTTP API + file collector + Web UI)
errorvault server

# Submit an error via CLI
errorvault submit --app myapp --message "Something went wrong" --stack "at main.go:42"

# List recent errors
errorvault list

# Show statistics
errorvault stats

# Show trends
errorvault trends

📖 Usage Guide

Server Mode

Start the error collection server:

errorvault server

This starts:

• HTTP API on http://localhost:8080/api/errors
• Web UI on http://localhost:8080
• File collector watching ~/.errorvault/incoming/

Submitting Errors

Via HTTP API

curl -X POST http://localhost:8080/api/errors \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Connection timeout",
    "stack": "at database.go:123\nat server.go:45",
    "app_name": "api-server",
    "app_version": "1.2.3",
    "metadata": {
      "user_id": "12345",
      "endpoint": "/api/users"
    }
  }'

Via File Drop

Create a JSON file in the watch directory:

cat > ~/.errorvault/incoming/error.json << EOF
{
  "message": "Database connection failed",
  "stack": "at db.go:100",
  "app_name": "backend",
  "app_version": "2.0.0"
}
EOF

The file will be automatically processed and archived.

Via CLI

errorvault submit \
  --app myapp \
  --message "Null pointer exception" \
  --stack "at utils.go:42" \
  --version "1.0.0"

Viewing Errors

List Error Groups

errorvault list

Output:

COUNT  APP      MESSAGE                      LAST SEEN
-----  ---      -------                      ---------
5      myapp    Connection timeout           2024-12-19 15:30:45
3      backend  Database connection failed   2024-12-19 14:20:12
1      api      Null pointer exception       2024-12-19 13:10:01

View Statistics

errorvault stats

Output:

Error Vault Statistics
======================
Total Errors:      9
Unique Signatures: 3
Errors (24h):      9
Applications:      3

View Trends

errorvault trends

Output:

Error Trends (Last 7 Days)
==========================

Connection timeout
  2024-12-18:   2 ████████████████
  2024-12-19:   5 ████████████████████████████████████████

Web UI

Visit http://localhost:8080 in your browser to:

• View dashboard with statistics
• Browse error groups
• Visualize trends over time

⚙️ Configuration

Configuration file is located at ~/.errorvault/config.json.

{
  "database_path": "~/.errorvault/errors.db",
  "watch_dirs": [
    "~/.errorvault/incoming"
  ],
  "collect_interval": 5000000000,
  "http_addr": ":8080",
  "enable_web": true,
  "data_dir": "~/.errorvault"
}

Configuration Options

• database_path: Path to SQLite database file
• watch_dirs: Directories to watch for error files
• collect_interval: File collection interval in nanoseconds (5s = 5000000000)
• http_addr: HTTP server address
• enable_web: Enable web UI
• data_dir: Base directory for all data

Custom Configuration

Set the ERRORVAULT_CONFIG environment variable to use a custom config file:

export ERRORVAULT_CONFIG=/path/to/config.json
errorvault server

🔒 Privacy & Security

• No External Services: All data stays on your machine
• Local SQLite Storage: Simple, portable, and private
• No Telemetry: We don't collect any usage data
• No Network Requirements: Works completely offline (except for HTTP API if you use it)

🏗️ Architecture

Components

1. Storage Layer (pkg/storage): SQLite-based persistence with grouping and aggregation
2. Models (pkg/models): Error report data structures and signature generation
3. Collector (pkg/collector): File-based error collection with automatic archival
4. API (pkg/api): HTTP REST API and web UI server
5. CLI (cmd/errorvault): Command-line interface

Error Signature

Errors are grouped by signature, which is generated from:

• Application name
• Error message
• First 500 characters of stack trace

This ensures similar errors are grouped together for better analysis.

🧪 Testing

Run tests:

go test ./...

Run tests with coverage:

go test -cover ./...

📦 Integration Examples

Go Application

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

type ErrorReport struct {
    Message    string                 `json:"message"`
    Stack      string                 `json:"stack"`
    AppName    string                 `json:"app_name"`
    AppVersion string                 `json:"app_version"`
    Metadata   map[string]interface{} `json:"metadata"`
}

func reportError(err error, stack string) {
    report := ErrorReport{
        Message:    err.Error(),
        Stack:      stack,
        AppName:    "my-go-app",
        AppVersion: "1.0.0",
    }
    
    data, _ := json.Marshal(report)
    http.Post("http://localhost:8080/api/errors", "application/json", bytes.NewBuffer(data))
}

Node.js Application

const axios = require('axios');

function reportError(err) {
    axios.post('http://localhost:8080/api/errors', {
        message: err.message,
        stack: err.stack,
        app_name: 'my-node-app',
        app_version: '1.0.0'
    }).catch(console.error);
}

process.on('uncaughtException', reportError);

Python Application

import requests
import traceback
import sys

def report_error(exc_type, exc_value, exc_traceback):
    error_data = {
        'message': str(exc_value),
        'stack': ''.join(traceback.format_tb(exc_traceback)),
        'app_name': 'my-python-app',
        'app_version': '1.0.0'
    }
    
    try:
        requests.post('http://localhost:8080/api/errors', json=error_data)
    except:
        pass

sys.excepthook = report_error

🛠️ Development

Project Structure

go-error-vault/
├── cmd/
│   └── errorvault/        # CLI application
├── pkg/
│   ├── api/               # HTTP server and web UI
│   ├── collector/         # File-based collection
│   ├── models/            # Data models
│   └── storage/           # Database layer
├── internal/
│   └── config/            # Configuration management
└── web/
    ├── templates/         # HTML templates (embedded in code)
    └── static/            # Static assets (embedded in code)

Building from Source

# Get dependencies
go mod download

# Build
go build -o errorvault ./cmd/errorvault

# Run tests
go test ./...

# Build with optimizations
go build -ldflags="-s -w" -o errorvault ./cmd/errorvault

📄 License

This project is licensed under the GPL-3.0 License - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📧 Contact

• GitHub: @BaseMax
• Repository: go-error-vault

🙏 Acknowledgments

Built with:

• mattn/go-sqlite3 - SQLite driver for Go
• google/uuid - UUID generation