dtrace_sched (4)
Leading comments
Copyright (c) 2015 Mark Johnston <markj@FreeBSD.org> All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the docum...
NAME
dtrace_sched - a DTrace provider for tracing CPU scheduling eventsSYNOPSIS
Fn sched:::change-pri struct thread * struct proc * uint8_t Fn sched:::dequeue struct thread * struct proc * void * Fn sched:::enqueue struct thread * struct proc * void * int Fn sched:::lend-pri struct thread * struct proc * uint8_t struct thread * Fn sched:::load-change int int Fn sched:::off-cpu struct thread * struct proc * Fn sched:::on-cpu Fn sched:::preempt Fn sched:::remain-cpu Fn sched:::surrender struct thread * struct proc * Fn sched:::sleep Fn sched:::tick struct thread * struct proc * Fn sched:::wakeup struct thread * struct proc *DESCRIPTION
The DTrace sched provider allows the tracing of events related to CPU scheduling in the 4BSD and ULE schedulers.The Fn 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 Fn 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 Fn 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 Fn sched:::dequeue are the thread and corresponding process. The third argument is currently always NULL The Fn 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 Fn 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 Fn sched:::off-cpu probe is triggered by the scheduler suspending execution of the currently-running thread, and the Fn 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 Fn 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 Fn sched:::remain-cpu probe will fire instead.
The Fn 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 Fn 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 Fn sched:::off-cpu or Fn sched:::remain-cpu probes will subsequently fire, depending on whether or not the scheduler selects the preempted thread.
The Fn 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 Fn 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 Fn sched:::tick fires before each scheduler clock tick. Its arguments are the currently-running thread and its corresponding process.
ARGUMENTS
The sched provider probes use the kernel types Vt struct proc and Vt struct thread 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 Vt struct thread * . For example, when a running thread is about to sleep, the Fn 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.EXAMPLES
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.
COMPATIBILITY
This provider is not compatible with the sched provider found in Solaris. In particular, the probe argument types are native Fx types, and the Fn sched:::cpucaps-sleep , Fn sched:::cpucaps-wakeup , Fn sched:::schedctl-nopreempt , Fn sched:::schedctl-preempt , and Fn sched:::schedctl-yield probes are not available in Fx .The Fn sched:::lend-pri and Fn sched:::load-change probes are specific to Fx .