# EXOS Analytics -- ClickStack Alignment **Last updated**: 2026-03-22 **Author**: Joe Lanzone **Purpose**: Document how EXOS Analytics aligns with ClickHouse's ClickStack initiative and how ServiceLink could adopt the bundled stack. --- ## What is ClickStack? ClickStack is ClickHouse's answer to the observability and analytics platform question: instead of using 5-10 separate tools, run a single integrated stack with ClickHouse at the center. ClickHouse has assembled ClickStack through a combination of acquisitions, partnerships, and open-source projects: | Component | Role | Status | |-----------|------|--------| | **ClickHouse** | Analytical database (columnar, real-time) | Core product | | **HyperDX** | Session replay + browser telemetry (rrweb + OTel) | Acquired by ClickHouse | | **LibreChat** | AI chat interface with Model Context Protocol (MCP) | Acquired by ClickHouse | | **Langfuse** | LLM observability (prompt traces, token usage, latency) | Partner / integration | | **OTel Collector** | Telemetry ingestion (HyperDX-flavored) | Open source | | **ClickHouse MCP Server** | AI agent access to ClickHouse via Model Context Protocol | Open source (`clickhouse/mcp-clickhouse`) | ClickStack ships as: - Docker Compose bundles for local development - Helm charts for Kubernetes (`ClickHouse/ClickStack-helm-charts`) - ClickHouse Cloud integrations (managed, one-click enable) ### Key ClickStack Blog Posts and Resources - [ClickStack: A Year in Review (2025)](https://clickhouse.com/blog/clickstack-a-year-in-review-2025) - [What's New in ClickStack (February 2026)](https://clickhouse.com/blog/whats-new-in-clickstack-february-2026) - [ClickStack Embedded ClickHouse](https://clickhouse.com/blog/clickstack-embedded-clickhouse) - [ClickStack API](https://clickhouse.com/blog/clickstack-api) - [The Agentic Data Stack](https://clickhouse.com/blog/the-agentic-data-stack) - [Event Patterns in ClickStack](https://clickhouse.com/blog/event-patterns-clickstack) - [Instrumenting Your App with OTel + ClickStack](https://clickhouse.com/blog/instrumenting-your-app-with-otel-clickstack) - [How to Set Up ClickHouse for Agentic Analytics](https://clickhouse.com/blog/how-to-set-up-clickhouse-for-agentic-analytics) - [ClickHouse Acquires LibreChat](https://clickhouse.com/blog/clickhouse-acquires-librechat) ### Reference Implementation: telco_marketing The `ClickHouse/ClickHouse_Demos` repo contains a `telco_marketing` demo that uses the full ClickStack: ``` telco_marketing/ ├── ClickHouse Cloud (analytical database) ├── HyperDX (session replay + browser OTel) ├── LibreChat (AI chat with MCP tool use) ├── Langfuse (LLM observability) ├── MCP ClickHouse Server (AI ↔ ClickHouse bridge) └── React frontend (Vite) (dashboard UI) ``` This demo targets telco marketing analytics: customer segmentation, campaign attribution, churn prediction. It proves the ClickStack pattern works but does not address process mining, operator analytics, or ServiceLink-specific workflows. --- ## EXOS Analytics: ClickStack Alignment Map ### Where EXOS Already Aligns | ClickStack Component | EXOS Equivalent | Alignment Level | |---------------------|-----------------|-----------------| | ClickHouse Cloud | ClickHouse Cloud (Azure East US 2) | **Full** -- same managed service, same tables | | HyperDX SDK | `@hyperdx/browser@0.22.0` on every page | **Full** -- same SDK, same rrweb replay, same OTel export | | HyperDX OTel Collector | `hyperdx/hyperdx-otel-collector:latest` | **Full** -- same Docker image, same OTLP ingestion | | MCP ClickHouse Server | `ghcr.io/clickhouse/mcp-clickhouse:latest` in `docker-compose.yml` | **Full** -- deployed, exposed via `mcp-http-adapter.py` | | OTel trace schema | `otel_traces`, `otel_logs`, `otel_metrics_*` | **Full** -- standard OTel schema | | Session replay in ClickHouse | `hyperdx_sessions` table | **Full** -- rrweb events stored in ClickHouse | ### Where EXOS Diverges (Intentionally) | ClickStack Component | EXOS Alternative | Why the Divergence | |---------------------|-----------------|-------------------| | **LibreChat** (AI chat) | Custom AI assistant (`/api/assistant`, `/api/query`) | LibreChat is a general-purpose chat UI. EXOS needs domain-specific AI that knows the Operational Intelligence Playbook, ServiceLink's LOBs, and can generate process mining queries. The custom assistant injects schema context, SQL templates, and domain knowledge into every prompt. | | **Langfuse** (LLM observability) | None (planned) | EXOS does not yet track AI query costs, latencies, or prompt effectiveness. Langfuse integration would be straightforward -- it accepts OTel spans. | | **React frontend (Vite)** | Vanilla HTML + Tailwind + Chart.js | Deliberate architectural choice: zero build step, zero npm dependencies in production, zero framework lock-in. Every page is a self-contained HTML file. This makes the portal trivially deployable to Cloudflare Pages, Vercel, nginx, or any static host. | ### Where EXOS Extends ClickStack EXOS Analytics adds capabilities that ClickStack does not provide: | Capability | EXOS Implementation | ClickStack Status | |-----------|--------------------|--------------------| | **Process mining** | 7 ClickHouse primitives (`windowFunnel`, `sequenceMatch`, `sequenceCount`, `lagInFrame`, `groupArray`, rolling z-score, ASOF JOIN) | Not addressed | | **Conformance checking** | `sequenceMatch()` against defined SOPs | Not addressed | | **Operator/workforce analytics** | Dedicated operator performance page + dimensional analysis | Not addressed | | **Automation opportunity scoring** | AI-assisted scoring with `daily_volume * avg_duration * (1 + rework_rate)` formula | Not addressed | | **Probabilistic attribution** | ASOF JOIN + composite temporal/attribute/frequency scoring | Not addressed | | **Dimensional RCA** | Multi-dimension sweep with variance contribution ranking (Meta DrP pattern) | Not addressed | | **Event clustering** | Drain3 template mining + K-means behavior vectors + temporal burst detection | Not addressed | | **Product analytics** (funnels, retention, paths, events) | Full implementation with 18 API handlers | Partial (telco demo has basic charts) | | **Visitor enrichment** | Real-time geo/device/network enrichment from Cloudflare headers | Not in ClickStack (HyperDX captures some device info) | | **Dead/rage click detection** | Custom `dead-click-tracker.js` emitting via `HyperDX.addAction()` | Not in ClickStack (HyperDX captures clicks but no frustration analysis) | | **Activity heatbar** | YouTube-style SVG waveform with Catmull-Rom spline interpolation | Not in ClickStack | --- ## Adoption Path: ServiceLink + ClickStack ### Phase 1: Current State (Already Aligned) ServiceLink is already running the core ClickStack: - ClickHouse Cloud on Azure - HyperDX SDK + OTel Collector - MCP ClickHouse Server - Standard OTel schema No migration needed. EXOS Analytics is already a ClickStack-native application. ### Phase 2: Add Langfuse for AI Observability **Why**: Track which AI queries succeed, fail, or hallucinate. Measure token costs. Identify prompt improvement opportunities. **How**: 1. Deploy Langfuse via Docker Compose (add to `docker-compose.yml`): ```yaml langfuse: image: langfuse/langfuse:latest environment: - DATABASE_URL=postgresql://exos:${POSTGRES_PASSWORD}@postgres:5432/langfuse - NEXTAUTH_SECRET=${LANGFUSE_SECRET} - NEXTAUTH_URL=https://exos-demo.com/langfuse depends_on: - postgres networks: - clickstack ``` 2. Instrument `/api/assistant` and `/api/query` handlers to emit Langfuse traces: ```javascript import { Langfuse } from 'langfuse'; const langfuse = new Langfuse({ publicKey: '...', secretKey: '...' }); // In the assistant handler: const trace = langfuse.trace({ name: 'nl-to-sql', userId: workspace }); const generation = trace.generation({ name: 'claude-sql-gen', model: 'claude-3-opus', input: userQuery, output: generatedSQL, }); ``` 3. Create a Langfuse dashboard to monitor: query success rate, avg latency, token cost per query, most-failed query patterns. **Effort**: 1-2 days. Langfuse uses PostgreSQL (already in the stack) and has a Node.js SDK. ### Phase 3: Evaluate LibreChat as Alternative Chat UI **When to consider**: If the custom AI assistant in `query.html` becomes difficult to maintain, or if ServiceLink wants multi-model support (GPT-4, Claude, Gemini) with conversation history. **LibreChat advantages**: - Built-in MCP tool use (ClickHouse queries via MCP server) - Conversation history and search - Multi-model routing - File upload and analysis - User management and auth **LibreChat disadvantages for EXOS**: - Does not know ServiceLink's domain context without custom prompt engineering - Does not integrate with the portal's UI (separate application) - Does not generate SQL that uses EXOS-specific views and SpanAttributes - Adds React/Node.js dependency to the stack **Recommendation**: Keep the custom assistant for the portal UI (it is deeply integrated with schema context and the Playbook). Consider LibreChat as a supplementary interface for power users who want freeform exploration with conversation history. ### Phase 4: ClickStack Helm Chart Deployment When ServiceLink moves to AKS (see `AKS_MIGRATION.md`), use ClickHouse's official ClickStack Helm charts (`ClickHouse/ClickStack-helm-charts`) as the base, then extend: ``` clickstack-helm-charts/ # Official ClickHouse charts ├── clickhouse/ # ClickHouse operator (or use Cloud) ├── hyperdx-collector/ # OTel Collector ├── hyperdx-frontend/ # HyperDX UI (optional) ├── librechat/ # AI chat (optional) └── langfuse/ # LLM observability (optional) exos-extensions/ # ServiceLink additions ├── portal/ # EXOS portal (nginx + API) ├── mcp-adapter/ # MCP HTTP adapter ├── metabase/ # BI dashboards └── values-servicelink.yaml # Override values for ServiceLink ``` This gives ServiceLink: - Official ClickHouse-maintained infrastructure components - EXOS-specific process mining and analytics extensions - Single `helm upgrade` for the entire stack - Azure Key Vault integration for secrets ### Phase 5: ClickHouse Cloud Native Integrations As ClickHouse Cloud adds native ClickStack features, EXOS can adopt them: | ClickHouse Cloud Feature | EXOS Benefit | Migration Path | |-------------------------|-------------|----------------| | **Cloud Dashboards** | Replace custom portal dashboards with Cloud-native ones | Export EXOS chart configs as Cloud Dashboard definitions | | **Agent Skills** | Pre-built analytical skills for AI queries | Import EXOS Playbook templates as Agent Skills | | **Agentic Analytics (Ask AI)** | Cloud-native NL-to-SQL | May replace `/api/query` handler if schema context injection is supported | | **Webhook Endpoints** | Push-based alerting from ClickHouse | Replace planned Cloudflare Worker cron alerting | | **ClickHouse MCP (remote)** | Remote MCP server without self-hosting | Remove `mcp-server` from Docker Compose | --- ## ClickStack Ecosystem Map ``` ClickHouse Cloud (Azure East US 2) ═══════════════════════════════════ | ┌────────────┼────────────────┐ | | | ┌─────────┐ ┌───────────┐ ┌──────────────┐ | HyperDX | | MCP Server | | Cloud | | (replay | | (AI tools | | Dashboards | | + OTel) | | for CH) | | (native) | └────┬────┘ └─────┬─────┘ └──────────────┘ | | ┌───────────┼─────────────┼───────────┐ | | | | ┌───────┐ ┌─────────┐ ┌───────────┐ ┌──────────┐ | EXOS | | Libre | | Langfuse | | Agent | | Portal | | Chat | | (LLM obs) | | Skills | | (custom| | (AI | | | | (pre- | | HTML) | | chat) | | | | built) | └───────┘ └─────────┘ └───────────┘ └──────────┘ | +── Process Mining (EXOS-exclusive) +── Operator Analytics (EXOS-exclusive) +── Product Analytics (funnels, retention, paths) +── Session Replay with trace correlation +── AI-assisted query (domain-aware) +── Automation scoring ``` EXOS Analytics sits in the application layer on top of ClickStack, adding the domain-specific intelligence that ServiceLink needs. The infrastructure layer (ClickHouse + HyperDX + OTel + MCP) is standard ClickStack. The intelligence layer (process mining, operator analytics, conformance checking, automation scoring) is EXOS-exclusive. --- ## Key Architectural Decisions ### Why Vanilla HTML over React The telco_marketing demo uses React + Vite. EXOS chose vanilla HTML because: 1. **Zero build step**: Edit HTML, push, deployed. No `npm install`, no `vite build`, no bundler configuration. 2. **Zero runtime dependencies**: No React, no router, no state management library. The portal runs in any browser without JavaScript framework compatibility concerns. 3. **Trivially deployable**: Works on Cloudflare Pages, Vercel, nginx, Apache, S3, or any static file server. No server-side rendering, no hydration, no framework-specific hosting requirements. 4. **Maintenance**: A vanilla HTML page with inline `