viva_telemetry/bench

viva_telemetry/bench - Statistical benchmarking for Gleam

Inspired by: criterion (Rust), benchee (Elixir), hyperfine

Features

Statistical analysis (mean, stddev, percentiles)
Confidence intervals (bootstrapping)
Multiple inputs and functions
Comparison with speedup calculation
Export to JSON/CSV/Markdown
Regression detection

Quick Start

import viva_telemetry/bench

pub fn main() {
  bench.run("my_function", fn() { my_function() })
  |> bench.print()
}

Types

BenchResult

</>

Benchmark result

pub type BenchResult {
  BenchResult(name: String, samples: List(Int), stats: Stats)
}

Constructors

BenchResult(name: String, samples: List(Int), stats: Stats)

Comparison

</>

Comparison between two benchmarks

pub type Comparison {
  Comparison(
    baseline: String,
    target: String,
    speedup: Float,
    significant: Bool,
    ci_95: #(Float, Float),
  )
}

Constructors

Comparison(
  baseline: String,
  target: String,
  speedup: Float,
  significant: Bool,
  ci_95: #(Float, Float),
)

Config

</>

Benchmark configuration

pub type Config {
  Config(
    warmup_iterations: Int,
    iterations: Int,
    confidence: Float,
  )
}

Constructors

Config(
  warmup_iterations: Int,
  iterations: Int,
  confidence: Float,
)

Stats

</>

Statistical summary

pub type Stats {
  Stats(
    mean: Float,
    stddev: Float,
    min: Int,
    max: Int,
    p50: Int,
    p95: Int,
    p99: Int,
    ips: Float,
    ci_95: #(Float, Float),
  )
}

Constructors

Stats(
  mean: Float,
  stddev: Float,
  min: Int,
  max: Int,
  p50: Int,
  p95: Int,
  p99: Int,
  ips: Float,
  ci_95: #(Float, Float),
)

Values

compare

</>

pub fn compare(
  baseline: BenchResult,
  target: BenchResult,
) -> Comparison

Compare two benchmark results

config

</>

pub fn config(warmup: Int, iterations: Int) -> Config

Config with custom iterations

default_config

</>

pub fn default_config() -> Config

Default configuration

print

</>

pub fn print(result: BenchResult) -> Nil

Print benchmark result to console

print_comparison

</>

pub fn print_comparison(cmp: Comparison) -> Nil

Print comparison result

run

</>

pub fn run(name: String, f: fn() -> a) -> BenchResult

Run a single benchmark with default config

run_all

</>

pub fn run_all(
  benchmarks: List(#(String, fn() -> a)),
  cfg: Config,
) -> List(BenchResult)

Run multiple benchmarks

run_with_config

</>

pub fn run_with_config(
  name: String,
  f: fn() -> a,
  cfg: Config,
) -> BenchResult

Run benchmark with custom config

to_json

</>

pub fn to_json(result: BenchResult) -> json.Json

Export to JSON

to_json_string

</>

pub fn to_json_string(result: BenchResult) -> String

Export to JSON string

to_markdown

</>

pub fn to_markdown(result: BenchResult) -> String

Export to Markdown table row

to_markdown_table

</>

pub fn to_markdown_table(results: List(BenchResult)) -> String

Export multiple results to Markdown table