05Design patternsTime-series metrics ingestion
05 · Reusable pattern
Time-series metrics ingestion
Design append-heavy collection, aggregation windows, retention, downsampling, and cardinality controls.Lesson spine
What you need to understand.
Time-series ingestion is an append-heavy pipeline whose enemies are unbounded cardinality, retention cost, and expensive wide scans.
Collection model
Push fits short-lived or edge producers; pull centralizes discovery and scrape control for service metrics.
Write path
Batch samples, append to a WAL, update in-memory structures, and flush immutable time-partitioned columnar blocks.
Series identity
A metric name plus labels defines a series. Unbounded user IDs or request IDs create cardinality explosions.
Compression and retention
Delta-encode timestamps and values, compact blocks, expire raw data, and retain longer rollups.
Downsampling
Aggregate old one-second samples into minute, hour, and day resolutions while preserving the functions queries need.
Query and alerting
Partition by series and time, prune blocks, precompute common aggregates, and evaluate alerts over streaming or recent windows.
Before the boxes
Frame the decision.
What must work
Design append-heavy collection, aggregation windows, retention, downsampling, and cardinality controls.
What changes the design
Samples/s · active series · labels · retention · compression · query window
What owns the truth
Identify the component that commits authoritative state, then separate synchronous confirmation from derived work.
What stays simple
Do not add global coordination, multi-region writes, or a specialized store until a requirement earns the complexity.
Architecture map
Trace ownership, not just traffic.
Follow the decision from left to right. Every arrow should have a reason.
Batch samples
Normalizes
Routes by series and time
Buffers ingestion
Builds columnar blocks
Creates rollups
Scans ranges
Walk one representative request across every arrow. Say whether the handoff is synchronous or asynchronous, what identity makes a retry safe, and which step changes authoritative state.
- 01
Agents — Batch samples Define the output contract before moving to the next owner.
- 02
Gateway — Normalizes Define the output contract before moving to the next owner.
- 03
Partitioner — Routes by series and time Define the output contract before moving to the next owner.
- 04
Write log — Buffers ingestion Define the output contract before moving to the next owner.
- 05
Compactor — Builds columnar blocks Define the output contract before moving to the next owner.
- 06
Downsampler — Creates rollups Define the output contract before moving to the next owner.
- 07
Query engine — Scans ranges Confirm the result and emit the evidence needed to reconcile it.
Decision table
Make the trade-offs explicit.
| Decision | Defensible position | Cost to acknowledge |
|---|---|---|
| Primary mechanism | Raw retention preserves flexibility; downsampling controls cost by discarding detail. | The stronger guarantee usually adds coordination, latency, state, or operational work. |
| Sync vs. async | Keep only correctness-critical confirmation synchronous. Move derived views, notifications, analytics, and cleanup behind a durable boundary. | Async work needs idempotency, lag monitoring, replay, and a product definition for partial completion. |
| Simple vs. scaled | Begin with one logical owner and a clear API. Partition or replicate only the resource proven to be the first bottleneck. | Migration requires stable identities, versioned contracts, backfill, and a rollback path. |
Failure review
Design the recovery path.
Topic-specific risk
Unbounded labels and hot series overwhelm indexes and partitions.
ResponsePersist enough identity and state to distinguish retry, resume, compensation, and operator repair.
Dependency timeout
A timeout is ambiguous: the remote side may have failed, succeeded, or still be running.
ResponseUse deadlines, bounded backoff with jitter, idempotency keys, and a status or reconciliation path.
Overload or skew
Average capacity can look healthy while a tenant, key, partition, region, or expensive request saturates one owner.
ResponseExpose queue depth and hot-key share, apply backpressure, isolate tenants, and degrade optional work before correctness.
Evidence + level bar
Prove the design can be operated.
Health of the promise
Measure user-visible latency or freshness, correctness drift, saturation, retry volume, and time to recover. Alert on the failed promise—not only CPU.
Complete and clear
Finish the happy path, identify the state owner, choose reasonable building blocks, and explain one scale mechanism.
Trade-offs and failure
Separate read and write paths, define consistency, explain partitioning, and make duplicate or partial failure safe.
Evolution and operations
Discuss multi-region boundaries, migration, tenant isolation, capacity, observability, and how the architecture changes over time.
Interview language
Open the deep dive with a claim.
“For Time-series metrics ingestion, the decision I want to make explicit is this: Raw retention preserves flexibility; downsampling controls cost by discarding detail. I’ll trace the state-changing path first, show where the result becomes durable, then test the design against the highest-risk failure and our target scale.”
08 · Retrieval check
Can you defend it without the page?
- For Time-series metrics ingestion, where is the correctness boundary and which failure would you test first?
- Which component owns committed truth, and what event or response proves the commit?
- Where is the first scaling or coordination bottleneck under the stated envelope?
- What happens after an ambiguous timeout or duplicate operation?
- Which complexity would you remove at one hundredth of the scale?