profile Provider

{anchor:top}
h1. {anchor:CHP-PROFILE} {{profile}} Provider
The {{profile}} provider provides probes associated with a time-based interrupt firing every fixed, specified time interval. These _unanchored_ probes that are not associated with any particular point of execution, but rather with the asynchronous interrupt event. These probes can be used to sample some aspect of system state every unit time and the samples can then be used to infer system behavior. If the sampling rate is high, or the sampling time is long, an accurate inference is possible. Using DTrace actions, the {{profile}} provider can be used to sample practically anything in the system. For example, you could sample the state of the current thread, the state of the CPU, or the current machine instruction.

[Top|#top]
h2. {anchor:CHP-PROFILE-1} {{profile-}}_n_ probes
A {{profile-}}_n_ probe fires every fixed interval on every CPU at high interrupt level. The probe's firing interval is denoted by the value of _n_: the interrupt source will fire _n_ times per second. _n_ may also have an optional time suffix, in which case _n_ is interpreted to be in the units denoted by the suffix. Valid suffixes and the units they denote are listed in [Table 19–1|#TBL-TIMEUNITS].
h6. {anchor:TBL-TIMEUNITS} Valid time suffixes
||Suffix||Time Units||
|{{nsec}} or {{ns}}|nanoseconds|
|{{usec}} or {{us}}|microseconds|
|{{msec}} or {{ms}}|milliseconds|
|{{sec}} or {{s}}|seconds|
|{{min}} or {{m}}|minutes|
|{{hour}} or {{h}}|hours|
|{{day}} or {{d}}|days|
|{{hz}}|hertz (frequency per second)|
The following example creates a probe to fire at 97 hertz to sample the currently running process:
{noformat}
#pragma D option quiet

profile-97
/pid != 0/
{
@proc[pid, execname] = count();
}

END
{
printf("%-8s %-40s %s\n", "PID", "CMD", "COUNT");
printa("%-8d %-40s %@d\n", @proc);
}
{noformat}
Running the above example for a brief period of time results in output similar to the following example:
{noformat}
# dtrace -s ./prof.d
^C
PID CMD COUNT
223887 sh 1
100360 httpd 1
100409 mibiisa 1
223887 uname 1
218848 sh 2
218984 adeptedit 2
100224 nscd 3
3 fsflush 4
2 pageout 6
100372 java 7
115279 xterm 7
100460 Xsun 7
100475 perfbar 9
223888 prstat 15
{noformat}
You can also use the {{profile-}}_n_ provider to sample information about the running process. The following example D script uses a 1,001 hertz profile probe to sample the current priority of a specified process:
{noformat}
profile-1001
/pid == $1/
{
@proc[execname] = lquantize(curlwpsinfo->pr_pri, 0, 100, 10);
}
{noformat}
To see this example script in action, type the following commands in one window:
{noformat}
$ echo $$
494621
$ while true ; do let i=0 ; done
{noformat}
In another window, run the D script for a brief period of time:
{noformat}
# dtrace -s ./profpri.d 494621
dtrace: script './profpri.d' matched 1 probe
^C
ksh
value ------------- Distribution ------------- count
< 0 | 0
0 |@@@@@@@@@@@@@@@@@@@@@ 7443
10 |@@@@@@ 2235
20 |@@@@ 1679
30 |@@@ 1119
40 |@ 560
50 |@ 554
60 | 0
{noformat}
This output shows the bias of the timesharing scheduling class. Because the shell process is spinning on the CPU, its priority is constantly being lowered by the system. If the shell process were running less frequently, its priority would be higher. To see this result, type Control-C in the spinning shell and run the script again:
{noformat}
# dtrace -s ./profpri.d 494621
dtrace: script './profpri.d' matched 1 probe
{noformat}
Now in the shell, type a few characters. When you terminate the DTrace script, output like the following example will appear:
{noformat}
ksh
value ------------- Distribution ------------- count
40 | 0
50 |@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ 14
60 | 0
{noformat}
Because the shell process was sleeping awaiting user input instead of spinning on the CPU, when it _did_ run it was run at a much higher priority.

h2. {anchor:CHP-PROFILE-4} Arguments
The arguments to {{profile}} probes are as follows:
|{{arg0}}|The program counter (PC) in the kernel at the time that the probe fired, or 0 if the current process was not executing in the kernel at the time that the probe fired|
|{{arg1}}|The PC in the user-level process at the time that the probe fired, or 0 if the current process was executing at the kernel at the time that the probe fired|
As the descriptions imply, if {{arg0}} is non-zero then {{arg1}} is zero; if {{arg0}} is zero then {{arg1}} is non-zero. Thus, you can use {{arg0}} and {{arg1}} to differentiate user-level from kernel level, as in this simple example:
{noformat}
profile-1ms
{
@ticks[arg0 ? "kernel" : "user"] = count();
}
{noformat}

[Top|#top]
h2. {anchor:CHP-PROFILE-5} Timer Resolution
The {{profile}} provider uses arbitrary resolution interval timers in the operating system. On architectures that do not support truly arbitrary resolution time-based interrupts, the frequency is limited by the system clock frequency, which is specified by the {{hz}} kernel variable. Probes of higher frequency than {{hz}} on such architectures will fire some number of times every 1/{{hz}} seconds. For example, a 1000 hertz {{profile}} probe on such an architecture with {{hz}} set to 100 will fire ten times in rapid succession every ten milliseconds. On platforms that support arbitrary resolution, a 1000 hertz {{profile}} probe would fire exactly every one millisecond.\\
\\The following example tests a given architecture's resolution:
{noformat}
profile-5000
{
/*
* We divide by 1,000,000 to convert nanoseconds to milliseconds, and
* then we take the value mod 10 to get the current millisecond within
* a 10 millisecond window. On platforms that do not support truly
* arbitrary resolution profile probes, all of the profile-5000 probes
* will fire on roughly the same millisecond. On platforms that
* support a truly arbitrary resolution, the probe firings will be
* evenly distributed across the milliseconds.
*/
@ms = lquantize((timestamp / 1000000) % 10, 0, 10, 1);
}

tick-1sec
/i++ >= 10/
{
exit(0);
}
{noformat}
On an architecture that supports arbitrary resolution {{profile}} probes, running the example script will yield an even distribution:
{noformat}
# dtrace -s ./restest.d
dtrace: script './restest.d' matched 2 probes
CPU ID FUNCTION:NAME
0 33631 :tick-1sec
value ------------- Distribution ------------- count
< 0 | 0
0 |@@@ 10760
1 |@@@@ 10842
2 |@@@@ 10861
3 |@@@ 10820
4 |@@@ 10819
5 |@@@ 10817
6 |@@@@ 10826
7 |@@@@ 10847
8 |@@@@ 10830
9 |@@@@ 10830
{noformat}
On an architecture that does not support arbitrary resolution {{profile}} probes, running the example script will yield an uneven distribution:
{noformat}
# dtrace -s ./restest.d
dtrace: script './restest.d' matched 2 probes
CPU ID FUNCTION:NAME
0 28321 :tick-1sec
value ------------- Distribution ------------- count
4 | 0
5 |@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ 107864
6 | 424
7 | 255
8 | 496
9 | 0
{noformat}
On these architectures, {{hz}} may be manually tuned in {{/etc/system}} to improve the effective profile resolution.\\
\\Currently, all variants of UltraSPARC ({{sun4u}}) support arbitrary resolution {{profile}} probes. Many variants of the x86 architecture ({{i86pc}}) also support arbitrary resolution {{profile}} probes, although some older variants do not.

[Top|#top]
h2. {anchor:CHP-PROFILE-6} Probe Creation
Unlike other providers, the {{profile}} provider creates probes dynamically on an as-needed basis. Thus, the desired profile probe might not appear in a listing of all probes (for example, by using {{dtrace -l -P profile}}) but the probe will be created when it is explicitly enabled.\\
\\On architectures that support arbitrary resolution {{profile}} probes, a time interval that is too short would cause the machine to continuously field time-based interrupts, thereby denying service on the machine. To prevent this situation, the {{profile}} provider will silently refuse to create any probe that would result in an interval of less than two hundred microseconds.

[Top|#top]
h2. {anchor:CHP-PROFILE-STABILITY} Stability
The {{profile}} provider uses DTrace's stability mechanism to describe its stabilities as shown in the following table. For more information about the stability mechanism, see [Chapter&nbsp;39, Stability|Stability].
||Element||Name stability||Data stability||Dependency class||
|Provider|Evolving|Evolving|Common|
|Module|Unstable|Unstable|Unknown|
|Function|Private|Private|Unknown|
|Name|Evolving|Evolving|Common|
|Arguments|Evolving|Evolving|Common|
{excerpt:hidden=true}Converted by tech dogg's sgml2wiki on Tue 20 Nov 2007 at 9:26:39 PM{excerpt}