Probabilistic Sampling

Use cases and patterns for probabilistic pipeline execution

The sometimes action enables probabilistic execution of pipelines, useful for sampling, testing, and gradual feature rollouts.

Common Use Cases

Request Sampling

Collect detailed logs or metrics from a subset of requests to reduce overhead:

sometimes 10% {
    debug "User: %{aaa.identity} from %{radius.client.ip}";
} else {
    debug "Skipped detailed logging";
}

Use fine-grained ratios for rare event sampling:

# Sample 0.01% (1 in 10,000)
sometimes 1/10000 {
    backend "DETAILED_ANALYTICS";
}

Gradual Feature Rollout

Incrementally route traffic to new backends, starting small and increasing over time:

# Start with 5%, increase to 25%, then 50%, then 100%
sometimes 5% {
    backend "NEW_AUTH_BACKEND";
} else {
    backend "LEGACY_AUTH_BACKEND";
}

Load Distribution

Probabilistically distribute load across different backends:

accounting {
    sometimes 50% {
        backend "ACCOUNTING_SYSTEM_A";
        accept;
    } else {
        backend "ACCOUNTING_SYSTEM_B";
        accept;
    }
}

Performance Testing

Introduce artificial delays to simulate load:

sometimes 20% {
    sleep 100ms;  # Slow down 20% of requests
}

Probability Formats

Two main formats:

sometimes 50% - percentage notation
sometimes 1/2 - ratio format

The ratio format is needed for probabilities below 1%:

sometimes 1/1000 - 0.1%
sometimes 1/10000 - 0.01%

Note: Plain numbers without % (e.g., 50) are supported for backwards compatibility.