Self-hosted log analytics and log explorer for ClickHouse and VictoriaLogs — single binary, multi-datasource, open source

Try Demo · Read Documentation · Announcement Blog Post

Logchef is a lightweight, self-hosted log analytics and observability platform for teams that want a strong query and control plane on top of existing log backends. It runs as a single binary and currently supports both ClickHouse and VictoriaLogs as datasource backends, providing a unified log explorer for exploration, saved queries, alerting, and access control — without reshaping how you store logs.

If you are evaluating VictoriaLogs specifically, start with the VictoriaLogs guide.

Features

• Query-first log exploration: Fast filtering with LogchefQL plus native SQL or LogsQL depending on the source.
• Live tail: Stream matching logs in real time from the explorer.
• Dashboards: Multi-panel views (time series, stat, table) on a shared time range, with a direct-manipulation grid editor.
• AI Query Assistant: Turn natural language into ClickHouse SQL instantly.
• Real-time alerting: Schedule rules and send email or webhook notifications.
• OIDC or local auth + RBAC: SSO out of the box, or run without an external identity provider using built-in email+password authentication.
• Datasource-first: Connect ClickHouse tables or VictoriaLogs instances without reshaping your storage layer.
• Single binary: One executable, no runtime dependencies.
• Pluggable metadata store: Zero-config SQLite by default; opt into Postgres for multi-replica high availability.
• Comprehensive metrics: Prometheus metrics for usage and performance.
• MCP integration: Model Context Protocol server for AI assistants (logchef-mcp).
• CLI: Query logs from your terminal with syntax highlighting and multi-context support (query, explain, histogram, tail, doctor, and more).

Quick Start

Docker

# Download the Docker Compose file
curl -LO https://raw.githubusercontent.com/mr-karan/logchef/refs/heads/main/deployment/docker/docker-compose.yml

# Start the services
docker compose up -d

Access the Logchef interface at http://localhost:8125.

CLI

Logchef includes a powerful CLI for querying logs directly from your terminal.

Install

Find the latest CLI version on the releases page, then set CLI_VERSION and download the build for your platform:

# Set to the latest cli-v* tag from the releases page (e.g. cli-v0.2.0)
CLI_VERSION=cli-vX.Y.Z
BASE=https://github.com/mr-karan/logchef/releases/download/$CLI_VERSION

# macOS (Apple Silicon)
curl -LO $BASE/logchef-darwin-arm64.tar.gz

# macOS (Intel)
curl -LO $BASE/logchef-darwin-amd64.tar.gz

# Linux (x86_64)
curl -LO $BASE/logchef-linux-amd64.tar.gz

# Linux (ARM64)
curl -LO $BASE/logchef-linux-arm64.tar.gz

# Extract and install
tar -xzf logchef-*.tar.gz
sudo mv logchef /usr/local/bin/

Usage

# Authenticate with your Logchef server
logchef auth --server https://logs.example.com

# Query logs with LogchefQL
logchef query 'level="error"' --since 1h

# See the generated SQL/LogsQL without running it
logchef explain 'level="error"'

# Counts over time (terminal bar chart)
logchef histogram 'level="error"' --since 1h

# Diagnose your setup (config, auth, server, defaults)
logchef doctor

# Execute a raw native query (SQL for ClickHouse, LogsQL for VictoriaLogs)
logchef sql "SELECT * FROM logs.app WHERE level='error' LIMIT 10"
logchef sql 'level:="error" | fields _time, _msg, service'

For full documentation, see the CLI Guide.

Documentation

For comprehensive documentation, including setup guides, configuration options, and API references, please visit logchef.app.

Contributing

We welcome contributions! To get started:

1. Development Setup: See our Development Setup Guide:

   just sqlc-generate
   just dev-docker
   just build

2. Read the Guidelines: Check CONTRIBUTING.md for detailed contribution guidelines

3. Find an Issue: Look for issues labeled good first issue or help wanted

4. Make Your Changes: Follow our coding standards and run just check before submitting

For questions or help, open an issue or start a discussion on GitHub.

Screenshots

License

Logchef is distributed under the terms of the AGPLv3 License.

Credits

The Logchef logo was designed by Namisha Katira.