1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
|
<table class="head">
<tr>
<td class="head-ltitle">TRACING(7)</td>
<td class="head-vol">Miscellaneous Information Manual</td>
<td class="head-rtitle">TRACING(7)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">tracing</code> —
<span class="Nd">introduction to FreeBSD tracing and performance
monitoring</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp"><span class="Ux">FreeBSD</span> features a large variety of
tracing and performance monitoring facilities. Use them to measure
performance and troubleshoot kernel and userland problems both during
<a class="Xr">development(7)</a> and potentially on production systems. The
facilities differ in scope, ease of use, overhead, design, and
limitations.</p>
<section class="Ss">
<h2 class="Ss" id="DTrace"><a class="permalink" href="#DTrace">DTrace</a></h2>
<p class="Pp"><a class="Xr">dtrace(1)</a> is the most versatile tracing
framework available on <span class="Ux">FreeBSD</span> and is capable of
tracing throughout the <span class="Ux">FreeBSD</span> software stack from
the kernel to the applications running in userland. Refer to
<a class="Xr">dtrace(1)</a> and <a class="Xr">SDT(9)</a> for more
details.</p>
<p class="Pp"><a class="Xr">dwatch(1)</a> is a user-friendly wrapper for DTrace.
It simplifies common DTrace usage patterns and requires less expert
knowledge to operate.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Userland_Tracing"><a class="permalink" href="#Userland_Tracing">Userland
Tracing</a></h2>
<p class="Pp"><a class="Xr">truss(1)</a> traces system calls. It uses
<a class="Xr">sysdecode(3)</a> to pretty-print system call arguments and
<a class="Xr">ptrace(2)</a> to trace processes.</p>
<p class="Pp"><a class="Xr">ktrace(1)</a> is useful for debugging user programs.
It enables kernel trace logging for specified processes. Like
<a class="Xr">truss(1)</a>, it mainly traces system calls, but instead of
using <a class="Xr">ptrace(2)</a>, it asynchronously logs entries to a trace
file configured with <a class="Xr">ktrace(2)</a> (typically
<span class="Pa">ktrace.out</span>), and it can log other types of kernel
events, such as page faults and name lookups (refer to
<code class="Fl">-t</code> in <a class="Xr">ktrace(1)</a>). Also, programs
can log to a <a class="Xr">ktrace(1)</a> stream using the
<a class="Xr">utrace(2)</a> system call.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Kernel_Tracing"><a class="permalink" href="#Kernel_Tracing">Kernel
Tracing</a></h2>
<p class="Pp"><a class="Xr">ktr(4)</a> is a facility for logging strings in the
kernel. It comes in handy for some niche purposes during kernel development.
It lets kernel programmers log events to a global ring buffer, which can
later be dumped using <a class="Xr">ktrdump(8)</a>.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Hardware-Accelerated_Tracing"><a class="permalink" href="#Hardware-Accelerated_Tracing">Hardware-Accelerated
Tracing</a></h2>
<p class="Pp"><a class="Xr">hwt(4)</a> is a kernel trace framework providing
infrastructure for hardware-assisted tracing.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Hardware_Counters"><a class="permalink" href="#Hardware_Counters">Hardware
Counters</a></h2>
<p class="Pp"><a class="Xr">pmcstat(8)</a>, and its kernel counterpart,
<a class="Xr">hwpmc(4)</a>, is the <span class="Ux">FreeBSD</span> facility
for conducting performance measurements with hardware counters.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Boot-Time_And_Shutdown_Tracing"><a class="permalink" href="#Boot-Time_And_Shutdown_Tracing">Boot-Time
And Shutdown Tracing</a></h2>
<p class="Pp"><a class="Xr">boottrace(4)</a> is a facility for tracing events at
boot and shutdown. Its target audience are system administrators.</p>
<p class="Pp"><a class="Xr">tslog(4)</a> is a developer-oriented tool for
tracing boot-time events.</p>
</section>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<p class="Pp">The <code class="Nm">tracing</code> manual page was written by
<span class="An">Mateusz Piotrowski</span>
<<a class="Mt" href="mailto:0mp@FreeBSD.org">0mp@FreeBSD.org</a>>. It
first appeared in <span class="Ux">FreeBSD 15.0</span>.</p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">July 12, 2025</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
