1 <!DOCTYPE html PUBLIC
"-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/2002/REC-xhtml1-20020801/DTD/xhtml1-strict.dtd">
2 <html xmlns=
"http://www.w3.org/1999/xhtml" xml:
lang=
"en" lang=
"en">
5 <title>The LTTng trace format
</title>
10 <h1>The LTTng trace format
</h1>
13 <em>Last update:
2008/
06/
02</em>
17 This document describes the LTTng trace format. It should be useful mainly to
18 developers who code the LTTng tracer or the traceread LTTV library, as this
19 library offers all the necessary abstractions on top of the raw trace data.
23 A trace is contained in a directory tree. To send a trace remotely, the
24 directory tree may be tar-gzipped. The trace
<tt>foo
</tt>, placed in the home
25 directory of user john, /home/john, would have the following contents:
52 The root directory contains a tracefile for each cpu, numbered from
0,
53 in .trace format. A uniprocessor thus only contains the file cpu_0.
54 A multi-processor with some unused (possibly hotplug) CPU slots may have some
55 unused CPU numbers. For instance an
8 way SMP board with
6 CPUs randomly
56 installed may produce tracefiles named
0,
1,
2,
4,
6,
7.
60 The files in the control directory also follow the .trace format and are
61 also per cpu. The
"facilities" files only contain
"core" marker_id,
62 marker_format and time_heartbeat events. The first two are used to describe the
63 events that are in the trace. The other control files contain the initial
64 system state and various subsequent important events, for example process
65 creations and exit. The interest of placing such subsequent events in control
66 trace files instead of (or in addition to) in the per cpu trace files is that
67 they may be accessed more quickly/conveniently and that they may be kept even
68 when the per cpu files are overwritten in
"flight recorder mode".
74 Each tracefile is divided into equal size blocks with a header at the beginning
75 of the block. Events are packed sequentially in the block starting right after
80 Each block consists of :
84 block start/end header
87 event
1 variable length data
89 event
2 variable length data
94 <h3>The block start/end header
</h3>
98 * the beginning of buffer information
100 * TSC at the beginning of the buffer
102 * frequency of the CPUs at the beginning of the buffer.
104 * the end of buffer information
106 * TSC at the end of the buffer
108 * frequency of the CPUs at the end of the buffer.
110 * number of bytes of padding at the end of the buffer.
112 * size of the sub-buffer.
117 <h3>The trace header
</h3>
121 *
0x00D6B7ED, used to check the trace byte order vs host byte order.
123 * Architecture type of the traced machine.
125 * Architecture variant of the traced machine. May be unused on some arch.
126 uint32 float_word_order
127 * Byte order of floats and doubles, sometimes different from integer byte
128 order. Useful only for user space traces.
130 * Size (in bytes) of the void * on the traced machine.
132 * major version of the trace.
134 * minor version of the trace.
135 uint8 flight_recorder
136 * Is flight recorder mode activated ? If yes, data might be missing
137 (overwritten) in the trace.
139 * Does this trace have heartbeat timer event activated ?
140 Yes (
1) -
> Event header has
32 bits TSC
141 No (
0) -
> Event header has
64 bits TSC
143 * Are event headers in this trace aligned ?
144 Yes -
> the value indicates the alignment
145 No (
0) -
> data is packed.
146 uint8 tsc_lsb_truncate
148 uint8 compact_data_shift
150 event time is always calculated from :
151 trace_start_time + ((event_tsc - trace_start_tsc) * (freq / freq_scale))
153 * CPUs clock frequency at the beginnig of the trace.
155 * TSC at the beginning of the trace.
156 uint64 start_monotonic
157 * monotonically increasing time at the beginning of the trace.
158 (currently not supported)
160 * Real time at the beginning of the trace (as given by date, adjusted by NTP)
161 This is the only time reference with the real world : the rest of the trace
162 has monotonically increasing time from this point (with TSC difference and
169 <h3>Event header
</h3>
172 Event headers differ according to the following conditions : does the
173 traced system have a heartbeat timer? Is tracing alignment activated?
183 * if has_heartbeat :
32 LSB of the cycle counter at the event record time.
184 * else :
64 bits complete cycle counter.
186 * Numerical ID of the facility corresponding to the event. See the facility
187 tracefile to know which facility ID matches which facility name and
190 * Numerical ID of the event inside the facility.
192 * Size of the variable length data that follows this header.
196 Event header alignment
200 If trace alignment is activated (
<tt>alignment
</tt>), the event header is
201 aligned. In addition, padding is automatically added after the event header so
202 the variable length data is automatically aligned on the architecture size.
206 <h2>System description</h2>
209 The system type description, in system.xml, looks like:
215 domainname="polymtl.ca"
220 kernel_release="2.4.18-686-smp"
221 kernel_version="#1 SMP Sun Apr 14 12:07:19 EST 2002"
224 hardware_platform="unknown"
225 operating_system="Linux"
226 ltt_major_version="2"
227 ltt_minor_version="0"
228 ltt_block_size="100000"
230 Some comments about the system
235 The system attributes kernel_name, node_name, kernel_release,
236 kernel_version, machine, processor, hardware_platform and operating_system
237 come from the uname(1) program. The domainname attribute is obtained from
238 the "hostname --domain" command. The arch_size attribute is one of
239 LP32, ILP32, LP64 or ILP64 and specifies the length in bits of integers (I),
240 long (L) and pointers (P). The endian attribute is "little" or "big".
241 While the arch_size and endian attributes could be deduced from the platform
242 type, having these explicit allows analysing traces from yet unknown
243 platforms. The cpu attribute specifies the maximum number of processors in
244 the system; only tracefiles 0 to this maximum - 1 may exist in the cpu
249 Within the system element, the text enclosed may describe further the
257 Bookmarks are user supplied information added to a trace. They contain user
258 annotations attached to a time interval.
264 <location name=name cpu=n start_time=t end_time=t>Some text</location>
270 The interval is defined using either "time=" or "start_time=" and
271 "end_time=", or "cycle=" or "start_cycle=" and "end_cycle=".
272 The time is in seconds with decimals up to nanoseconds and cycle counts
273 are unsigned integers with a 64 bits range. The cpu attribute is optional.