ref: 95db2e9ddeaa3e85d4c7867541da72476db4a3c8
dir: /sys/man/1/prof/
.TH PROF 1 .SH NAME prof, tprof, kprof \- display profiling data .SH SYNOPSIS .B prof [ .B -dr ] .I program .I profile .PP .B flambe .I program .I profile .PP .B tprof .I pid .PP .B kprof .I kernel .I kpdata .SH DESCRIPTION .I Prof interprets files produced automatically by programs loaded using the .B -p option of .IR 2l (1) or other loader. The symbol table in the named .I program file is read and correlated with the .I profile file. For each symbol, the percentage of time (in seconds) spent executing between that symbol and the next is printed (in decreasing order), together with the time spent there and the number of times that routine was called. .PP Under option .BR -d , .I prof prints the dynamic call graph of the target program, annotating the calls with the time spent in each routine and those it calls, recursively. The output is indented two spaces for each call, and is formatted as .IP .EX symbol:time/ncall .EE .LP where .I symbol is the entry point of the call, .I time is in seconds, and .I ncall is the number of times that entry point was called at that point in the call graph. If .I ncall is one, the .B /ncall is elided. Normally recursive calls are compressed to keep the output brief; option .B -r prints the full call graph. .PP The size of the buffer in .I program used to hold the profiling data, by default 256k entries, may be controlled by setting the environment variable .B profsize before running .IR program . If the buffer fills, subsequent function calls may not be recorded. .PP The profiling code provided by the linker initializes itself to profile the current pid, producing a file called .B prof.\f2pid\fP. If a process forks, only the parent will continue to be profiled. Forked children can cause themselves to be profile by calling .IP .EX prof(fn, arg, entries, what) .EE .LP which causes the function \f2fn\fP(\f2arg\fP) to be profiled. When \f2fn\fP returns .B prof.\f2pid\fP is produced for the current process pid. .PP The environment variable .B proftype can be set to one of .BR user , .BR kernel , .BR elapsed , or .BR sample , to profile time measured spent in user mode, time spent in user+kernel mode, or elapsed time, using the cycle counter, or the time in user mode using the kernel's HZ clock. The cycle counter is currently only available on modern PCs and on the PowerPC. Default profiling measures user time, using the cycle counter if it is available. .PP .I Flambe presents an interactive flame graph using information gathered by .IR prof . The graph is presented as a series of rows, each row representing a level in the call stack. Each row is split up among all the siblings of the respective call stack level, their width representative of the portion of their parent's time they occupied. Hovering the mouse over any block shows its full name, the total time spent in the function, and the number of calls made to it in the top left hand side of the window. Clicking a block reroots the the graph with the selected block as the base. The escape key can be used to return to the real root of the graph. .PP .I Tprof is similar to .IR prof , but is intended for profiling multiprocess programs. It uses the .BI /proc/ pid /profile file to collect instruction frequency counts for the text image associated with the process, for all processes that share that text. It must be run while the program is still active, since the data is stored with the running program. To enable .I tprof profiling for a given process, .IP .EX echo profile > /proc/\f2pid\f1/ctl .EE .LP and then, after the program has run for a while, execute .IP .EX tprof \f2pid\f1 .EE .LP Since the data collected for .I tprof is based on interrupt-time sampling of the program counter, .I tprof has no .B -d or .B -r options. .PP .I Kprof is similar to .IR prof , but presents the data accumulated by the kernel profiling device, .IR kprof (3) . The symbol table file, that of the operating system kernel, and the data file, typically .BR /dev/kpdata , must be provided. .I Kprof has no options and cannot present dynamic data. .SH SOURCE .B /sys/src/cmd/prof.c .br .B /sys/src/cmd/kprof.c .SH SEE ALSO .IR 2l (1), .IR exec (2), .IR kprof (3)