go 58 lines · 7 steps

A per-key rate limiter for log sampling

A Sampler caps how many log lines pass per key within a time window and reports how many it suppressed.

Explained by highlit
Intermediate rate-limiting concurrency time-windows mutex stateful
1package logsample
2 
3import (
4 "sync"
5 "time"
6)
7 
8type Sampler struct {
9 mu sync.Mutex
10 window time.Duration
11 threshold int
12 state map[string]*counter
13 now func() time.Time
14}
15 
16type counter struct {
17 count int
18 windowStart time.Time
19 suppressed int
20}
21 
22func NewSampler(window time.Duration, threshold int) *Sampler {
23 return &Sampler{
24 window: window,
25 threshold: threshold,
26 state: make(map[string]*counter),
27 now: time.Now,
28 }
29}
30 
31type Decision struct {
32 Log bool
33 Suppressed int
34}
35 
36func (s *Sampler) Allow(key string) Decision {
37 s.mu.Lock()
38 defer s.mu.Unlock()
39 
40 now := s.now()
41 c, ok := s.state[key]
42 if !ok || now.Sub(c.windowStart) >= s.window {
43 suppressed := 0
44 if ok {
45 suppressed = c.suppressed
46 }
47 s.state[key] = &counter{count: 1, windowStart: now}
48 return Decision{Log: true, Suppressed: suppressed}
49 }
50 
51 c.count++
52 if c.count <= s.threshold {
53 return Decision{Log: true}
54 }
55 
56 c.suppressed++
57 return Decision{Log: false}
58}
01 / 01
STEP 01

Walkthrough

Space play ←→ step click any line
Three takeaways
  1. 1Tumbling time windows reset counters on first access after the window elapses, avoiding a background sweep.
  2. 2Guarding shared map state with a mutex keeps a sampler safe for concurrent callers.
  3. 3Injecting the clock as a func() time.Time makes time-based logic testable without waiting.

Related explainers

go 
package streaming
 
import (
	"bufio"

Streaming NDJSON logs over HTTP in Go

http-streaming channels select
Advanced 10 steps
go 
package api
 
import (
	"crypto/sha256"

ETag conditional requests in Gin

http-caching etag conditional-requests
Intermediate 6 steps
go 
func (w *Watcher) resetDebounce(d time.Duration) {
	if !w.timer.Stop() {
		select {
		case <-w.timer.C:

Debouncing a stream of events in Go

debounce timers channels
Advanced 7 steps
go 
package logging
 
import (
	"context"

Deduplicating log attributes in Go's slog

decorator-pattern structured-logging immutability
Intermediate 8 steps
python 
import secrets
 
from django.contrib.auth import authenticate, login
from django.core.cache import cache

Two-factor login with OTP in Django

two-factor-auth one-time-passwords caching
Intermediate 9 steps
rust 
use std::collections::VecDeque;
use std::sync::{Arc, Condvar, Mutex};
use std::time::{Duration, Instant};
 

Building a counting semaphore in Rust

concurrency synchronization condition-variable
Advanced 9 steps

Share this explainer

Here's the card — post it anywhere.

A per-key rate limiter for log sampling — share card
Made with highlit — turn any snippet into a walkthrough like this in about a minute.
Explain your code