Perform sound benchmarking of Clojure code.
Provides functions and macros for measuring code performance while accounting for:
Primary API:
Example: (bench (+ 1 1)) ; Basic usage (bench (+ 1 1) :viewer :pprint) ; With pretty-printed output (set-default-viewer! :kindly) ; Set default for all bench calls
Perform sound benchmarking of Clojure code. Provides functions and macros for measuring code performance while accounting for: - JVM warmup periods - Garbage collection effects - Statistical significance Primary API: - bench - Macro for benchmarking expressions - bench-measured - Function for benchmarking pre-wrapped measurements - last-bench - Access results from most recent benchmark - set-default-viewer! - Set default output viewer - default-viewer - Get current default viewer Example: (bench (+ 1 1)) ; Basic usage (bench (+ 1 1) :viewer :pprint) ; With pretty-printed output (set-default-viewer! :kindly) ; Set default for all bench calls
(analyze analyse-plan data-map)Apply statistical analysis to collected metrics.
Parameters: analyse-config - Vector of analysis steps to perform metrics - Raw metrics from collect-metrics
Returns analyzed metrics with statistical computations added.
Apply statistical analysis to collected metrics. Parameters: analyse-config - Vector of analysis steps to perform metrics - Raw metrics from collect-metrics Returns analyzed metrics with statistical computations added.
(bench expr & options)Main macro for benchmarking Clojure expressions with statistical rigor.
Intended for simplified use at the REPL.
Takes an expression to benchmark, and optional configuration options.
Parameters: expr - Expression to benchmark (may reference local bindings) options - Keyword/value pairs for configuration: :viewer - Output format [:print, :pprint, :portal, :kindly] Default can be set via (set-default-viewer! :kindly) :analyse - Vector of analysis steps [[:outliers] [:stats]] :view - Vector of view components [:stats] :metric-ids - Vector of metrics to collect, from: [:elapsed-time :garbage-collector :finalization :memory :thread-allocation :compilation :measured-args :class-loader] :limit-time-s - Time limit in seconds (optional) :collect-plan - Sampling strategy (optional) :time-fn - Custom timing function (optional)
:warmup-args-fn - Function returning arguments for warmup phase
(optional). When specified, warmup uses varied
inputs from this function instead of the expression's
captured arguments, enabling more representative JIT
optimization. This option is baked into the Measured
at macro expansion time.
:with-allocation-trace - When true, collect allocation trace and display
allocation analysis (summary, hotspots, by-type). Requires
the native agent to be attached. (optional)
Returns: The value from evaluating the expression. Complete benchmark data available via (last-bench).
Examples: ;; Basic usage (bench (+ 1 1))
;; With pretty-printed output (bench (+ 1 1) :viewer :pprint)
;; With local bindings (let [data (vec (range 1000))] (bench (reduce + data)))
;; With specific metrics and time limit (bench (my-function) :metric-ids [:elapsed-time :memory] :limit-time-s 5)
;; With warmup using varied inputs (let [coll (vec (range 1000))] (bench (sort coll) :warmup-args-fn (fn [] [(vec (shuffle (range 5000)))])))
(bench (+ 1 1) :viewer :portal :benchmark (criterium.benchmark/->benchmark {:analyse [[:quantiles {:quantiles [0.025 0.5 0.975]}] :outliers :stats] :view [:stats :quantiles :samples :histogram]}))
For the portal viewer, you will need to have portal connected to tap>.
Notes:
Main macro for benchmarking Clojure expressions with statistical rigor.
Intended for simplified use at the REPL.
Takes an expression to benchmark, and optional configuration options.
Parameters:
expr - Expression to benchmark (may reference local bindings)
options - Keyword/value pairs for configuration:
:viewer - Output format [:print, :pprint, :portal, :kindly]
Default can be set via (set-default-viewer! :kindly)
:analyse - Vector of analysis steps [[:outliers] [:stats]]
:view - Vector of view components [:stats]
:metric-ids - Vector of metrics to collect, from:
[:elapsed-time :garbage-collector :finalization
:memory :thread-allocation :compilation
:measured-args :class-loader]
:limit-time-s - Time limit in seconds (optional)
:collect-plan - Sampling strategy (optional)
:time-fn - Custom timing function (optional)
:warmup-args-fn - Function returning arguments for warmup phase
(optional). When specified, warmup uses varied
inputs from this function instead of the expression's
captured arguments, enabling more representative JIT
optimization. This option is baked into the Measured
at macro expansion time.
:with-allocation-trace - When true, collect allocation trace and display
allocation analysis (summary, hotspots, by-type). Requires
the native agent to be attached. (optional)
Returns:
The value from evaluating the expression.
Complete benchmark data available via (last-bench).
Examples:
;; Basic usage
(bench (+ 1 1))
;; With pretty-printed output
(bench (+ 1 1) :viewer :pprint)
;; With local bindings
(let [data (vec (range 1000))]
(bench (reduce + data)))
;; With specific metrics and time limit
(bench (my-function)
:metric-ids [:elapsed-time :memory]
:limit-time-s 5)
;; With warmup using varied inputs
(let [coll (vec (range 1000))]
(bench (sort coll)
:warmup-args-fn (fn [] [(vec (shuffle (range 5000)))])))
(bench (+ 1 1)
:viewer :portal
:benchmark (criterium.benchmark/->benchmark
{:analyse [[:quantiles {:quantiles [0.025 0.5 0.975]}]
:outliers
:stats]
:view [:stats :quantiles :samples :histogram]}))
For the portal viewer, you will need to have portal connected to tap>.
Notes:
- Handles JVM warmup automatically
- Accounts for GC interference
- Ensures statistical significance
- Local bindings from enclosing scope can be used in the expression(bench-measured bench-plan measured)Evaluate measured and output the benchmark time.
By default, return the value of calling the measured's wrapped function.
The timing info is available as a data structure by calling last-time.
Takes a bench-plan that fully specifies the benchmark behaviour.
Evaluate measured and output the benchmark time. By default, return the value of calling the measured's wrapped function. The timing info is available as a data structure by calling last-time. Takes a bench-plan that fully specifies the benchmark behaviour.
(collect-data-map collector-config collect-plan measured)Collect metrics according to the sampling plan.
Parameters: collector-config - Configuration for the metric collector collect-plan - Strategy for collecting samples measured - The wrapped code/function to measure
Returns collected measurements.
Collect metrics according to the sampling plan. Parameters: collector-config - Configuration for the metric collector collect-plan - Strategy for collecting samples measured - The wrapped code/function to measure Returns collected measurements.
(default-viewer)Returns the current default viewer.
The default viewer is used when no explicit :viewer option is provided to bench calls. Initial value is :print.
Returns the current default viewer. The default viewer is used when no explicit :viewer option is provided to bench calls. Initial value is :print.
(last-bench)Returns the complete measurement data from the most recent benchmark.
The returned data structure contains all metrics, statistical analysis, and raw measurements from the last call to bench or bench-measured.
Returns nil if no benchmarks have been run in the current session.
Example: (bench (+ 1 1)) (let [results (last-bench)] ;; Access detailed metrics from results )
Returns the complete measurement data from the most recent benchmark. The returned data structure contains all metrics, statistical analysis, and raw measurements from the last call to bench or bench-measured. Returns nil if no benchmarks have been run in the current session. Example: (bench (+ 1 1)) (let [results (last-bench)] ;; Access detailed metrics from results )
(options->bench-plan & {:as options})Explicit conversion of bench options into a bench-plan.
Explicit conversion of `bench` options into a bench-plan.
(set-default-viewer! viewer)Set the default viewer for all bench calls that don't specify an explicit :viewer option.
viewer - Keyword identifying the viewer, e.g. :print, :pprint, :portal, :kindly
Example: (set-default-viewer! :kindly) (bench (+ 1 1)) ; Now uses :kindly viewer by default
Set the default viewer for all bench calls that don't specify an explicit
:viewer option.
viewer - Keyword identifying the viewer,
e.g. :print, :pprint, :portal, :kindly
Example:
(set-default-viewer! :kindly)
(bench (+ 1 1)) ; Now uses :kindly viewer by default(view view-plan viewer data-map)Format and present analyzed metrics.
Parameters: view-config - Vector of view components to include metrics - Analyzed metrics from analyze-metrics options - Additional view options like :viewer
Returns the viewed metrics data structure.
Format and present analyzed metrics. Parameters: view-config - Vector of view components to include metrics - Analyzed metrics from analyze-metrics options - Additional view options like :viewer Returns the viewed metrics data structure.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |