+++ /dev/null
-<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-<html>
-<head>
- <title>The LTTng trace format</title>
-</head>
- <body>
-
-<h1>The LTTng trace format</h1>
-
-<P>
-This document describes the LTTng trace format. It should be used only by
-developers who code the LTTng tracer or the traceread LTTV library, as this
-library offers all the necessary abstractions on top of the raw trace data.
-
-<P>
-A trace is contained in a directory tree. To send a trace remotely,
-the directory tree may be tar-gzipped. Trace foo, placed in the home
-directory of user john, /home/john, would have the following content:
-
-<PRE><TT>
-$ cd /home/john
-$ tree foo
-foo/
-|-- eventdefs
-| |-- core.xml
-| |-- fs.xml
-| |-- ipc.xml
-| |-- kernel.xml
-| |-- memory.xml
-| |-- network.xml
-| |-- process.xml
-| |-- s390_kernel.xml
-| |-- socket.xml
-| |-- timer.xml
-| `-- ...
-|-- info
-| |-- bookmarks.xml
-| `-- system.xml
-|-- control
-| |-- facilities_0
-| |-- facilities_1
-| |-- facilities_...
-| |-- interrupts_0
-| |-- interrupts_1
-| |-- interrupts_...
-| |-- modules_0
-| |-- modules_1
-| |-- modules_...
-| `-- processes_0
-| `-- processes_1
-| `-- processes_...
-|-- cpu_0
-|-- cpu_1
-`-- cpu_...
-
-</TT></PRE>
-
-<P>
-The eventdefs directory contains the events descriptions for all the
-facilities used. The syntax is a simple subset of XML; XML is widely
-known and easily parsed or hand edited. Each file contains one or more
-<FACILITY NAME=name>...</FACILITY> elements. Indeed, several
-facilities may have the same name but different content (and thus will
-generate a different checksum). It typically happens when, while tracing
-is enabled, a module using the named facility is unloaded, modified
-(along with the description of some events), recompiled and reloaded.
-Then, the trace will contain events from two different, similarly named,
-facility versions.
-
-<P>
-A small number of events are predefined, part of the "core" facility,
-and are not present there. These "core" events include "facility_load",
-"facility_unload", "time_heartbeat" and "state_dump_facility_load".
-
-<P>
-The root directory contains a tracefile for each cpu, numbered from 0,
-in .trace format. A uniprocessor thus only contains the file cpu_0.
-A multi-processor with some unused (possibly hotplug) CPU slots may have some
-unused CPU numbers. For instance a 8 way SMP board with 6 CPUs randomly
-installed may produce tracefiles named 0, 1, 2, 4, 6, 7.
-
-<P>
-The files in the control directory also follow the .trace format and are also
-per cpu.
-The "facilities" file only contains "core" facility_load, facility_unload,
-time_heartbeat and state_dump_facility_load events
-and is used to determine the facilities used and the code range assigned
-to each facility. The other control files contain the initial system
-state and various subsequent important events, for example process
-creations and exit. The interest of placing such subsequent events
-in control trace files instead of (or in addition to) in the per cpu
-trace files is that they may be accessed more quickly/conveniently
-and that they may be kept even when the per cpu files are overwritten
-in "flight recorder mode".
-
-<P>
-The info directory contains in system.xml a description of the system on which
-the trace was created as well as different user annotations in bookmark.xml.
-This directory may also contain various information about the trace, generated
-during trace analysis (statistics, index...).
-
-
-<H2>Trace format</H2>
-
-<P>
-Each tracefile is divided into equal size blocks with a header at the beginning
-of the block. Events are packed sequentially in the block starting right after
-the block header.
-<P>
-Each block consists of :
-<PRE><TT>
-block start/end header
-trace header
-event 1 header
-event 1 variable length data
-event 2 header
-event 2 variable length data
-....
-padding
-</TT></PRE>
-
-<P>
-The block start/end header
-
-<PRE><TT>
-begin
- * the beginning of buffer information
- uint64 cycle_count
- * TSC at the beginning of the buffer
- uint64 freq
- * frequency of the CPUs at the beginning of the buffer.
-end
- * the end of buffer information
- uint64 cycle_count
- * TSC at the beginning of the buffer
- uint64 freq
- * frequency of the CPUs at the end of the buffer.
-uint32 lost_size
- * number of bytes of padding at the end of the buffer.
-uint32 buf_size
- * size of the sub-buffer.
-</TT></PRE>
-
-
-
-<P>
-The trace header
-
-<PRE><TT>
-uint32 magic_number
- * 0x00D6B7ED, used to check the trace byte order vs host byte order.
-uint32 arch_type
- * Architecture type of the traced machine.
-uint32 arch_variant
- * Architecture variant of the traced machine. May be unused on some arch.
-uint32 float_word_order
- * Byte order of floats and doubles, sometimes different from integer byte
- order. Useful only for user space traces.
-uint8 arch_size
- * Size (in bytes) of the void * on the traced machine.
-uint8 major_version
- * major version of the trace.
-uint8 minor_version
- * minor version of the trace.
-uint8 flight_recorder
- * Is flight recorder mode activated ? If yes, data might be missing
- (overwritten) in the trace.
-uint8 has_heartbeat
- * Does this trace have heartbeat timer event activated ?
- Yes (1) -> Event header has 32 bits TSC
- No (0) -> Event header has 64 bits TSC
-uint8 has_alignment
- * Is the information in this trace aligned ?
- Yes (1) -> aligned on min(arch size, atomic data size).
- No (0) -> data is packed.
-uint32 freq_scale
- event time is always calculated from :
- trace_start_time + ((event_tsc - trace_start_tsc) * (freq / freq_scale))
-uint64 start_freq
- * CPUs clock frequency at the beginnig of the trace.
-uint64 start_tsc
- * TSC at the beginning of the trace.
-uint64 start_monotonic
- * monotonically increasing time at the beginning of the trace.
- (currently not supported)
-start_time
- * Real time at the beginning of the trace (as given by date, adjusted by NTP)
- This is the only time reference with the real world : the rest of the trace
- has monotonically increasing time from this point (with TSC difference and
- clock frequency).
- uint32 seconds
- uint32 nanoseconds
-</TT></PRE>
-
-
-<P>
-Event header
-
-<P>
-Event headers differs depending on those conditions : does the traced system has
-a heartbeat timer ? Is tracing alignment activated ?
-
-<P>
-Event header :
-<PRE><TT>
-{ uint32 timestamp
- or
- uint64 timestamp }
- * if has_heartbeat : 32 LSB of the cycle counter at the event record time.
- * else : 64 bits complete cycle counter.
-uint8 facility_id
- * Numerical ID of the facility corresponding to the event. See the facility
- tracefile to know which facility ID matches which facility name and
- description.
-uint8 event_id
- * Numerical ID of the event inside the facility.
-uint16 event_size
- * Size of the variable length data that follows this header.
-</TT></PRE>
-
-<P>
-Event header alignment
-
-<P>
-If trace alignment is activated (has_alignment), the event header is aligned
-on the architecture size (void pointer size). In addition, a padding is
-automatically added after the event header so the variable length data is
-automatically aligned on the architecture size.
-
-<P>
-
-<H2>System description</H2>
-
-<P>
-The system type description, in system.xml, looks like:
-
-<PRE><TT>
-<system
- node_name="vaucluse"
- domainname="polymtl.ca"
- cpu=4
- arch_size="ILP32"
- endian="little"
- kernel_name="Linux"
- kernel_release="2.4.18-686-smp"
- kernel_version="#1 SMP Sun Apr 14 12:07:19 EST 2002"
- machine="i686"
- processor="unknown"
- hardware_platform="unknown"
- operating_system="Linux"
- ltt_major_version="2"
- ltt_minor_version="0"
- ltt_block_size="100000"
->
-Some comments about the system
-</system>
-</TT></PRE>
-
-<P>
-The system attributes kernel_name, node_name, kernel_release,
- kernel_version, machine, processor, hardware_platform and operating_system
-come from the uname(1) program. The domainname attribute is obtained from
-the "hostname --domain" command. The arch_size attribute is one of
-LP32, ILP32, LP64 or ILP64 and specifies the length in bits of integers (I),
-long (L) and pointers (P). The endian attribute is "little" or "big".
-While the arch_size and endian attributes could be deduced from the platform
-type, having these explicit allows analysing traces from yet unknown
-platforms. The cpu attribute specifies the maximum number of processors in
-the system; only tracefiles 0 to this maximum - 1 may exist in the cpu
-directory.
-
-<P>
-Within the system element, the text enclosed may describe further the
-system traced.
-
-
-<H2>Event type descriptions</H2>
-
-<P>
-A facility contains the descriptions of several event types. When a structure
-is reused in several event types, a named type is defined and may be referenced
-by several other event types or named types.
-
-<PRE><TT>
-<facility name=facility_name>
- <description>Some text</description>
- <event name=eventtype_name>
- <description>Some text</description>
- --type structure--
- </event>
- ...
- <type name=type_name>
- --type structure--
- </type>
-</facility>
-</TT></PRE>
-
-<P>
-The type structure may be one of the following primitive type elements.
-Whenever the keyword isize is used, the allowed values are
-short, medium, long, 1, 2, 4, 8, indicating the size in bytes.
-The fsize keyword represents one of medium, long, 4 and 8 bytes.
-
-<PRE><TT>
-<int size=isize format="printf format"/>
-
-<uint size=isize format="printf format"/>
-
-<float size=fsize format="printf format"/>
-
-<string format="printf format"/>
-
-<enum size=isize format="printf format">label1 label2 ...</enum>
-</TT></PRE>
-
-<P>
-The string is null terminated. For the enumeration, the size of the integer
-used for its representation is specified.
-
-<P>
-The type structure may also be a compound type.
-
-<PRE><TT>
-<array size=n> --type structure-- </array>
-
-<sequence lengthsize=isize> --type structure-- </sequence>
-
-<struct>
- <field name=field_name>
- <description>Some text</description>
- --type structure--
- </field>
- ...
-</struct>
-
-<union typecodesize=isize>
- <field name=field_name>
- <description>Some text</description>
- --type structure--
- </field>
- ...
-</union>
-</TT></PRE>
-
-<P>
-Array is a fixed size array of length size. Sequence is a variable size
-array with its length stored as a prepended uint of length lengthsize.
-A structure is simply an aggregation of fields. An union is one of its n
-fields (variant record), as indicated by a preceeding code (0 to n - 1)
-of the specified size typecodesize.
-
-<P>
-Finally the type structure may be defined by referencing a named type.
-
-<PRE><TT>
-<typeref name=type_name/>
-</PRE></TT>
-
-<H2>Core events</H2>
-
-<P>
-The facility named "core" is always present and contains at least the
-following event types.
-
-<PRE><TT>
-<event name=facility_load>
- <description>Facility used in the trace</description>
- <struct>
- <field name="name"><string/></field>
- <field name="checksum"><uint size=4/></field>
- <field name="id"><uint size=4/></field>
- <field name="int_size"><uint size=4/></field>
- <field name="long_size"><uint size=4/></field>
- <field name="pointer_size"><uint size=4/></field>
- <field name="size_t_size"><uint size=4/></field>
- <field name="has_alignment"><uint size=4/></field>
- </struct>
-</event>
-
-<event name=state_dump_facility_load>
- <description>Facility used in the trace</description>
- <struct>
- <field name="name"><string/></field>
- <field name="checksum"><uint size=4/></field>
- <field name="id"><uint size=4/></field>
- <field name="int_size"><uint size=4/></field>
- <field name="long_size"><uint size=4/></field>
- <field name="pointer_size"><uint size=4/></field>
- <field name="size_t_size"><uint size=4/></field>
- <field name="has_alignment"><uint size=4/></field>
- </struct>
-</event>
-
-<event name=time_heartbeat>
- <description>System time values sent periodically to minimize cycle counter
- drift with respect to real time clock and to detect cycle counter
- rollovers
- </description>
- <typeref name=timestamp/>
-</event>
-
-<type name=timestamp>
- <struct>
- <field name="seconds"><uint size=4/></field>
- <field name="nanoseconds"><uint size=4/></field>
- <field name="cycle_count"><uint size=8/></field>
- </struct>
-</event>
-
-</TT></PRE>
-
-<H2>Control files</H2>
-
-<P>
-The interrupts file reflects the content of the /proc/interrupts system file.
-It contains one event describing each interrupt. At trace start, events are
-generated describing all the current interrupts. If the assignment of
-interrupts changes later, due to devices or device drivers being activated or
-deactivated, additional events may be added to the file. Each interrupt
-event has the following structure.
-
-<PRE><TT>
-<event name=interrupt>
- <description>Interrupt request number assignment<description>
- <struct>
- <field name="number"><uint size=4/></field>
- <field name="count"><uint size=4/></field>
- <field name="controller"><string/></field>
- <field name="name"><string/></field>
- </struct>
-</event>
-</TT></PRE>
-
-<P>
-The processes file contains the list of processes already created when the
-trace starts. Each process describing event is modeled after the
-/proc/self/status system file. The number of fields in this event is
-expected to be expanded in the future to include groups, signal masks,
-opened file descriptors and address maps.
-
-<PRE><TT>
-<event name=process>
- <description>Existing process<description>
- <struct>
- <field name="name"><string/></field>
- <field name="pid"><uint size=4/></field>
- <field name="ppid"><uint size=4/></field>
- <field name="tracer_pid"><uint size=4/></field>
- <field name="uid"><uint size=4/></field>
- <field name="euid"><uint size=4/></field>
- <field name="suid"><uint size=4/></field>
- <field name="fsuid"><uint size=4/></field>
- <field name="gid"><uint size=4/></field>
- <field name="egid"><uint size=4/></field>
- <field name="sgid"><uint size=4/></field>
- <field name="fsgid"><uint size=4/></field>
- <field name="state"><enum size=4>
- Running WaitInterruptible WaitUninterruptible Zombie Traced Paging
- </enum></field>
- </struct>
-</event>
-</TT></PRE>
-
-<H2>Facilities</H2>
-
-<P>
-Facilities define a granularity of events grouping for filtering, activation
-and compilation. Each facility does cost a table entry in the kernel (name,
-checksum, event type code range), or somewhere between 20 and 30 bytes. Having
-one facility per tracing statement in the kernel would be too much (assuming
-that they eventually are routinely inserted in the kernel code and replace
-the 80000+ printk statements in some proportion). However, having a few
-facilities, up to a few tens, would make sense.
-
-<P>
-The "builtin" facility contains a small number of predefined events which must
-always exist. The "core" facility contains a small subset of OS events which
-are almost always of interest (scheduling, interrupts, faults, system calls).
-Then, specialized facilities may exist for each subsystem (network, disks,
-USB, SCSI...).
-
-
-<H2>Bookmarks</H2>
-
-<P>
-Bookmarks are user supplied information added to a trace. They contain user
-annotations attached to a time interval.
-
-<PRE><TT>
-<bookmarks>
- <location name=name cpu=n start_time=t end_time=t>Some text</location>
- ...
-</bookmarks>
-</TT></PRE>
-
-<P>
-The interval is defined using either "time=" or "start_time=" and
-"end_time=", or "cycle=" or "start_cycle=" and "end_cycle=".
-The time is in seconds with decimals up to nanoseconds and cycle counts
-are unsigned integers with a 64 bits range. The cpu attribute is optional.
-
-</BODY>
-</HTML>
-
-
-
-
projects / lttv.git / blobdiff