1TRACE-CMD.DAT.V(5)             libtracefs Manual            TRACE-CMD.DAT.V(5)
2
3
4

NAME

6       trace-cmd.dat.v7 - trace-cmd version 7 file format
7

SYNOPSIS

9       trace-cmd.dat ignore
10

DESCRIPTION

12       The trace-cmd(1) utility produces a "trace.dat" file. The file may also
13       be named anything depending if the user specifies a different output
14       name, but it must have a certain binary format. The file is used by
15       trace-cmd to save kernel traces into it and be able to extract the
16       trace from it at a later point (see trace-cmd-report(1)).
17

INITIAL FORMAT

19           The first three bytes contain the magic value:
20
21           0x17 0x08  0x44
22
23           The next 7 bytes contain the characters:
24
25           "tracing"
26
27           The next set of characters contain a null '\0' terminated string
28           that contains the version of the file:
29
30           "7\0"
31
32           The next 1 byte contains the flags for the file endianess:
33
34           0 = little endian
35           1 = big endian
36
37           The next byte contains the number of bytes per "long" value:
38
39           4 - 32-bit long values
40           8 - 64-bit long values
41
42           Note: This is the long size of the target's user space. Not the
43           kernel space size.
44
45           [ Now all numbers are written in file defined endianess. ]
46
47           The next 4 bytes are a 32-bit word that defines what the traced
48           host machine page size was.
49
50           The compression algorithm header is written next:
51              "name\0version\0"
52           where "name" and "version" are strings, name and version of the
53           compression algorithm used to compress the trace file. If the name
54           is "none", the data in the file is not compressed.
55
56           The next 8 bytes are 64-bit integer, the offset within the file where
57           the first OPTIONS section is located.
58
59           The rest of the file consists of different sections. The only mandatory
60           is the first OPTIONS section, all others are optional. The location and
61           the order of the sections is not strict. Each section starts with a header:
62

FORMAT OF THE SECTION HEADER

64           <2 bytes> unsigned short integer, ID of the section.
65           <2 bytes> unsigned short integer, section flags:
66             1 = the section is compressed.
67           <4 bytes> ID of a string, description of the section.
68           <4 bytes> unsigned integer, size of the section in the file.
69
70           If the section is compressed, the above is the compressed size.
71           The section must be uncompressed on reading. The described format of
72           the sections refers to the uncompressed data.
73

COMPRESSION FORMAT OF THE FILE SECTIONS

75           Some of the sections in the file may be compressed with the compression algorithm,
76           specified in the compression algorithm header. Compressed sections have a compression
77           header, written after the section header and right before the compressed data:
78             <4 bytes> unsigned int, size of compressed data in this section.
79             <4 bytes> unsigned int, size of uncompressed data.
80             <data> binary compressed data, with the specified size.
81

COMPRESSION FORMAT OF THE TRACE DATA

83           There are two special sections, BUFFER FLYRECORD and BUFFER LATENCY, containing
84           trace data. These sections may be compressed with the compression algorithm, specified
85           in the compression header. Usually the size of these sections is huge, that's why its
86           compression format is different from the other sections. The trace data is compressed
87           in chunks The size of one chunk is specified in the file creation time. The format
88           of compressed trace data is:
89              <4 bytes> unsigned int, count of chunks.
90              Follows the compressed chunks of given count. For each chunk:
91                 <4 bytes> unsigned int, size of compressed data in this chunk.
92                 <4 bytes> unsigned int, size of uncompressed data, aligned with the trace page size.
93                 <data> binary compressed data, with the specified size.
94           These chunks must be uncompressed on reading. The described format of
95           trace data refers to the uncompressed data.
96

OPTIONS SECTION

98           Section ID: 0
99
100           This is the the only mandatory section in the file. There can be multiple
101           options sections, the first one is located at the offset specified right
102           after the compression algorithm header. The section consists of multiple
103           trace options, each option has the following format:
104             <2 bytes> unsigned short integer, ID of the option.
105             <4 bytes> unsigned integer, size of the option's data.
106             <binary data> bytes of the size specified above, data of the option.
107
108           Options, supported by the trace file version 7:
109
110           DONE: id 0, size 8
111             This option indicates the end of the options section, it is written
112             always as last option. The DONE option data is:
113                <8 bytes> long long unsigned integer, offset in the trace file where
114                the next options section is located. If this offset is 0, then there
115                are no more options sections.
116
117           DATE: id 1, size vary
118             The DATE option data is a null terminated ASCII string, which represents
119             the time difference between trace events timestamps and the Generic Time
120             of Day of the system.
121
122           CPUSTAT: id 2, size vary
123             The CPUSTAT option data is a null terminated ASCII string, the content of the
124             "per_cpu/cpu<id>/stats" file from the trace directory. There is a CPUSTAT option
125             for each CPU.
126
127           BUFFER: id 3, size vary
128             The BUFFER option describes the flyrecord trace data saved in the file, collected
129             from one trace instance. There is BUFFER option for each trace instance. The format
130             of the BUFFER data is:
131               <8 bytes> long long unsigned integer, offset in the trace file where the
132               BUFFER FLYRECORD section is located, containing flyrecord trace data.
133               <string> a null terminated ASCII string, name of the trace instance. Empty string ""
134               is saved as name of the top instance.
135               <string> a null terminated ASCII string, trace clock used for events timestamps in
136               this trace instance.
137               <4 bytes> unsigned integer, size of the trace buffer page.
138               <4 bytes> unsigned integer, count of the CPUs with trace data.
139               For each CPU of the above count:
140                  <4 bytes> unsigned integer, ID of the CPU.
141                  <8 bytes> long long unsigned integer, offset in the trace file where the trace data
142                  for this CPU is located.
143                  <8 bytes> long long unsigned integer, size of the trace data for this CPU.
144
145           TRACECLOCK: id 4, size vary
146             The TRACECLOCK option data is a null terminated ASCII string, the content of the
147             "trace_clock" file from the trace directory.
148
149           UNAME: id 5, size vary
150             The UNAME option data is a null terminated ASCII string, identifying the system where
151             the trace data is collected. The string is retrieved by the uname() system call.
152
153           HOOK: id 6, size vary
154             The HOOK option data is a null terminated ASCII string, describing event hooks: custom
155             event matching to connect any two events together.
156
157           OFFSET: id 7, size vary
158             The OFFSET option data is a null terminated ASCII string, representing a fixed time that
159             is added to each event timestamp on reading.
160
161           CPUCOUNT: id 8, size 4
162             The CPUCOUNT option data is:
163               <4 bytes> unsigned integer, number of CPUs in the system.
164
165           VERSION: id 9, size vary
166             The VERSION option data is a null terminated ASCII string, representing the version of
167             the trace-cmd application, used to collect these trace logs.
168
169           PROCMAPS: id 10, size vary
170             The PROCMAPS option data is a null terminated ASCII string, representing the memory map
171             of each traced filtered process. The format of the string is, for each filtered process:
172               <procss ID> <libraries count> <process command> \n
173                 <memory start address> <memory end address> <full path of the mapped library file> \n
174                 ...
175                  separate line for each library, used by this process
176                 ...
177               ...
178
179           TRACEID: id 11, size 8
180             The TRACEID option data is a unique identifier of this tracing session:
181               <8 bytes> long long unsigned integer, trace session identifier.
182
183           TIME_SHIFT: id 12, size vary
184             The TIME_SHIFT option stores time synchronization information, collected during host and guest
185             tracing session. Usually it is saved in the guest trace file. This information is used to
186             synchronize guest with host events timestamps, when displaying all files from this tracing
187             session. The format of the TIME_SHIFT option data is:
188               <8 bytes> long long unsigned integer, trace identifier of the peer (usually the host).
189               <4 bytes> unsigned integer, flags specific to the time synchronization protocol, used in this
190               trace session.
191               <4 bytes> unsigned integer, number of traced CPUs. For each CPU, timestamps corrections
192               are recorded:
193                  <4 bytes> unsigned integer, count of the recorded timestamps corrections for this CPU.
194                  <array of unsigned long long integers of the above count>, times when the corrections are calculated
195                  <array of unsigned long long integers of the above count>, corrections offsets
196                  <array of unsigned long long integers of the above count>, corrections scaling ratio
197
198           GUEST: id 13, size vary
199             The GUEST option stores information about traced guests in this tracing session. Usually it is
200             saved in the host trace file. There is a separate GUEST option for each traced guest.
201             The information is used when displaying all files from this tracing session. The format of
202             the GUEST option data is:
203                <string> a null terminated ASCII string, name of the guest.
204                <8 bytes> long long unsigned integer, trace identifier of the guest for this session.
205                <4 bytes> unsigned integer, number of guest's CPUs. For each CPU:
206                   <4 bytes> unsigned integer, ID of the CPU.
207                   <4 bytes> unsigned integer, PID of the host task, emulating this guest CPU.
208
209           TSC2NSEC: id 14, size 16
210             The TSC2NSEC option stores information, used to convert TSC events timestamps to nanoseconds.
211             The format of the TSC2NSEC option data is:
212                <4 bytes> unsigned integer, time multiplier.
213                <4 bytes> unsigned integer, time shift.
214                <8 bytes> unsigned long long integer, time offset.
215
216           HEADER_INFO: id 16, size 8
217             The HEADER_INFO option data is:
218               <8 bytes> long long unsigned integer, offset into the trace file where the HEADER INFO
219               section is located
220
221           FTRACE_EVENTS: id 17, size 8
222             The FTRACE_EVENTS option data is:
223               <8 bytes> long long unsigned integer, offset into the trace file where the
224               FTRACE EVENT FORMATS section is located.
225
226           EVENT_FORMATS: id 18, size 8
227             The EVENT_FORMATS option data is:
228               <8 bytes> long long unsigned integer, offset into the trace file where the EVENT FORMATS
229               section is located.
230
231           KALLSYMS: id 19, size 8
232             The KALLSYMS option data is:
233               <8 bytes> long long unsigned integer, offset into the trace file where the KALLSYMS
234               section is located.
235
236           PRINTK: id 20, size 8
237             The PRINTK option data is:
238               <8 bytes> long long unsigned integer, offset into the trace file where the TRACE_PRINTK
239               section is located.
240
241           CMDLINES: id 21, size 8
242             The CMDLINES option data is:
243               <8 bytes> long long unsigned integer, offset into the trace file where the
244               SAVED COMMAND LINES section is located.
245
246           BUFFER_TEXT: id 22, size
247             The BUFFER_LAT option describes the latency trace data saved in the file. The format
248             of the BUFFER_LAT data is:
249               <8 bytes> long long unsigned integer, offset in the trace file where the
250               BUFFER LATENCY section is located, containing latency trace data.
251               <string> a null terminated ASCII string, name of the trace instance. Empty string ""
252               is saved as name of the top instance.
253               <string> a null terminated ASCII string, trace clock used for events timestamps in
254               this trace instance.
255

HEADER INFO SECTION

257           Section ID: 16
258
259           The first 12 bytes of the section, after the section header, contain the string:
260
261           "header_page\0"
262
263           The next 8 bytes are a 64-bit word containing the size of the
264           page header information stored next.
265
266           The next set of data is of the size read from the previous 8 bytes,
267           and contains the data retrieved from debugfs/tracing/events/header_page.
268
269           Note: The size of the second field \fBcommit\fR contains the target
270           kernel long size. For example:
271
272           field: local_t commit;        offset:8;       \fBsize:8;\fR   signed:1;
273
274           shows the kernel has a 64-bit long.
275
276           The next 13 bytes contain the string:
277
278           "header_event\0"
279
280           The next 8 bytes are a 64-bit word containing the size of the
281           event header information stored next.
282
283           The next set of data is of the size read from the previous 8 bytes
284           and contains the data retrieved from debugfs/tracing/events/header_event.
285
286           This data allows the trace-cmd tool to know if the ring buffer format
287           of the kernel made any changes.
288

FTRACE EVENT FORMATS SECTION

290           Section ID: 17
291
292           Directly after the section header comes the information about
293           the Ftrace specific events. These are the events used by the Ftrace plugins
294           and are not enabled by the event tracing.
295
296           The next 4 bytes contain a 32-bit word of the number of Ftrace event
297           format files that are stored in the file.
298
299           For the number of times defined by the previous 4 bytes is the
300           following:
301
302           8 bytes for the size of the Ftrace event format file.
303
304           The Ftrace event format file copied from the target machine:
305           debugfs/tracing/events/ftrace/<event>/format
306

EVENT FORMATS SECTION

308           Section ID: 18
309
310           Directly after the section header comes the information about
311           the event layout.
312
313           The next 4 bytes are a 32-bit word containing the number of
314           event systems that are stored in the file. These are the
315           directories in debugfs/tracing/events excluding the \fBftrace\fR
316           directory.
317
318           For the number of times defined by the previous 4 bytes is the
319           following:
320
321           A null-terminated string containing the system name.
322
323           4 bytes containing a 32-bit word containing the number
324           of events within the system.
325
326           For the number of times defined in the previous 4 bytes is the
327           following:
328
329           8 bytes for the size of the event format file.
330
331           The event format file copied from the target machine:
332           debugfs/tracing/events/<system>/<event>/format
333

KALLSYMS SECTION

335           Section ID: 19
336
337           Directly after the section header comes the information of the mapping
338           of function addresses to the function names.
339
340           The next 4 bytes are a 32-bit word containing the size of the
341           data holding the function mappings.
342
343           The next set of data is of the size defined by the previous 4 bytes
344           and contains the information from the target machine's file:
345           /proc/kallsyms
346

TRACE_PRINTK SECTION

348           Section ID: 20
349
350           If a developer used trace_printk() within the kernel, it may
351           store the format string outside the ring buffer.
352           This information can be found in:
353           debugfs/tracing/printk_formats
354
355           The next 4 bytes are a 32-bit word containing the size of the
356           data holding the printk formats.
357
358           The next set of data is of the size defined by the previous 4 bytes
359           and contains the information from debugfs/tracing/printk_formats.
360

SAVED COMMAND LINES SECTION

362           Section ID: 21
363
364           Directly after the section header comes the information mapping
365           a PID to a process name.
366
367           The next 8 bytes contain a 64-bit word that holds the size of the
368           data mapping the PID to a process name.
369
370           The next set of data is of the size defined by the previous 8 bytes
371           and contains the information from debugfs/tracing/saved_cmdlines.
372

BUFFER FLYRECORD SECTION

374           This section contains flyrecord tracing data, collected in one trace instance.
375           The data is saved per CPU. Each BUFFER FLYRECORD section has a corresponding BUFFER
376           option, containing information about saved CPU's trace data. Padding is placed between
377           the section header and the CPU data, placing the CPU data at a page aligned (target page)
378           position in the file.
379
380           This data is copied directly from the Ftrace ring buffer and is of the
381           same format as the ring buffer specified by the event header files
382           loaded in the header format file.
383
384           The trace-cmd tool will try to \fBmmap(2)\fR the data page by page with the
385           target's page size if possible. If it fails to mmap, it will just read the
386           data instead.
387
388       BUFFER TEXT SECTION
389
390
391           .ft C
392             This section contains latency tracing data, ASCII text taken from the
393             target's debugfs/tracing/trace file.
394
395           STRINGS SECTION
396           .ft
397
398
399           All strings from trace file metadata are stored in string section in the file. The section
400           contains a list of NULL terminated ASCII strings. An ID of the string is used in the file
401           meta data, which is the offset of the actual string into the string section. Strings can be stored
402           into multiple string sections in the file.
403

SEE ALSO

405       trace-cmd(1), trace-cmd-record(1), trace-cmd-report(1),
406       trace-cmd-start(1), trace-cmd-stop(1), trace-cmd-extract(1),
407       trace-cmd-reset(1), trace-cmd-split(1), trace-cmd-list(1),
408       trace-cmd-listen(1), trace-cmd.dat(5)
409

AUTHOR

411       Written by Steven Rostedt, <rostedt@goodmis.org[1]>
412

RESOURCES

414       https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
415

COPYING

417       Copyright (C) 2010 Red Hat, Inc. Free use of this software is granted
418       under the terms of the GNU Public License (GPL).
419

NOTES

421        1. rostedt@goodmis.org
422           mailto:rostedt@goodmis.org
423
424
425
426libtracefs                        04/15/2022                TRACE-CMD.DAT.V(5)
Impressum