{"id":45847827,"url":"https://github.com/mchurichi/peek","last_synced_at":"2026-03-11T02:03:46.076Z","repository":{"id":339186332,"uuid":"1160391350","full_name":"mchurichi/peek","owner":"mchurichi","description":"Minimalist, lightweight observability inspector for logs. Turn service log streams into human-readable traces for local observability in daily workflows.","archived":false,"fork":false,"pushed_at":"2026-03-06T01:51:25.000Z","size":3672,"stargazers_count":1,"open_issues_count":4,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-06T05:18:18.007Z","etag":null,"topics":["developer-tools","logging","logs","lucene","observability"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mchurichi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-17T22:09:10.000Z","updated_at":"2026-02-28T17:58:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mchurichi/peek","commit_stats":null,"previous_names":["mchurichi/peek"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/mchurichi/peek","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mchurichi%2Fpeek","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mchurichi%2Fpeek/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mchurichi%2Fpeek/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mchurichi%2Fpeek/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mchurichi","download_url":"https://codeload.github.com/mchurichi/peek/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mchurichi%2Fpeek/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30367810,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T21:41:54.280Z","status":"online","status_checked_at":"2026-03-11T02:00:07.027Z","response_time":84,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["developer-tools","logging","logs","lucene","observability"],"created_at":"2026-02-27T02:16:27.757Z","updated_at":"2026-03-11T02:03:46.068Z","avatar_url":"https://github.com/mchurichi.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Peek\n\n[![CI](https://github.com/mchurichi/peek/actions/workflows/ci-build-test.yml/badge.svg?branch=main)](https://github.com/mchurichi/peek/actions/workflows/ci-build-test.yml?query=branch%3Amain)\n\nA minimalist, dev-first CLI log collector and web UI. Pipe logs into `peek`, store them locally, and query them through a real-time web dashboard.\n\n```bash\n$ kubectl logs -l app=frontdesk -w | peek\n\n2026/02/18 02:30:20 Starting collect mode...\n2026/02/18 02:30:20 Web UI available at http://localhost:8080\n2026/02/18 02:30:20 Starting server on http://localhost:8080\n```\n\n![Peek — Lucene query filtering errors and warnings across microservices](docs/screenshot.png)\n\n## Features\n\n- 🚀 **Single binary** - No external dependencies\n- 📊 **Structured log support** - Auto-detects JSON and logfmt (key-value) formats\n- 💾 **Local storage** - BadgerDB with configurable retention\n- 🔍 **Lucene queries** - Powerful search syntax\n- ⚡ **Real-time updates** - WebSocket streaming\n- 🎨 **Web UI** - Clean, minimal interface\n- ⚙️ **Configurable** - TOML config + CLI flags\n\n## Installation\n\n```bash\n# Linux quick install (latest) to ~/.local/bin\ncurl -fsSL https://raw.githubusercontent.com/mchurichi/peek/main/scripts/get-peek.sh | sh -s -- install\n\n# Linux quick install (specific version)\ncurl -fsSL https://raw.githubusercontent.com/mchurichi/peek/main/scripts/get-peek.sh | sh -s -- install --version v0.1.0\n\n# Linux system install to /usr/local/bin (uses sudo when needed)\ncurl -fsSL https://raw.githubusercontent.com/mchurichi/peek/main/scripts/get-peek.sh | sh -s -- install --system\n\n# Linux uninstall (remove binary only)\ncurl -fsSL https://raw.githubusercontent.com/mchurichi/peek/main/scripts/get-peek.sh | sh -s -- uninstall\n\n# Linux uninstall + remove all ~/.peek data/config\ncurl -fsSL https://raw.githubusercontent.com/mchurichi/peek/main/scripts/get-peek.sh | sh -s -- uninstall --purge\n\n# Linux uninstall + purge non-interactively\ncurl -fsSL https://raw.githubusercontent.com/mchurichi/peek/main/scripts/get-peek.sh | sh -s -- uninstall --purge --force\n\n# Build from source\ngit clone https://github.com/mchurichi/peek.git\ncd peek\ngo build -o peek ./cmd/peek\n\n# Or install directly\ngo install github.com/mchurichi/peek/cmd/peek@latest\n```\n\n## Quick Start\n\n### Collect \u0026 View in Real Time (Fresh Mode)\n\nPipe logs from any source — the web UI starts automatically and shows only logs from the current session:\n\n```bash\n# From a file (fresh mode - only shows logs from this session)\ncat application.log | peek\n\n# From a running process\ndocker logs my-container | peek\n\n# From kubectl\nkubectl logs my-pod -f | peek\n\n# With a custom port\nkubectl logs my-pod -f | peek --port 8081\n\n# Show all historic logs alongside new ones\nkubectl logs my-pod -f | peek --all\n```\n\nThe browser auto-opens to `http://localhost:8080`. Logs stream to the UI in real time via WebSocket. \n\n**Fresh Mode (default)**: By default, the UI only shows logs from the current piping session. Historic logs in the database are filtered out. This is ideal for live debugging.\n\n**All Mode (`--all`)**: Use the `--all` flag to see all stored logs alongside newly piped ones.\n\nAfter stdin closes, the server stays alive so you can keep browsing — press `Ctrl+C` to exit.\n\n### Browse Previously Collected Logs\n\nStart the web UI in standalone mode to browse all stored logs:\n\n```bash\npeek\n```\n\n### Database Management\n\nView and manage your log database:\n\n```bash\n# Show database statistics\npeek db stats\n\n# Delete all logs (with confirmation)\npeek db clean\n\n# Delete all logs (skip confirmation)\npeek db clean --force\n\n# Delete logs older than 7 days\npeek db clean --older-than 7d --force\n\n# Delete only DEBUG level logs\npeek db clean --level DEBUG --force\n```\n\n## Usage\n\n### Version\n\nPrint the build version (supports `-ldflags` injection at build/release time):\n\n```bash\npeek version\n```\n\n### Collect Mode\n\nCollects logs from stdin and starts an embedded web UI for real-time viewing:\n\n```bash\ncat app.log | peek [OPTIONS]\n\nOptions:\n  --all                  Show all historic logs alongside new ones (default: fresh mode)\n  --config FILE          Path to config file (default: ~/.peek/config.toml)\n  --db-path PATH         Database path (default: ~/.peek/db)\n  --retention-size SIZE  Max storage (e.g., 1GB, 500MB)\n  --retention-days DAYS  Max age of logs (default: 7)\n  --format FORMAT        auto | json | logfmt (default: auto)\n  --port PORT            HTTP port for embedded web UI (default: 8080)\n  --no-browser           Don't auto-open browser\n  --help                 Show help\n```\n\n### Standalone Mode\n\nBrowse previously collected logs (no stdin required):\n\n```bash\npeek [OPTIONS]\n\nOptions:\n  --config FILE      Path to config file (default: ~/.peek/config.toml)\n  --db-path PATH    Database path (default: ~/.peek/db)\n  --port PORT       HTTP port (default: 8080)\n  --no-browser      Don't auto-open browser\n  --help             Show help\n```\n\n### Database Management\n\nManage your log database:\n\n```bash\n# Show database statistics\npeek db stats [OPTIONS]\n\n# Delete logs from database\npeek db clean [OPTIONS]\n\nOptions for 'db stats':\n  --config FILE      Path to config file (default: ~/.peek/config.toml)\n  --db-path PATH     Database path (default: ~/.peek/db)\n\nOptions for 'db clean':\n  --config FILE          Path to config file (default: ~/.peek/config.toml)\n  --db-path PATH         Database path (default: ~/.peek/db)\n  --older-than DURATION  Delete logs older than duration (e.g., 24h, 7d, 2w)\n  --level LEVEL          Delete only logs matching level (e.g., DEBUG)\n  --force                Skip confirmation prompt\n```\n\n**Examples:**\n\n```bash\n# View database info\npeek db stats\n# Output:\n# Database Statistics\n# ===================\n# Path:          /home/user/.peek/db\n# Total logs:    14,382\n# Database size: 238.45 MB\n# Oldest entry:  2026-02-01T10:30:45Z\n# Newest entry:  2026-02-18T22:15:30Z\n\n# Delete all logs (with confirmation)\npeek db clean\n\n# Delete all logs (skip confirmation)\npeek db clean --force\n\n# Delete logs older than 7 days\npeek db clean --older-than 7d --force\n\n# Delete only DEBUG level logs\npeek db clean --level DEBUG --force\n```\n\n## Query Syntax\n\nPeek supports ElasticSearch Lucene query syntax:\n\n```\n# Keyword search\nerror timeout\n\n# Field-based queries\nlevel:ERROR\nservice:api\nuser_id:123\n\n# Boolean operators\nlevel:ERROR AND service:api\nlevel:ERROR OR level:WARN\nNOT level:DEBUG\n\n# Wildcards\nmessage:*timeout*\nservice:api*\n\n# Quoted phrases\nmessage:\"connection refused\"\n\n# Complex queries\n(level:ERROR OR level:CRITICAL) AND service:api\n```\n\n## Log Formats\n\nPeek supports structured log formats with auto-detection. The JSON parser accepts common field names (`timestamp`/`time`, `message`/`msg`, `level`/`severity`).\n\n### JSON\n```json\n{\n  \"timestamp\": \"2026-02-17T10:30:45Z\",\n  \"level\": \"ERROR\",\n  \"message\": \"Connection timeout\",\n  \"service\": \"api\",\n  \"attempt\": 3\n}\n```\n\n### Logfmt (key-value pairs)\n```\ntime=2026-02-17T10:30:45Z level=ERROR msg=\"Connection timeout\" service=api attempt=3\n```\n\n## Configuration\n\nDefault config location: `~/.peek/config.toml`\n\n```toml\n[storage]\nretention_size = \"1GB\"\nretention_days = 7\ndb_path = \"~/.peek/db\"\n\n[server]\nport = 8080\nauto_open_browser = true\n\n[parsing]\nformat = \"auto\"\nauto_timestamp = true\n```\n\nCLI flags override config file values.\n\n## Architecture \u0026 API\n\nPeek runs as a single process that reads stdin, stores logs locally, and serves a web UI.\nFull architecture and API details are in [docs/README.md](docs/README.md).\n\n## Examples\n\n### Collect and view in real time\n\n```bash\n# Collect + view in one command\nkubectl logs my-pod -f | peek --port 8081\n\n# Browse logs after collection ends\npeek\n\n# Collect more logs (same database)\ncat another-app.log | peek\n```\n\n### Filter and search\n\n```bash\n# In the web UI:\nlevel:ERROR                    # Show only errors\nservice:api                    # Filter by service\nlevel:ERROR AND service:auth   # Combine filters\nmessage:*timeout*              # Wildcard search\n```\n\n## Development\n\n### Requirements\n\n- Go 1.24+\n- BadgerDB v4\n- Gorilla WebSocket\n\n### Build\n\n```bash\ngo build -o peek ./cmd/peek\n```\n\n### Project Structure\n\n```\npeek/\n├── cmd/peek/           # Main entry point\n├── pkg/\n│   ├── parser/         # Log format parsers\n│   ├── storage/        # BadgerDB storage layer\n│   ├── query/          # Lucene query engine\n│   └── server/         # HTTP server, WebSocket, embedded UI (index.html)\n├── internal/\n│   └── config/         # Configuration management\n├── scripts/\n│   └── get-peek.sh     # Linux install/uninstall script for GitHub release binaries\n└── go.mod\n```\n\n## Performance \u0026 Roadmap\n\nPerformance notes and the roadmap live in [docs/README.md](docs/README.md).\n\n## Contributing\n\nContributions welcome! Please open an issue first to discuss changes.\n\n## License\n\nApache-2.0 - see [LICENSE](LICENSE) for details\n\n## Credits\n\nBuilt with:\n- [BadgerDB](https://github.com/dgraph-io/badger) - Embedded key-value database\n- [Gorilla WebSocket](https://github.com/gorilla/websocket) - WebSocket library\n- [BurntSushi/toml](https://github.com/BurntSushi/toml) - TOML parser\n\n---\n\n**Local-first. Security-first. Minimal. Modular.**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmchurichi%2Fpeek","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmchurichi%2Fpeek","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmchurichi%2Fpeek/lists"}