Architecture

import SignalFlow from ‘../../../components/SignalFlow.astro’; import { Aside } from ‘@astrojs/starlight/components’;

PulsusDB is a stateless translation and coordination layer around ClickHouse. It accepts telemetry, applies signal-specific validation and modeling, and compiles familiar observability queries into ClickHouse-native SQL.

Process model

One binary runs in three modes:

Writer and reader processes scale independently; all mode combines both responsibilities.

all embeds both responsibilities and rule evaluation. writer and reader modes let operators scale ingest and query independently behind separate load balancers.

Writer path

1. Receive OTLP, Prometheus remote write, or an enabled compatibility protocol.
2. Decompress and decode the request with explicit limits.
3. Normalize labels and attributes into the signal’s canonical model.
4. Compute stream or series fingerprints.
5. Apply backpressure before allocating or queuing unbounded work.
6. Insert one deduplicated landing block into ClickHouse.
7. Let materialized views route the block into purpose-built tables.

The writer can acknowledge synchronously or queue async insertion, controlled globally and per request.

Reader path

1. Parse LogQL, PromQL, or TraceQL.
2. Validate language and resource budgets.
3. Resolve candidate streams or series through index tables.
4. Select raw or rollup tables while preserving query semantics.
5. Generate ClickHouse SQL with time bounds pushed into PREWHERE.
6. Run partial aggregation close to the data.
7. Complete any language semantics that are unsafe to lower into SQL.

ClickHouse owns state

ClickHouse stores telemetry, label indexes, rollups, rules, and schema metadata. PulsusDB processes can therefore be replaced or horizontally scaled without local durable state. Optional disk spooling protects writes during insertion failures, but it is not the system of record.

Cluster model

In a clustered deployment:

• local tables use replicated ClickHouse engines;
• distributed wrapper tables fan reads and writes across shards;
• PULSUS_CLUSTER enables cluster-aware schema rendering;
• readers target the distributed suffix configured by PULSUS_DIST_SUFFIX;
• multiple ClickHouse HTTP endpoints can be configured for zone-aware connection spreading.

Every endpoint in `CLICKHOUSE_SERVERS` must be a cluster member that exposes the distributed wrapper tables. Endpoint spreading changes the coordinator, not the query's meaning.

Schema ownership

The server never creates the database automatically. schema/schema.sh owns creation and reads schema-specific variables such as retention. At startup, PulsusDB checks that the configured database and required objects exist before reporting ready.