How clickhouse/clickstack works
ClickStack is an observability product for searching and visualizing logs, metrics, traces, and session replays over ClickHouse. Engineers ingest telemetry, discover sources, investigate events and traces, and use charts, dashboards, and alerts to monitor systems. The web app, API, MCP interface, and terminal CLI provide distinct ways to work with this data. The graph preserves documented product capabilities and sampled query/MCP relationships; many UI routes, ingestion internals, and persistence connections were not shown, so those links are omitted.
Main entry points: mcpServer.ts MCP server · pages Web application · src Query and schema utilities · useOffsetPaginatedQuery.tsx Paged chart queries
Components 26
Web investigation
- Web application
packages/app/pages - Time selection
packages/app/src/timeQuery.ts - Metadata lookup
packages/app/src/hooks/useMetadata.tsx - Paged chart queries
packages/app/src/hooks/useOffsetPaginatedQuery.tsx - Service dashboards
packages/app/src/ServicesDashboardPage
API services
- Application API
packages/api/src/server.ts - API routes
packages/api/src/routers - Domain controllers
packages/api/src/controllers - Alert evaluation
packages/api/src/tasks/checkAlerts - Prometheus queries
packages/api/src/controllers/timeseriesEngine.ts
Query foundation
- Query and schema utilities
packages/common-utils/src - Search syntax parser
packages/common-utils/src/queryParser.ts
Agent interface
- MCP HTTP endpoint
packages/api/src/mcp/app.ts - MCP server
packages/api/src/mcp/mcpServer.ts - Query tools
packages/api/src/mcp/tools/query - Dashboard tools
packages/api/src/mcp/tools/dashboards - Source tools
packages/api/src/mcp/tools/sources - Alert and trace tools
packages/api/src/mcp/tools
Terminal interface
- CLI interface
packages/cli/src/App.tsx - CLI API client
packages/cli/src/api/client.ts - Event query builder
packages/cli/src/api/eventQuery.ts - Dashboard tile queries
packages/cli/src/shared/tileQuery.ts - TUI keybindings
packages/cli/src/components/EventViewer/useKeybindings.ts
Other components
- Engineer
- Telemetry producers
- ClickHouse
Connections 22
- Engineer → Web application: investigates in
README.md - Telemetry producers → ClickHouse: stores telemetry
- Web application → Application API: uses API
README.md - Web application → Time selection: sets time range
- Paged chart queries → Metadata lookup: loads metadata
packages/app/src/hooks/useOffsetPaginatedQuery.tsx - Paged chart queries → Query and schema utilities: renders chart query
packages/app/src/hooks/useOffsetPaginatedQuery.tsx - Service dashboards → Web application: supports APM views
- Application API → API routes: serves routes
- API routes → Domain controllers: dispatches requests
- Alert evaluation → ClickHouse: evaluates telemetry
- Prometheus queries → Query and schema utilities: uses metadata and SQL
packages/api/src/controllers/timeseriesEngine.ts - Engineer → CLI interface: uses terminal
README.md - CLI interface → CLI API client: loads data
packages/cli/src/App.tsx - Event query builder → Query and schema utilities: renders event SQL
packages/cli/src/api/eventQuery.ts - Dashboard tile queries → Query and schema utilities: queries chart config
packages/cli/src/shared/tileQuery.ts - Engineer → MCP HTTP endpoint: connects agent
- MCP HTTP endpoint → MCP server: creates server
packages/api/src/mcp/app.ts - MCP server → Query tools: registers tools
packages/api/src/mcp/mcpServer.ts - MCP server → Dashboard tools: registers tools
packages/api/src/mcp/mcpServer.ts - MCP server → Source tools: registers tools
packages/api/src/mcp/mcpServer.ts - MCP server → Alert and trace tools: registers tools
packages/api/src/mcp/mcpServer.ts - Query tools → ClickHouse: queries observability data