Trench

Trench is an open-source analytics infrastructure designed for teams that need scalable, real-time event tracking without the complexity of wiring together Kafka and ClickHouse independently. Built by the Frigade team to solve their own production scaling bottlenecks, it replaces slow Postgres-based event tables with a high-throughput pipeline capable of ingesting thousands of events per second on a single node and querying them in real time.

The system packages Apache Kafka for event ingestion, ClickHouse for fast columnar SQL queries, and a NestJS API layer into a single production-ready Docker image. It supports self-hosting on any cloud provider with full data control, or a managed Trench Cloud option with serverless autoscaling and 99.99% SLAs. The platform is GDPR and PECR compliant by design — no cookies, with built-in user data access, rectification, and deletion controls.

Trench implements the Segment Track, Identify, and Group API schema natively, enabling drop-in replacement for tools like PostHog or Mixpanel without changing client-side instrumentation code. Events can be forwarded in real time to external systems via configurable webhook subscriptions, and raw SQL queries against ClickHouse are exposed through a REST API for ad-hoc analysis and dashboard integrations.

Multi-workspace support provides tenant-level isolation using per-workspace Kafka topics and ClickHouse databases, making Trench suitable for SaaS platforms that need to provide analytics as a product feature without mixing customer data in shared tables.

What You Get

• Segment API Compatibility - Full implementation of Segment’s Track, Identify, and Group event schemas, enabling migration from PostHog, Mixpanel, or any Segment-compatible SDK without changing client instrumentation.
• Single Production-Ready Docker Image - Kafka, ClickHouse, and the NestJS API ship as one containerized stack with pre-configured Docker Compose files, including dev, SASL, SSL+SASL, and stateless variants.
• Real-Time SQL Querying - A REST endpoint accepts raw ClickHouse SQL queries against your event data, enforcing read-only validation before execution so engineers can run ad-hoc analysis or connect Grafana without a separate query layer.
• Kafka-Powered Event Ingestion - Events published to the API are written to Kafka topics and consumed into ClickHouse via materialized views, decoupling ingestion throughput from query performance and providing durable buffering under traffic spikes.
• GDPR and PECR Compliant by Default - No tracking cookies are set; the API supports user data access, correction, and deletion requests through standard query and delete endpoints.
• Configurable Webhook Delivery - Webhooks subscribe to Kafka consumer groups per workspace, filtering by event type and name, and deliver batches to external HTTP endpoints — enabling integrations with Slack, CRMs, LLM pipelines, or custom downstream services.
• Multi-Workspace Tenant Isolation - Each workspace receives its own Kafka topic and ClickHouse database, preventing cross-tenant data access and enabling SaaS platforms to offer analytics as a first-class product feature.
• Automated Schema Migrations - SQL migrations are tracked by filename and MD5 checksum in a _migrations table, ensuring idempotent, ordered schema evolution without external migration tooling.

Common Use Cases

• Building a custom product analytics dashboard - A SaaS founder instruments their application with a Segment-compatible SDK, points it at Trench, and connects Grafana to ClickHouse via the queries endpoint to visualize feature adoption and user funnels in real time.
• Enriching LLM RAG pipelines with behavioral context - An AI startup streams user interaction events through Trench and uses the SQL query API to pull recent user behavior as context for retrieval-augmented generation prompts, personalizing AI responses based on past actions.
• Replacing an overloaded Postgres events table - An engineering team migrates from a events table in their primary Postgres database to Trench, eliminating slow aggregation queries during traffic peaks and reducing infrastructure costs by separating the analytics write path from the transactional database.
• Running a compliance-first analytics stack for European markets - A fintech company tracks user sessions and actions through Trench without cookies, satisfying GDPR data minimization requirements while maintaining real-time dashboards for product and compliance teams.
• Providing per-tenant analytics in a B2B SaaS product - A platform engineering team configures one Trench workspace per customer, giving each tenant isolated event storage and a dedicated SQL query endpoint for their own analytics without shared data exposure.

Under The Hood

Architecture Trench is a NestJS monorepo organized into domain modules — events, queries, webhooks, workspaces, and API keys — each with controller, service, DAO, and interface layers that enforce clean separation between HTTP handling and data access. The write path and read path are structurally separated: incoming events are validated in the service layer and written to Kafka topics in the DAO via KafkaJS producers, while read queries execute directly against ClickHouse through a separate service. Webhook delivery is implemented as per-webhook Kafka consumer groups that initialize on module startup, pulling events from the topic and fanning out to registered HTTP endpoints. A BootstrapService runs at startup to create Kafka topics, execute schema migrations, and seed default workspace records, providing a unified initialization sequence for distributed infrastructure state. Multi-tenancy is achieved by assigning each workspace its own Kafka topic and ClickHouse database, with migration runs scoped per database.

Tech Stack The backend is TypeScript on Node.js with NestJS using Fastify as the HTTP adapter for high-performance routing. Event streaming uses KafkaJS with full support for SASL (PLAIN, SCRAM-SHA-256, SCRAM-SHA-512) and mutual TLS authentication via environment variable configuration. ClickHouse is accessed through the official @clickhouse/client SDK, with Kafka-to-ClickHouse data flow handled entirely by SQL materialized views defined in versioned migration files. Redis and cache-manager provide API key and workspace caching. The monorepo uses Turbo for parallelized builds and test execution across pnpm workspaces. Docker Compose configurations bundle all infrastructure components, including variant files for SASL-only and SSL+SASL Kafka authentication setups.

Code Quality The test suite includes comprehensive end-to-end tests covering event creation, multi-field querying with filters, workspace isolation, and webhook consumption, using polling utilities to handle the eventual-consistency delay between Kafka ingestion and ClickHouse availability. Unit tests validate query safety enforcement and webhook event filtering logic. TypeScript typing is applied consistently across all module boundaries including Kafka event payloads, ClickHouse result shapes, and API response structures. Custom escapeString and formatToClickhouseDate utility functions handle ClickHouse query injection prevention at the data access layer. The migration runner tracks execution state by checksum, preventing re-application of modified migrations. Error handling uses NestJS BadRequestException at DAO boundaries but does not distinguish infrastructure failures from user input errors through custom error hierarchies.

What Makes It Unique Trench’s distinguishing technical choice is eliminating application-level ETL entirely: the Kafka-to-ClickHouse pipeline runs as a ClickHouse materialized view defined in a SQL migration file, meaning events written to Kafka are automatically materialized into the events table by ClickHouse’s built-in Kafka engine without any Node.js consumer polling. This design keeps the ingestion path fire-and-forget from the API’s perspective while guaranteeing durable buffering through Kafka. The Segment API compatibility layer is implemented as a direct schema mapping rather than a translation proxy, so standard Segment SDKs work without modification. Multi-workspace isolation using per-workspace Kafka topics and ClickHouse databases — rather than row-level tenant columns — provides hard data boundaries suitable for regulated environments and SaaS multi-tenancy.

Self-Hosting

Trench is released under the MIT License, which grants unrestricted rights to use, copy, modify, merge, publish, distribute, sublicense, and sell the software without requiring source disclosure or imposing copyleft conditions on applications built with it. Self-hosted deployments for commercial products, internal tooling, or customer-facing analytics features require no license fees or agreements with the Frigade team.

Running Trench in production requires Docker and Docker Compose on a host with at least 4 GB RAM and 4 CPU cores for the bundled Kafka and ClickHouse services alongside the Node.js API. The operator is responsible for Kafka topic retention configuration, ClickHouse storage growth, disk provisioning, SSL certificate management, and Kafka authentication (SASL/SSL) setup when connecting to external brokers. Schema evolution is handled through versioned SQL migration files, but applying migrations across a multi-node deployment or restoring from ClickHouse backups requires operational familiarity with both systems. There is no built-in high-availability configuration in the provided Docker Compose files; production HA would require running Kafka in a multi-broker cluster and ClickHouse in a replicated setup separately from the bundled single-node stack.

Trench Cloud provides the managed alternative with serverless autoscaling, 99.99% uptime SLAs, zero operational overhead, and a web dashboard at app.trench.dev. Compared to self-hosting, the cloud tier removes the operational burden of Kafka cluster management, ClickHouse storage provisioning, and infrastructure monitoring, and adds managed backups and guaranteed support. The community Slack group is available for self-hosted users, but there is no stated enterprise support tier or SLA for the open-source version.