birch - v0.1.0

birch/sampling

Sampling and rate limiting for high-volume logging scenarios.

This module provides probabilistic sampling and rate limiting to prevent log flooding in high-throughput applications.

Sampling

Sampling allows you to log only a percentage of messages at certain levels:

import birch as log
import birch/level
import birch/sampling

// Log only 10% of debug messages
log.configure([
  log.config_sampling(sampling.config(level.Debug, 0.1)),
])

Rate Limiting

Rate limiting uses a token bucket algorithm to limit logs per second:

import birch/sampling

// Allow max 100 logs/second with burst of 10
let config = sampling.rate_limit_config(100, 10)

Types

RateLimitConfig

</>

Configuration for rate limiting using a token bucket algorithm.

pub type RateLimitConfig {
  RateLimitConfig(max_per_second: Int, burst_size: Int)
}

Constructors 

  • RateLimitConfig(max_per_second: Int, burst_size: Int)

    Arguments

    max_per_second

    Maximum logs per second

    burst_size

    Burst size (maximum tokens that can accumulate)

SampleConfigType

</> 
pub type SampleConfigType =
  config.SampleConfig

TokenBucket

opaque </>

A token bucket for rate limiting.

The bucket starts with max_tokens and consumes one token per log. Tokens are refilled over time based on the rate.

pub opaque type TokenBucket

Values

bucket_burst_size

</> 
pub fn bucket_burst_size(bucket: TokenBucket) -> Int

Get the refill rate (burst size) for a bucket.

bucket_max_tokens

</> 
pub fn bucket_max_tokens(bucket: TokenBucket) -> Int

Get the maximum tokens for a bucket.

config

</> 
pub fn config(
  lvl: level.Level,
  rate: Float,
) -> config.SampleConfig

Create a sampling configuration.

  • lvl: Apply sampling to this level and all levels below it
  • rate: Probability of logging (0.0 = never, 1.0 = always)

The rate is clamped to the valid range [0.0, 1.0].

new_token_bucket

</> 
pub fn new_token_bucket(
  max_tokens: Int,
  refill_rate: Int,
) -> TokenBucket

Create a new token bucket.

  • max_tokens: Maximum tokens the bucket can hold (burst capacity)
  • refill_rate: Tokens added per second

rate_limit_config

</> 
pub fn rate_limit_config(
  max_per_second: Int,
  burst_size: Int,
) -> RateLimitConfig

Create a rate limit configuration.

  • max_per_second: Target rate limit (tokens added per second)
  • burst_size: Maximum burst capacity (allows brief spikes above rate)

should_sample

</> 
pub fn should_sample(
  sample_config: config.SampleConfig,
  log_level: level.Level,
) -> Bool

Check if a log at the given level should be sampled (logged).

Returns True if the log should be emitted, False if it should be dropped.

  • Logs above the sample config level are always logged
  • Logs at or below the sample config level are sampled probabilistically

should_sample_with_config

</> 
pub fn should_sample_with_config(
  maybe_config: Result(config.SampleConfig, Nil),
  log_level: level.Level,
) -> Bool

Check if a log should be sampled, given an optional SampleConfig.

If no config is provided (Error), always returns True (log everything).

try_consume

</> 
pub fn try_consume(bucket: TokenBucket) -> #(Bool, TokenBucket)

Try to consume a token from the bucket.

Returns a tuple of:

  • Bool: True if token was consumed (log allowed), False if bucket empty
  • TokenBucket: The updated bucket state
✨ Search Document