Beamchmark v1.3.0

View Source Beamchmark (Beamchmark v1.3.0)

Top level module providing Beamchmark.run/2 API.

Beamchmark measures EVM performance while it is running user Beamchmark.Scenario.

Metrics being measured

Scheduler Utilization

At the moment, the main interest of Beamchmark is scheduler utilization which tells how much given scheduler was busy. Scheduler is busy when:

  • Executing process code
  • Executing linked-in driver or NIF code
  • Executing BIFs, or any other runtime handling
  • Garbage collecting
  • Handling any other memory management

Scheduler utilization is measured using Erlang's :scheduler module which uses :erlang.statistics/1 under the hood and it is represented as a floating point value between 0.0 and 1.0 and percent.

Beamchmark measures following types of scheduler utilization:

  • normal/cpu/io - average utilization of single scheduler of given type
  • total normal/cpu/io - average utilization of all schedulers of given type. E.g total normal equals 1.0 when each of normal schedulers have been active all the time
  • total - average utilization of all schedulers
  • weighted - average utilization of all schedulers weighted against maximum amount of available CPU time

For more information please refer to :erlang.statistics/1 (under :scheduler_wall_time) or :scheduler.utilization/1.

Other

Other metrics being measured:

  • reductions - total reductions number
  • context switches - total context switches number

Link to this section Summary

Types

options_t()

Configuration for Beamchmark.

Functions

run(scenario, opts \\ [])

Runs scenario and benchmarks EVM performance.

Link to this section Types

Link to this type

options_t()

View Source

Specs

options_t() :: [
  name: String.t(),
  duration: pos_integer(),
  cpu_interval: pos_integer(),
  delay: non_neg_integer(),
  formatters: [Beamchmark.Formatter.t()],
  compare?: boolean(),
  output_dir: Path.t()
]

Configuration for Beamchmark.

  • name - name of the benchmark. It can be used by formatters.
  • duration - time in seconds Beamchmark will be benchmarking EVM. Defaults to 60 seconds.
  • cpu_interval - time in milliseconds Beamchmark will be benchmarking cpu usage. Defaults to 1000 milliseconds. Needs to be greater than or equal to interfere_timeout.
  • delay - time in seconds Beamchmark will wait after running scenario and before starting benchmarking. Defaults to 0 seconds.
  • formatters - list of formatters that will be applied to the result. By default contains only Beamchmark.Formatters.Console.
  • compare? - boolean indicating whether formatters should compare results for given scenario with the previous one. Defaults to true.
  • output_dir - directory where results of benchmarking will be saved. Defaults to "beamchmark" directory under location provided by System.tmp_dir!/0.

Link to this section Functions

Link to this function

run(scenario, opts \\ [])

View Source

Specs

run(Beamchmark.Scenario.t(), options_t()) :: :ok

Runs scenario and benchmarks EVM performance.

If compare? option equals true, invocation of this function will also compare new measurements with the last ones. Measurements will be compared only if they share the same scenario module, delay and duration.