Skip to content

Core

Async collector

AsyncCollector: bounded, drop-oldest queue with background batch writer.

  • Non-blocking enqueue (drops oldest when full)
  • Background writer thread batches and flushes to a provided sink
  • atexit handler drains remaining items
  • Graceful shutdown: best-effort flush with timeout; never blocks exit beyond timeout
  • Collector crash handling: after consecutive sink failures, sink is disabled (noop)

Configuration: - queue_size (int): max buffer size (default 2048) - flush_interval (float): seconds between periodic flush attempts (default 0.5s) - batch_max (int): maximum batch size per sink call (default 256) - max_consecutive_sink_failures (int): after this many failures, disable sink (default 5)

AsyncCollector

Bases: Generic[T]

queue_depth property

Current number of items in the buffer (thread-safe).

close(*, timeout=2.0)

Stop the background thread and best-effort flush with timeout; never block exit beyond timeout.

enqueue(item)

Non-blocking enqueue.

If the buffer is full, drop the oldest item and append the new one. This method never blocks on back-pressure.

Emitter

Emitter: hot-path event creation + enqueue to AsyncCollector.

  • Builds tiny dicts for REQ/FN/DB events
  • Optimized to minimize allocations (≤15µs/event target)

Stats

StatsStore: rolling 15-minute window with RPS, error%, percentiles, sparkline.

Sampling

Shared sampling policy: global rate, route excludes (prefix/regex), per-route overrides, always 5xx.

Used by ASGI middleware and Sanic adapter for deterministic tests (seedable RNG) and consistent behavior across adapters.

clamp_sampling_rate(rate)

Clamp sampling rate to [0.0, 1.0]. Raises ValueError if not in range (for strict validation).

get_effective_rate(path, compiled_overrides, default_rate)

Return sampling rate for path: first matching override, or default_rate.

make_rng(random_seed=None, rng=None)

Return a callable that returns a float in [0, 1). Prefer rng if provided, else seeded Random, else system random.

should_exclude_route(path, compiled)

Return True if path matches any exclude (prefix or regex).

should_record_request(sampled, status_code, error_info, always_sample_errors, error_threshold=HTTP_ERROR_STATUS_THRESHOLD)

Return True if request should be recorded (sampled or 5xx/exception when always_sample_errors).

should_sample_request(rate, rng)

Return True if this request should be sampled according to rate and RNG.