Why architecture matters here
The reason a percentile sketch is architectural, not a library footnote, is that the naive alternatives all fail at scale in ways that matter. Keeping the full sample is O(n) memory and O(n log n) to query — impossible for a high-cardinality, high-rate stream. Fixed-bucket histograms (the classic 'count of requests in the 10-20ms bucket') are cheap and mergeable but force you to choose bucket boundaries in advance; get them wrong and your p99 lands inside one fat bucket that spans 500ms to 2s, so your 'answer' is a 1500ms-wide shrug. Worse, the tail — the region you most care about — is exactly where a linear or even log-bucketed histogram has the fewest, widest buckets relative to the rank resolution you need.
The t-digest attacks the problem from the rank side instead of the value side. It does not pre-commit to value boundaries; it lets the data decide where clusters fall, and it constrains cluster size in rank space so that clusters near quantile 0 and quantile 1 are forced small (few observations each, hence fine resolution) while clusters near quantile 0.5 are allowed to grow large. The consequence is that estimating p99.9 interpolates between two tiny, tightly-packed centroids and is accurate to a small relative error, while estimating p50 interpolates across one big centroid and is accurate to within a value or two — which is all anyone needs from a median.
The design decision the architecture forces you to make is the compression parameter, usually written δ or 1/K: it sets the ceiling on how many centroids the digest keeps, and therefore the size-versus-accuracy trade. A larger budget buys tighter tails and more memory; a smaller budget saves space at the cost of tail resolution. Because the trade is smooth and the accuracy guarantee is about relative rank error at the extremes, you can tune one number and reason about exactly what you are giving up. That legibility — one knob, a known guarantee, bounded memory, lossless merge — is why the t-digest displaced ad-hoc histograms in most modern monitoring stacks.
There is a deeper reason the relative-error-at-the-tails guarantee is the right one for observability, and it is worth stating because it justifies the whole warped-cluster design. The quantiles people act on are almost never in the middle; they are p90, p99, p99.9 — the tail — because that is where SLA violations, timeouts, and user pain concentrate. A monitoring system that is accurate about the median and vague about the tail is accurate about the thing nobody pages on and vague about the thing everyone does. A sketch that spent its memory uniformly across quantile space would be making exactly that mistake: lavishing resolution on a median that tolerates being off by a value or two, and starving the tail that needs to distinguish a 300ms p99.9 from a 4-second one. The t-digest's insistence on small, fine centroids at the extremes is not a clever trick bolted on for accuracy; it is a direct encoding of the operational truth that tail resolution is worth more than middle resolution, and it is why a t-digest with a modest centroid budget outperforms a much larger uniform histogram on the questions that actually get asked.
The architecture: every piece explained
Start with the centroids. The digest is an ordered list of (mean, count) pairs, sorted by mean. Each centroid claims a contiguous slice of the sorted stream: its count is how many observations it summarizes, its mean is their average. Conceptually the centroids tile the distribution left to right, and the cumulative counts let you map any value to an approximate rank and any rank to an approximate value. A brand-new observation is either absorbed into the nearest centroid (updating its mean and incrementing its count) or, if the nearest centroid is already at its size ceiling, becomes a new singleton centroid.
The magic is in the scale function k(q), which warps quantile space. Instead of allowing every centroid the same count, the t-digest bounds each centroid's size by a function of where it sits in the distribution: a centroid covering the quantile range [q1, q2] is allowed to exist only if k(q2) − k(q1) ≤ 1, where k is a monotone function (a scaled arcsine or logit-like curve) that is steep near q=0 and q=1 and shallow near q=0.5. Steep means a small change in q consumes a full unit of k, so centroids there must stay small — few observations, fine resolution. Shallow near the median means a large change in q fits inside one unit of k, so centroids there can be large. This single function is what produces the fine-tails / coarse-middle shape that defines the sketch.
The compression K scales k(q) — it is the multiplier that sets how many units of k span the whole [0,1] range, hence the total centroid budget (roughly proportional to K). Turn K up and every region gets more, smaller centroids and the whole digest is more accurate but larger; turn it down for a smaller, coarser sketch. The bounded sketch that results is typically a hundred to a few hundred centroids regardless of stream length. Querying a quantile walks the centroids accumulating counts until it reaches the target rank, then interpolates linearly between the two straddling centroid means — giving a smooth estimate rather than a bucket-quantized one. The merge of two digests concatenates their centroid lists, sorts by mean, and re-clusters under the same k-bound, producing a valid digest of the combined data; because it depends only on the centroids and not their arrival order, it is associative and commutative. The ops strip — per-shard digests, periodic merge, size caps, and accuracy spot-checks against exact quantiles on samples — keeps the fleet-wide numbers trustworthy.
End-to-end flow
Trace latency monitoring across a fleet. Each of 500 application servers keeps a t-digest of its request latencies with compression K=100, costing a few kilobytes per server. On every request the server folds the measured latency into its local digest in constant time: find the nearest centroid, and either absorb the value or spawn a singleton if that centroid is at its k-bounded ceiling. No sorting, no unbounded growth, no per-request allocation beyond the occasional new centroid. The digest is the server's entire memory of its latency distribution.
Once a second, each server serializes its digest — a compact list of (mean, count) pairs — and ships it to a central collector. The collector does not need any raw latencies; it merges the 500 incoming digests into one fleet-wide digest by concatenating all their centroids, sorting by mean, and re-clustering under the k-bound. Because merge is associative, the collector can fold them in any order, in parallel, in a tree; the result is identical. From that single merged digest it reads p50, p90, p99, and p99.9 for the entire fleet by walking centroids to the target cumulative rank and interpolating. The whole pipeline moves kilobytes per server per second and yields accurate tail percentiles over billions of requests.
Now the tail scenario that shows why the shape matters. At 03:10 a bad deploy on 20 of the 500 servers pushes their p99.9 from 300ms to 4 seconds while their median barely moves. In a fixed-bucket histogram with coarse tail buckets, that shift might vanish inside one wide bucket and the alert would never fire. In the t-digest, the affected servers' digests grow small, sharp centroids way out at 4 seconds — the fine tail resolution captures them precisely — and when merged into the fleet digest they pull p99.9 up sharply and visibly. The on-call sees the tail move within seconds of the deploy, correlates it to the 20 servers, and rolls back. The median never twitched; only the sketch that keeps the tails sharp could have caught it.
Consider what the merge bought operationally. If instead each server had computed and reported its own p99 as a single number, the collector would be stuck: you cannot average per-server p99s to get a fleet p99 — a server handling ten requests and a server handling ten million contribute their percentiles with wildly different weight, and the mean of quantiles is not the quantile of the union. The only correct fleet percentile comes from combining the underlying distributions, which is exactly what merging digests does and what reporting scalar quantiles destroys. This is the single most common mistake teams make when they roll their own metrics, and it is why the mergeability of the sketch — not just its compactness — is the property that makes it architecturally correct. A distribution you can merge is a distribution you can shard, parallelize, and roll up; a scalar percentile is a dead end the moment you have more than one producer.