WarpMetricExporter

A CRDT-backed metric exporter for cumulative sums, gauges, and cardinality estimates.

Each metric kind is backed by a different CRDT chosen to match its semantics:

• Sum — a GCounter per MetricKey. Cumulative, monotonically increasing. Two replicas that independently saw N and M events report N+M after merge. Re-exporting the same increment is not idempotent in the counter sense (each call to incrementSum adds to the total), but the GCounter lattice guarantees that merging the same remote snapshot twice does not inflate the total — so merge under retry is safe.

• Gauge — a LWWRegister<Double> per MetricKey. Last-writer-wins by (timestamp, replicaId) tiebreak. A later timestamp from any replica wins; tie-breaking on ReplicaId is deterministic regardless of arrival order.

• Cardinality — a HyperLogLog per MetricKey. Estimates distinct element counts (~0.81% relative error at default precision p=14). The join is element-wise max of register arrays: two replicas that independently added overlapping sets produce the same merged estimate — no double-counting.

• Exponential histogram — a DDSketch per MetricKey. Answers quantile queries ("p99 latency?") within a relative accuracy α; the join is lossless, so merged replicas equal the sketch of the combined stream. Exports as an OTLP ExponentialHistogramDataPoint, which requires α to align with an integer OTLP scale — configure via alphaForOtlpScale (the default histogramPrototype is scale-DEFAULT_OTLP_HISTOGRAM_SCALE-aligned, α ≈ 1.08%). Like HyperLogLog precision, the sketch configuration is a cluster-wide constant: sketches merge only when it matches exactly.

Key inversion

incrementSum, setGauge, and addCardinality all return MetricExportResult.Success the moment the updated CRDT is durably written to DurableStore — not when it is delivered to any backend. Delivery is asynchronous and eventually consistent.

Buffer cap

The total number of distinct MetricKeys across all kinds is bounded by maxMetrics. When the cap is exceeded, the bufferPolicy selects a series to evict. Every eviction is logged — the metric name and kind are emitted at WARN so an operator can detect label-cardinality explosions.

Thread safety

An explicit reentrantLock guards all mutable state. Suspend calls (store reads/writes) are performed outside the lock section. This is correct under a genuinely multi-threaded dispatcher — limitedParallelism(1) confinement is explicitly banned per repo policy.

Honest limits

• Clock skew. Gauge timestamps are the producer's local clock. An offline device with a slow clock may have its gauge silently overwritten by a peer with a faster clock even if the slow-clock value is "newer" in wall time. An HLC offset could be estimated on reconnect but is not yet implemented.

• Cardinality bound. HyperLogLog precision is fixed at p=14 (~0.81% error, 12 KB per series). Very small cardinalities (< ~5 distinct elements) have higher relative error; the linear-counting correction reduces but does not eliminate this.

• Histogram α is OTLP-gated. Only OTLP-aligned sketch accuracies are accepted (alphaForOtlpScale); a free-form α has no integer OTLP scale, and re-bucketing would break the accuracy guarantee, so ingestion rejects it up front rather than letting an OTLP drain fail later.

Parameters

Samples

val replica = us.tractat.kuilt.crdt.ReplicaId("device-uuid-abc123")
val exporter = WarpMetricExporter(replica = replica, store = InMemoryDurableStore())

// Recover persisted metrics from a previous session.
exporter.recover()

// Sum: count server requests — idempotent merge means no double-count under retry.
val requests = MetricKey("server.requests", MetricKind.SUM, mapOf("handler" to "/api/v1"))
exporter.incrementSum(requests, by = 1L)
check(exporter.sumValue(requests) == 1L)

// Gauge: snapshot the current CPU load — last writer (by timestamp) wins across replicas.
val cpu = MetricKey("cpu.usage", MetricKind.GAUGE)
exporter.setGauge(cpu, value = 0.72, timestamp = 1_000_000L)
check(exporter.gaugeValue(cpu) == 0.72)

// Cardinality: count distinct users — same user added twice is still 1.
val users = MetricKey("unique.users", MetricKind.CARDINALITY)
exporter.addCardinality(users, "user-abc")
exporter.addCardinality(users, "user-abc") // idempotent — no double-count
check(exporter.cardinalityEstimate(users) > 0L)

// Exponential histogram: record latencies — any quantile within ~1% relative accuracy.
// Exports as an OTLP ExponentialHistogramDataPoint (see alphaForOtlpScale).
val latency = MetricKey("request.latency.ms", MetricKind.EXPONENTIAL_HISTOGRAM)
exporter.recordHistogram(latency, 12.5)
exporter.recordHistogram(latency, 480.0)
check(exporter.histogramQuantile(latency, 0.5) != null)