dtrace_sched — a DTrace provider for tracing CPU scheduling events

       The sched provider probes use the kernel types structproc and structthread to represent  processes  and
       threads,  respectively.   These  structures  have  many fields and are defined in sys/proc.h.  In a probe
       body, the currently-running thread can always be obtained with the curthread global variable,  which  has
       type  structthread*.  For example, when a running thread is about to sleep, the sched:::sleep() probe
       fires in the context of that thread, which can be accessed using curthread.  The curcpu  global  variable
       contains the cpuid of the CPU on which the currently-running thread is executing.

       This manual page was written by Mark Johnston <markj@FreeBSD.org>.

Debian                                           April 18, 2015                                  DTRACE_SCHED(4)

       This provider is not compatible with the sched provider found  in  Solaris.   In  particular,  the  probe
       argument  types  are  native  FreeBSD  types,  and the sched:::cpucaps-sleep(), sched:::cpucaps-wakeup(),
       sched:::schedctl-nopreempt(), sched:::schedctl-preempt(), and  sched:::schedctl-yield()  probes  are  not
       available in FreeBSD.

       The sched:::lend-pri() and sched:::load-change() probes are specific to FreeBSD.

       The  DTrace  sched  provider  allows  the tracing of events related to CPU scheduling in the 4BSD and ULE
       schedulers.

       The sched:::change-pri() probe fires when a thread's active scheduling priority is about to  be  updated.
       The  first  two  arguments  are  the  thread whose priority is about to be changed, and the corresponding
       process.  The third argument is the new absolute priority for the thread,  while  the  current  value  is
       given  by  args[0]->td_priority.   The  sched:::lend-pri()  probe fires when the currently-running thread
       elevates the priority of another thread via priority lending.  The first two  arguments  are  the  thread
       whose  priority  is  about  to  be changed, and the corresponding process.  The third argument is the new
       absolute priority for the thread.  The fourth argument is the currently-running thread.

       The sched:::dequeue() probe fires immediately before a runnable thread is removed from  a  scheduler  run
       queue.   This  may  occur  when the thread is about to begin execution on a CPU, or because the thread is
       being migrated to a different run queue.  The latter  event  may  occur  in  several  circumstances:  the
       scheduler may be attempting to rebalance load between multiple CPUs, the thread's scheduling priority may
       have  changed,  or  the  thread's  CPU  affinity  settings  may have changed.  The first two arguments to
       sched:::dequeue() are the thread and corresponding process.  The third argument is currently always NULL.
       The sched:::enqueue() probe fires when a runnable thread is about to be added to a scheduler  run  queue.
       Its first two arguments are the thread and corresponding process.  The third argument is currently always
       NULL.  The fourth argument is a boolean value that is non-zero if the thread is enqueued at the beginning
       of its run queue slot, and zero if the thread is instead enqueued at the end.

       The  sched:::load-change()  probe fires after the load of a thread queue is adjusted.  The first argument
       is the cpuid for the CPU associated with the thread queue, and the second argument is the  adjusted  load
       of the thread queue, i.e., the number of elements in the queue.

       The  sched:::off-cpu()  probe is triggered by the scheduler suspending execution of the currently-running
       thread, and the sched:::on-cpu() probe fires when the current thread has been selected to run  on  a  CPU
       and  is  about  to  begin  or  resume  execution.   The arguments to sched:::off-cpu() are the thread and
       corresponding process selected to run following the currently-running thread.  If these two  threads  are
       the same, the sched:::remain-cpu() probe will fire instead.

       The  sched:::surrender() probe fires when the scheduler is called upon to make a scheduling decision by a
       thread running on a different CPU, via an interprocessor interrupt.  The arguments to this probe are  the
       interrupted  thread  and  its corresponding process.  This probe currently always fires in the context of
       the interrupted thread.

       The sched:::preempt() probe will fire immediately before the currently-running thread is preempted.  When
       this occurs, the scheduler will select a  new  thread  to  run,  and  one  of  the  sched:::off-cpu()  or
       sched:::remain-cpu() probes will subsequently fire, depending on whether or not the scheduler selects the
       preempted thread.

       The  sched:::sleep()  probe  fires  immediately  before  the currently-running thread is about to suspend
       execution and begin waiting for a condition to be met.  The sched:::wakeup() probe fires when a thread is
       set up to resume execution after having gone to sleep.  Its arguments are the thread  being  awoken,  and
       the corresponding process.

       The  sched:::tick()  fires  before  each  scheduler  clock tick.  Its arguments are the currently-running
       thread and its corresponding process.

       The following script gives a breakdown of CPU utilization by process name:

             sched:::on-cpu
             {
                     self->ts = timestamp;
             }

             sched:::off-cpu
             /self->ts != 0/
             {
                     @[execname] = sum((timestamp - self->ts) / 1000);
                     self->ts = 0;
             }

       Here,  DTrace stores a timestamp each time a thread is scheduled to run, and computes the time elapsed in
       microseconds when it is descheduled.  The results are summed by process name.

       The sched provider first appeared in FreeBSD 8.4 and 9.1.

       dtrace_sched — a DTrace provider for tracing CPU scheduling events

dtrace(1), sched_4bsd(4), sched_ule(4), SDT(9), sleepqueue(9)

sched:::change-pri(structthread*, structproc*, uint8_t);

       sched:::dequeue(structthread*, structproc*, void*);

       sched:::enqueue(structthread*, structproc*, void*, int);

       sched:::lend-pri(structthread*, structproc*, uint8_t, structthread*);

       sched:::load-change(int, int);

       sched:::off-cpu(structthread*, structproc*);

       sched:::on-cpu();

       sched:::preempt();

       sched:::remain-cpu();

       sched:::surrender(structthread*, structproc*);

       sched:::sleep();

       sched:::tick(structthread*, structproc*);

       sched:::wakeup(structthread*, structproc*);