Strict vs lax
distkit's counters come in two flavors, and the same split shows up again in the instance-aware counters. Understanding it once explains both.
Strict: correctness first
A strict counter executes every operation as an atomic Lua script on Redis. Each call is one round-trip, and a read always reflects the latest write from anywhere in the cluster.
Use strict counters when an off-by-one matters: billing, inventory, quota enforcement, anything you would be uncomfortable approximating.
Lax: throughput first
A lax counter buffers increments in a local DashMap and flushes them to Redis in batched pipelines on an interval (allowed_lag, default ~20 ms). Increments return almost instantly because they never touch the network on the hot path. Reads return the local view (remote_total + pending_delta), which is always consistent within the same process but may lag what other processes have flushed.
Use lax counters for analytics and high-throughput metrics, where a few milliseconds of cross-process lag is fine and per-call Redis I/O would be the bottleneck.
Side by side
StrictCounter | LaxCounter | StrictInstanceAwareCounter | LaxInstanceAwareCounter | |
|---|---|---|---|---|
| Consistency | Immediate | Eventual (~20 ms default) | Immediate | Eventual (flush_interval) |
inc latency | Redis round-trip | Sub-microsecond (warm path) | Redis round-trip | Sub-microsecond (warm path) |
| Redis I/O | Every operation | Batched on interval | Every inc | Batched on interval |
set / del | Immediate | Immediate | Immediate (bumps epoch) | Flushes pending delta, then immediate |
| Per-instance tracking | No | No | Yes | Yes |
| Dead-instance cleanup | No | No | Yes | Yes |
| Feature flag | counter (default) | counter (default) | instance-aware-counter | instance-aware-counter |
| Use case | Billing, inventory, exact global count | Analytics, high-throughput metrics | Connection counts, exact live metrics | High-frequency per-node throughput metrics |
A rule of thumb
Reach for strict by default. Switch to lax only when you have measured that per-call Redis round-trips are your bottleneck and you can tolerate a small, bounded lag.
See Counters for the API and Instance-aware counters for the per-instance variants.