Debian Codegraph @

docs/modules/how-barectf-works/pages/ctf-primer.adoc

raw
1 = CTF primer
2
3 The https://diamon.org/ctf/[_**Common Trace Format**_] (CTF) is a binary
4 https://en.wikipedia.org/wiki/Tracing_(software)[trace] format which is
5 designed to be very fast to write while offering many field types to
6 represent data.
7
8 A barectf configuration can use the following CTF field types:
9
10 * Unsigned/signed xref:yaml:int-ft-obj.adoc[integer] (1 to 64 bits).
11 * Unsigned/signed xref:yaml:enum-ft-obj.adoc[enumeration] (1 to
12 64 bits).
13 * xref:yaml:real-ft-obj.adoc[Real] (single or double precision).
14 * Null-terminated xref:yaml:str-ft-obj.adoc[string].
15 * xref:yaml:struct-ft-obj.adoc[Structure] (zero or more named members).
16 * xref:yaml:static-array-ft-obj.adoc[Static array] of any field type
17 except structure and dynamic array.
18 * xref:yaml:dyn-array-ft-obj.adoc[Dynamic array] of any field type
19 except structure and dynamic array.
20
21 CTF makes it possible to describe the alignment and byte order of
22 integer, enumeration, and real fields.
23
24 A system which produces CTF streams is known as a _CTF producer_.
25
26 A system which consumes CTF streams is known as a _CTF consumer_.
27
28 [[trace]]
29 == CTF trace structure
30
31 A _**CTF trace**_ is exactly one metadata stream and one or more
32 <<ds,data streams>>:
33
34 [.width-50]
35 image::ctf-trace.svg[]
36
37 The metadata stream describes the trace's data streams with TSDL
38 (Trace Stream Description Language). On the file system, its file name
39 must be `metadata`.
40
41 The metadata stream describes things such as:
42
43 * The xref:yaml:clk-type-obj.adoc[type] of the data stream default clocks.
44 * The names of xref:yaml:ert-obj.adoc[event record types].
45 * The types of event record fields.
46 * The xref:yaml:trace-obj.adoc[trace]'s environment variables.
47
48 [[ds]]
49 === Data stream
50
51 A _**CTF data stream**_ is a sequence of one or more data
52 <<pkt,packets>>:
53
54 [.width-100]
55 image::ctf-trace-all.svg[]
56
57 A xref:yaml:dst-obj.adoc[data stream type] describes data streams.
58
59 A packet contains one or more bytes of data.
60
61 Although a packet can contain padding itself, from the data stream's
62 point of view, there's no padding between packets.
63
64 A data stream can have, conceptually:
65
66 [[def-clk]]A default clock::
67 Described by a xref:yaml:clk-type-obj.adoc[clock type] in the trace's
68 metadata stream.
69 +
70 <<pkt,Packets>> and event records can contain snapshots, named
71 _timestamps_, of their data stream's clock.
72
73 [[disc-er-counter]]A counter of discarded event records::
74 Indicates the number of event records which the generated tracer
75 needed to discard for different reasons.
76 +
77 For example, the tracer discards an event record when it doesn't fit the
78 current packet and the back end is full (see
79 xref:platform:index.adoc[]).
80 +
81 A <<pkt,packet>> can contain a snapshot of this counter.
82
83 On the file system, a data stream file:
84
85 * Can have any name, except `metadata` and anything which begins with
86 `.`.
87
88 * Must be in the same directory as the `metadata` file.
89
90 [[pkt]]
91 === Packet
92
93 A _**CTF packet**_ is a part of a <<ds,data stream>>.
94
95 A packet contains, in this order:
96
97 . [.opt]##Optional##A header structure field, which contains:
98 +
99 ** [.opt]##Optional##The CTF magic number.
100 +
101 See the trace type features object's
102 xref:yaml:trace-type-obj.adoc#magic-ft-prop[`magic-field-type`
103 property].
104
105 ** [.opt]##Optional##A trace type
106 https://en.wikipedia.org/wiki/Universally_unique_identifier[UUID].
107 +
108 See the trace type object's
109 xref:yaml:trace-type-obj.adoc#uuid-prop[`uuid` property] and the
110 trace type features object's
111 xref:yaml:trace-type-obj.adoc#uuid-ft-prop[`uuid-field-type`
112 property].
113
114 ** [.opt]##Optional##The numeric ID of the data stream type which, in the
115 metadata stream, describes this packet's data stream.
116 +
117 See the trace type features object's
118 xref:yaml:trace-type-obj.adoc#dst-id-ft-prop[`data-stream-type-id-field-type`
119 property].
120
121 ** [.opt]##Optional##The numeric ID of this packet's data stream.
122
123 . A context structure field, which contains:
124 +
125 ** The packet's total size, in bits (always a multiple of{nbsp}8).
126 +
127 See the data stream type packet features object's
128 xref:yaml:dst-obj.adoc#total-size-ft-prop[`total-size-field-type`
129 property].
130
131 ** The packet's content size, in bits.
132 +
133 See the data stream type packet features object's
134 xref:yaml:dst-obj.adoc#content-size-ft-prop[`content-size-field-type`
135 property].
136
137 ** [.opt]##Optional##The packet's beginning timestamp.
138 +
139 See the data stream type packet features object's
140 xref:yaml:dst-obj.adoc#beginning-ts-ft-prop[`beginning-timestamp-field-type`
141 property].
142
143 ** [.opt]##Optional##The packet's end timestamp.
144 +
145 See the data stream type packet features object's
146 xref:yaml:dst-obj.adoc#end-ts-ft-prop[`end-timestamp-field-type`
147 property].
148
149 ** [.opt]##Optional##A discarded event record counter snapshot.
150 +
151 See the data stream type packet features object's
152 xref:yaml:dst-obj.adoc#disc-er-counter-snapshot-ft-prop[`discarded-event-records-counter-snapshot-field-type`
153 property].
154
155 ** [.opt]##Optional##A packet sequence number (within its <<ds,data
156 stream>>).
157 +
158 See the data stream type packet features object's
159 xref:yaml:dst-obj.adoc#seq-num-ft-prop[`sequence-number-field-type`
160 property].
161
162 ** [.opt]##Optional##User fields.
163 +
164 See the data stream type object's
165 xref:yaml:dst-obj.adoc#pkt-ctx-ft-extra-members-prop[`packet-context-field-type-extra-members`
166 property].
167
168 . Zero or more <<er,event records>>.
169
170 A packet contains one or more bytes of data.
171
172 A packet can have padding (garbage data) after its last event record if
173 its total size is different from its content size.
174
175 [[er]]
176 === Event record
177
178 A _**CTF event record**_ is the result of a tracer writing a
179 time-stamped record with user data when an event occurs during a user
180 application's execution.
181
182 An xref:yaml:ert-obj.adoc[event record type] describes event records.
183
184 An event record contains, in this order:
185
186 . [.opt]##Optional##A header structure field, which contains:
187 +
188 ** [.opt]##Optional##The numeric ID of the event record type which, in the
189 metadata stream, describes this event record.
190 +
191 See the data stream type event record features object's
192 xref:yaml:dst-obj.adoc#type-id-ft-prop[`type-id-field-type` property].
193
194 ** [.opt]##Optional##A timestamp.
195 +
196 See the data stream type event record features object's
197 xref:yaml:dst-obj.adoc#ts-prop[`timestamp-field-type` property].
198
199 . [.opt]##Optional##A common context structure field, which contains
200 user fields.
201 +
202 See the data stream type object's
203 xref:yaml:dst-obj.adoc#er-common-ctx-ft-prop[`event-record-common-context-field-type`
204 property].
205
206 . [.opt]##Optional##A specific context structure field, which contains user
207 fields.
208 +
209 See the event record type object's
210 xref:yaml:ert-obj.adoc#spec-ctx-ft-prop[`specific-context-field-type`
211 property].
212
213 . [.opt]##Optional##A payload structure field, which contains user
214 fields.
215 +
216 See the event record type object's
217 xref:yaml:ert-obj.adoc#payload-ft-prop[`payload-field-type` property].