Getting Started
TraceHouse is under heavy development and breaking changes are expected. Saved connections, dashboards, and queries are stored in your browser and may be affected by updates.
Choose How to Run TraceHouse
TraceHouse is available as a Grafana app plugin, a standalone application, or a single HTML file, so you can choose the option that best fits your environment and deployment requirements.
| Grafana App Plugin | Standalone App | Single HTML File | |
|---|---|---|---|
| Best for | Teams already using Grafana | Local use or a dedicated deployment | Trying or sharing TraceHouse |
| Additional requirements | Grafana and a ClickHouse data source | A supported Linux or Apple Silicon macOS host | A CORS-enabled ClickHouse HTTP endpoint |
| ClickHouse CORS required | No | No - proxy included | Yes |
| Install from | Grafana plugin catalog | GitHub release | Online or GitHub release |
All options require a modern web browser. If you are unsure whether your ClickHouse endpoint supports browser connections, see Connecting to ClickHouse for an explanation of CORS and the available proxy options.
If you already use Grafana, the Grafana app plugin is the easiest option. Otherwise, use the standalone app unless your ClickHouse HTTP endpoint already allows browser requests.
Option 1: Install the Grafana App Plugin
The Grafana app uses your existing Grafana ClickHouse data source. Grafana handles credentials, connectivity, and CORS.
- Install and configure the Grafana ClickHouse data source plugin if you do not already have a ClickHouse data source.
- Install TraceHouse from the Grafana plugin catalog.
- In Grafana, open Administration → Plugins and data → Plugins, select TraceHouse, and enable it.
- Open TraceHouse from the Grafana sidebar and select your ClickHouse data source.
The catalog page lists the currently supported Grafana versions.
Option 2: Run the Standalone App
The standalone app packages the TraceHouse frontend and its ClickHouse proxy into one executable. The proxy forwards browser requests to ClickHouse server-side, so the ClickHouse endpoint does not need to allow direct browser connections.
Download the archive for your platform from the latest GitHub release:
| Platform | Download |
|---|---|
| Linux x86_64 | tracehouse-x86_64-unknown-linux-gnu.tar.gz |
| Linux ARM64 | tracehouse-aarch64-unknown-linux-gnu.tar.gz |
| macOS Apple Silicon | tracehouse-aarch64-apple-darwin.tar.gz |
Or download it from the command line with curl. Set PLATFORM for your system:
# Linux x86_64
PLATFORM=x86_64-unknown-linux-gnu
# Linux ARM64
# PLATFORM=aarch64-unknown-linux-gnu
# macOS Apple Silicon
# PLATFORM=aarch64-apple-darwin
curl -fLO "https://github.com/dmkskd/tracehouse/releases/latest/download/tracehouse-${PLATFORM}.tar.gz"
tar -xzf "tracehouse-${PLATFORM}.tar.gz"
./tracehouse-${PLATFORM}/tracehouse
Open http://localhost:8990, add your ClickHouse connection, and connect.
The standalone app does not provide user authentication or TLS. It is safe to bind locally for personal use. Before exposing it to a network, restrict access or put it behind an authenticated HTTPS reverse proxy, and always connect with a read-only ClickHouse account.
See Deployment for port options and production considerations.
Option 3: Use the Single HTML File
The single-file build runs entirely in your browser:
- Try TraceHouse online
- Download
tracehouse.htmland open it locally
The HTML build connects directly from your browser to ClickHouse. Your ClickHouse HTTP endpoint must return suitable CORS headers. If it does not, use the standalone app or Grafana plugin instead.
ClickHouse Cloud supports browser connections. Many self-managed, Kubernetes, and hosted ClickHouse environments do not enable CORS by default.
For details, see Connecting to ClickHouse.
Connect with a Read-Only Account
TraceHouse reads ClickHouse system tables to power its dashboards. Use a dedicated read-only account and grant only the access you need.
See Required Permissions for the recommended grants and optional settings used by features such as flamegraphs.
Next Steps
- Connecting to ClickHouse - connectivity, permissions, and environment-specific notes
- Deployment - explore deployment options and build TraceHouse from source
- Architecture - understand the available connection and deployment modes
- Development Setup - clone the source, run the development server, and generate test data