View Source erlperf_monitor (erlperf v2.2.0)

System monitor: reports scheduler, RAM, and benchmarks.

Monitor is started by default when erlperf starts as an application. Monitor is not started for ad-hoc benchmarking (e.g. command-line, unless verbose logging is requested).

When started, the monitor provides periodic reports about Erlang VM state, and registered jobs performance. The reports are sent to all processes that joined {erlperf_monitor, Node} or cluster_monitor process group in erlperf scope.

Reports can be received by any process, even the shell. Run the following example in rebar3 shell of erlperf:
   (erlperf@ubuntu22)1> ok = pg:join(erlperf, cluster_monitor, self()).
   (erlperf@ubuntu22)2> erlperf:run(rand, uniform, []).
   (erlperf@ubuntu22)4> flush().
   Shell got {erlperf@ubuntu22,#{dcpu => 0.0,dio => 6.42619095979426e-4,
                           ets => 44,jobs => [],memory_binary => 928408,
                           memory_ets => 978056,
                           memory_processes => 8603392,
                           memory_total => 34952096,ports => 5,
                           processes => 95,
                           sched_util => 0.013187335960637163,

Note that the monitor may report differently from the benchmark run results. It is running with lower priority and may be significantly affected by scheduler starvation, timing issues etc..

Link to this section Summary


Monitoring report

Monitor startup options


Registers an erlperf_job to monitor.

Starts the monitor.

Starts the monitor and links it to the current process. See start/1 for options description.

Removes the job from monitoring.

Link to this section Types

-type monitor_sample() ::
    #{time := integer(),
      node := node(),
      sched_util := float(),
      dcpu := float(),
      dio := float(),
      processes := integer(),
      ports := integer(),
      ets := integer(),
      memory_total := non_neg_integer(),
      memory_processes := non_neg_integer(),
      memory_binary := non_neg_integer(),
      memory_ets := non_neg_integer(),
      jobs => [{Job :: pid(), Cycles :: non_neg_integer()}]}.

Monitoring report

  • time: timestamp when the report is generates, wall clock, milliseconds
  • node: originating Erlang node name
  • sched_util: normal scheduler utilisation, percentage. See scheduler:utilization/1
  • dcpu: dirty CPU scheduler utilisation, percentage.
  • dio: dirty IO scheduler utilisation, percentage
  • processes: number of processes in the VM.
  • ports: number of ports in the VM.
  • ets: number of ETS tables created in the VM.
  • memory_total: total VM memory usage, see erlang:memory/1.
  • memory_processes: processes memory usage, see erlang:system_info/1.
  • memory_binary: binary memory usage.
  • memory_ets: ETS memory usage.
  • jobs: a map of job process identifier to the iterations surplus since last sample. If the sampling interval is default 1 second, the value of the map is "requests/queries per second" (RPS/QPS).
-type start_options() :: #{interval => pos_integer()}.

Monitor startup options

  • interval: monitoring interval, 1000 ms by default

Link to this section Functions

Link to this function

register(Job, Handle, Initial)

View Source
-spec register(pid(), term(), non_neg_integer()) -> ok.

Registers an erlperf_job to monitor.

Running monitor queries every registered job, adding the number of iterations performed by all workers of that job to the report. This API is intended to be used by erlperf_job to enable VM monitoring while benchmarking.

Job specifies job process identifier, it is only used to detect when job is stopped, to stop reporting counters for that job.

Handle is the sampling handle, see erlperf_job:handle/1.

Initial value should be provided when an existing job is registered, to avoid reporting accumulated counter value in the first report for that job.

Always return ok, even when monitor is not running.
-spec start() -> {ok, Pid :: pid()} | {error, Reason :: term()}.

Equivalent to start(#{interval => 1000}).

-spec start(Options :: start_options()) -> {ok, Pid :: pid()} | {error, Reason :: term()}.

Starts the monitor.

Options are used to change the monitor behaviour.
  • interval: time, in milliseconds, to wait between sample collection
-spec start_link() -> {ok, Pid :: pid()} | {error, Reason :: term()}.

Equivalent to start_link(#{interval => 1000}).

Starts the monitor and links it to the current process. See start/1 for options description.
-spec unregister(pid()) -> ok.

Removes the job from monitoring.

Stops reporting this job performance.

Job is the process identifier of the job.