NAME

       scheduler - Measure scheduler utilization

DESCRIPTION

       This module contains utility functions for easier measurement and calculation of scheduler
       utilization,    otherwise     obtained     from     calling     the     more     primitive
       statistics(scheduler_wall_time).

       The simplest usage is to call scheduler:utilization(Seconds).

DATA TYPES

       sched_sample()

       sched_type() = normal | cpu | io

       sched_id() = integer()

       sched_util_result() =
           [{sched_type(), sched_id(), float(), string()} |
            {total, float(), string()} |
            {weighted, float(), string()}]

              A list of tuples containing results for individual schedulers as well as aggregated
              averages. Util is the scheduler utilization as a floating point value  between  0.0
              and  1.0. Percent is the same utilization as a more human readable string expressed
              in percent.

                {normal, SchedulerId, Util, Percent}:
                  Scheduler utilization of a normal scheduler with number SchedulerId. Schedulers
                  that  are  not  online will also be included. Online schedulers have the lowest
                  SchedulerId.

                {cpu, SchedulerId, Util, Percent}:
                  Scheduler utilization of a dirty-cpu scheduler with number SchedulerId.

                {io, SchedulerId, Util, Percent}:
                  Scheduler utilization of a dirty-io scheduler  with  number  SchedulerId.  This
                  tuple will only exist if both samples were taken with sample_all/0.

                {total, Util, Percent}:
                  Total utilization of all normal and dirty-cpu schedulers.

                {weighted, Util, Percent}:
                  Total  utilization  of  all  normal  and dirty-cpu schedulers, weighted against
                  maximum amount of available CPU time.

EXPORTS

       sample() -> sched_sample()

              Return a scheduler utilization sample for normal and dirty-cpu schedulers.

       sample_all() -> sched_sample()

              Return a scheduler  utilization  sample  for  all  schedulers,  including  dirty-io
              schedulers.

       utilization(Seconds) -> sched_util_result()

              Types:

                 Seconds = integer() >= 1

              Measure utilization for normal and dirty-cpu schedulers during Seconds seconds, and
              then return the result.

       utilization(Sample) -> sched_util_result()

              Types:

                 Sample = sched_sample()

              Calculate scheduler utilizations for the time interval from when Sample  was  taken
              and     "now".     The     same     as     calling    scheduler:utilization(Sample,
              scheduler:sample_all()).

          Note:
              Scheduler utilization is measured  as  an  average  value  over  a  time  interval,
              calculated  as  the  difference between two samples. To get good useful utilization
              values at least a couple of seconds should have passed between the two samples. For
              this reason, you should not do

              scheduler:utilization(scheduler:sample()). % DO NOT DO THIS!

              The  above  example  takes  two  samples  in  rapid  succession  and calculates the
              scheduler utilization between them. The resulting  values  will  probably  be  more
              misleading than informative.

              Instead   use   scheduler:utilization(Seconds)   or  let  some  time  pass  between
              Sample=scheduler:sample() and scheduler:utilization(Sample).

       utilization(Sample1, Sample2) -> sched_util_result()

              Types:

                 Sample1 = Sample2 = sched_sample()

              Calculates scheduler utilizations for the time interval  between  the  two  samples
              obtained from calling sample/0 or sample_all/0.