docs: add comprehensive README and monitoring stack

Author: adamxrodriguez

.dockerignore

@@ -0,0 +1,36 @@
+# Git
+.git
+.gitignore
+
+# Documentation
+README.md
+CHANGELOG.md
+
+# Docker
+Dockerfile
+docker-compose.yml
+.dockerignore
+
+# CI/CD
+.github
+
+# Environment
+.env
+.env.example
+
+# Data
+data/
+*.jsonl
+
+# IDE
+.vscode
+.idea
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Misc
+prometheus.yml
+grafana/
+

.gitignore

@@ -1,8 +1,8 @@
 # Generated by Cargo
 /target/
 
-# Lock files for binaries
-Cargo.lock
+# Lock files for libraries (but commit for binaries)
+# Cargo.lock
 
 # Environment variables
 .env

CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2024-01-15
+
+### Added
+
+- Initial release of Solana Event Listener
+- WebSocket JSON-RPC client for Solana blockchain
+- Support for `logsSubscribe` mode for monitoring program logs
+- Support for `accountSubscribe` mode for monitoring account changes
+- Prometheus metrics endpoint on `/metrics` with:
+  - `sol_events_total`: Counter for total events processed
+  - `sol_errors_total`: Counter for total errors encountered
+  - `sol_ws_connected`: Gauge for WebSocket connection status
+- JSONL file storage for event persistence
+- Automatic reconnection with exponential backoff (capped at 30s)
+- Graceful shutdown on CTRL+C
+- Configuration via environment variables and CLI arguments
+- Docker Compose setup with Prometheus and Grafana
+- Comprehensive CI/CD pipeline with GitHub Actions
+- Extensive test coverage for core functionality
+- Documentation with quickstart guide and examples
+
+### Technical Details
+
+- Built with Rust 2021 edition
+- Uses Tokio async runtime for high performance
+- Structured logging with tracing
+- Error handling with anyhow and thiserror
+- Clippy clean with `-D warnings`
+
+[0.1.0]: https://github.com/yourusername/solana-event-listener/releases/tag/v0.1.0
+

Dockerfile

@@ -0,0 +1,37 @@
+# Build stage
+FROM rust:1.75-slim as builder
+
+WORKDIR /app
+
+# Install dependencies
+RUN apt-get update && apt-get install -y \
+    pkg-config \
+    libssl-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy manifest files
+COPY Cargo.toml Cargo.lock ./
+
+# Copy source code
+COPY src ./src
+
+# Build for release
+RUN cargo build --release
+
+# Runtime stage
+FROM debian:bookworm-slim
+
+WORKDIR /app
+
+# Install runtime dependencies
+RUN apt-get update && apt-get install -y \
+    ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy binary from builder
+COPY --from=builder /app/target/release/solana-event-listener /app/
+
+EXPOSE 9108
+
+CMD ["/app/solana-event-listener"]
+

README.md

@@ -68,6 +68,26 @@ cargo run --release -- --mode account --accounts <PUBKEY1,PUBKEY2>
 cargo run --release -- --metrics-addr 0.0.0.0:9999
 ```
 
+### Docker Compose (Recommended for Production)
+
+Start with Prometheus and Grafana:
+
+```bash
+# Build and start all services
+docker-compose up -d
+
+# View logs
+docker-compose logs -f solana-event-listener
+
+# Stop services
+docker-compose down
+```
+
+Access dashboards:
+- **Prometheus**: http://localhost:9090
+- **Grafana**: http://localhost:3000 (default: `admin`/`admin`)
+- **Metrics**: http://localhost:9108/metrics
+
 ### Check Metrics
 
 ```bash
@@ -118,6 +138,27 @@ CLI flags override environment variables.
 {"timestamp":"2024-01-15T10:30:45Z","pubkey":"Address...","slot":12345,"lamports":1000000,"data":"base64..."}
 ```
 
+## Terminal Output Example
+
+Running in logs mode produces output like:
+
+```
+$ cargo run --release -- --mode logs --program-id ComputeBudget111111111111111111111111111111
+
+2024-01-15T10:30:45.123Z INFO Starting Solana Event Listener v0.1.0
+2024-01-15T10:30:45.125Z INFO Configuration loaded: mode=logs
+2024-01-15T10:30:45.126Z INFO Metrics registry initialized
+2024-01-15T10:30:45.127Z INFO Metrics server spawned on 0.0.0.0:9108
+2024-01-15T10:30:45.128Z INFO Storage initialized: ./events.jsonl
+2024-01-15T10:30:45.129Z INFO Starting logs subscription mode
+2024-01-15T10:30:45.130Z INFO Connecting to Solana WebSocket: wss://api.mainnet-beta.solana.com/
+2024-01-15T10:30:45.456Z INFO Connected to WebSocket
+2024-01-15T10:30:45.457Z INFO Sending subscription request for program: ComputeBudget111111111111111111111111111111
+2024-01-15T10:30:45.500Z INFO Subscribed to logs for program: ComputeBudget111111111111111111111111111111
+2024-01-15T10:30:46.200Z INFO Event: signature=5VeK..., slot=245000000, program=ComputeBudget111111111111111111111111111111, log_lines=3
+2024-01-15T10:30:47.100Z INFO Event: signature=7XmP..., slot=245000001, program=ComputeBudget111111111111111111111111111111, log_lines=2
+```
+
 ## Architecture
 
 ```

docker-compose.yml

@@ -0,0 +1,71 @@
+version: '3.8'
+
+services:
+  solana-event-listener:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: solana-event-listener
+    restart: unless-stopped
+    environment:
+      - WS_URL=${WS_URL:-wss://api.mainnet-beta.solana.com/}
+      - MODE=${MODE:-logs}
+      - PROGRAM_ID=${PROGRAM_ID}
+      - ACCOUNTS=${ACCOUNTS}
+      - COMMITMENT=${COMMITMENT:-finalized}
+      - EVENT_LOG_PATH=/data/events.jsonl
+      - METRICS_ADDR=0.0.0.0:9108
+      - RUST_LOG=${RUST_LOG:-info}
+    volumes:
+      - ./data:/data
+      - ./events.jsonl:/data/events.jsonl:rw
+    networks:
+      - monitoring
+    depends_on:
+      - prometheus
+
+  prometheus:
+    image: prom/prometheus:latest
+    container_name: prometheus
+    restart: unless-stopped
+    ports:
+      - "9090:9090"
+    volumes:
+      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
+      - prometheus-data:/prometheus
+    command:
+      - '--config.file=/etc/prometheus/prometheus.yml'
+      - '--storage.tsdb.path=/prometheus'
+      - '--storage.tsdb.retention.time=30d'
+      - '--web.console.libraries=/usr/share/prometheus/console_libraries'
+      - '--web.console.templates=/usr/share/prometheus/consoles'
+    networks:
+      - monitoring
+
+  grafana:
+    image: grafana/grafana:latest
+    container_name: grafana
+    restart: unless-stopped
+    ports:
+      - "3000:3000"
+    environment:
+      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD:-admin}
+      - GF_SECURITY_ADMIN_USER=${GRAFANA_USER:-admin}
+      - GF_USERS_ALLOW_SIGN_UP=false
+    volumes:
+      - grafana-data:/var/lib/grafana
+      - ./grafana/dashboards:/etc/grafana/provisioning/dashboards
+      - ./grafana/datasources:/etc/grafana/provisioning/datasources
+    networks:
+      - monitoring
+    depends_on:
+      - prometheus
+
+volumes:
+  prometheus-data:
+  grafana-data:
+
+networks:
+  monitoring:
+    driver: bridge
+

prometheus.yml

@@ -0,0 +1,9 @@
+global:
+  scrape_interval: 15s
+  evaluation_interval: 15s
+
+scrape_configs:
+  - job_name: 'solana-event-listener'
+    static_configs:
+      - targets: ['solana-event-listener:9108']
+