Data Format

This page describes the structure of uftrace trace data which was generated by uftrace record command.

Overview

The uftrace data is saved under a directory (uftrace.data by default) and it contains following files

• info : various information about uftrace and running process
• task.txt : task and session information
• sid-<SESSION_ID>.map : memory mapping for a session
• <PROGRAM>.sym : (function) symbol address and name
• <TID>.dat : trace data for each task of given <TID>
• kernel_header : kernel ftrace header info (only if kernel tracing was used)
• kallsyms : kernel symbol information (ditto)
• kernel-cpuX.dat : per-cpu kernel tracing data (ditto)

The actual trace data is saved in the .dat file. It needs to resolve the addresses (in .dat file) to a symbol which was saved in the .sym file. But the .sym file only has the relative offsets so it also needs to find a base address from a (per-session) .map file. The task.txt file provides information that which (session) map should be used to resolve an address of a task at a given timestamp.

The info file

The info file provides metadata about the format as well as process and system information at the time of the recording. This file consists of two parts - the first is binary form of metadata and the second is text form of the information (which can be shown with uftrace info command).

• The metadata starts with a 8-byte magic string which is 0x46 0x74 0x72 0x61 0x63 0x65 0x21 0x00 or "Ftrace!".
• It's followed by a 4-byte number of file version and the current version is 4.
• And then there's a 2-byte number of header (metadata) size and the current value is 40 (or 0x28).
• The next byte identifies a byte-order (endian) in the data files. The value is same as the ELF format (EI_DATA: 1 is for the little-endian and 2 is for the big-endian).
• The next byte tells the size of address or long int type also same as the ELF format (EI_CLASS: 1 is for 32-bit and 2 is for 64-bit).
• Then 64-bit bit mask (feat_mask) of enabled features comes after it. The bit 0 is for PLT (library call) hooking, the bit 1 is for task and session info, the bit 2 is for kernel tracing, the bit 3 is for function arguments, the bit 4 is for function return value, the bit 5 is for whether symbol file contains relative offset or absolute address, and the bit 6 is for max (function) stack depth.
• The next 64-bit mask (info_mask) is for which kind of process and system information was saved after the metadata.
• And then it followed by a 2-byte number of maximum function call (stack) depth given by user.
• The rest 6-byte is reserved for future use and should be filled with zero.

After the metadata, info string follows in a "key:value" form. Basically a single bit in the info_mask corresponds to a single line in the info string. If it consists of two or more lines, the first line should tell how many lines comes after it. The uftrace info command will also show those info string in more readable format.