| 1 | = babeltrace2-source.ctf.fs(7) |
| 2 | :manpagetype: component class |
| 3 | :revdate: 14 September 2019 |
| 4 | |
| 5 | |
| 6 | == NAME |
| 7 | |
| 8 | babeltrace2-source.ctf.fs - Babeltrace 2's file system CTF source |
| 9 | component class |
| 10 | |
| 11 | |
| 12 | == DESCRIPTION |
| 13 | |
| 14 | A Babeltrace~2 compcls:source.ctf.fs message iterator reads one or |
| 15 | more https://diamon.org/ctf/[CTF]~1.8 streams on the file system |
| 16 | and emits corresponding messages. |
| 17 | |
| 18 | ---- |
| 19 | CTF streams on |
| 20 | the file system |
| 21 | | |
| 22 | | +---------------------+ |
| 23 | | | src.ctf.fs | |
| 24 | | | | |
| 25 | '-->| ...5c847 | 0 | 0 @--> Stream 0 messages |
| 26 | | ...5c847 | 0 | 1 @--> Stream 1 messages |
| 27 | | ...5c847 | 0 | 2 @--> Stream 2 messages |
| 28 | +---------------------+ |
| 29 | ---- |
| 30 | |
| 31 | include::common-see-babeltrace2-intro.txt[] |
| 32 | |
| 33 | |
| 34 | [[input]] |
| 35 | === Input |
| 36 | |
| 37 | A compcls:source.ctf.fs component opens a single _logical_ CTF trace. A |
| 38 | logical CTF trace contains one or more _physical_ CTF traces. A physical |
| 39 | CTF trace on the file system is a directory which contains: |
| 40 | |
| 41 | * One metadata stream file named `metadata`. |
| 42 | * One or more data stream files, that is, any file with a name that does |
| 43 | not start with `.` and which is not `metadata`. |
| 44 | * **Optional**: One https://lttng.org/[LTTng] index directory named |
| 45 | `index`. |
| 46 | |
| 47 | If the logical CTF trace to handle contains more than one physical CTF |
| 48 | trace, then all the physical CTF traces must have a trace UUID and all |
| 49 | UUIDs must be the same. Opening more than one physical CTF trace to |
| 50 | constitute a single logical CTF trace is needed to support LTTng's |
| 51 | tracing session rotation feature, for example (see man:lttng-rotate(1) |
| 52 | starting from LTTng~2.11). |
| 53 | |
| 54 | You specify which physical CTF traces to open and read with the |
| 55 | param:inputs array parameter. Each entry in this array is the path to a |
| 56 | physical CTF trace directory, that is, the directory directly containing |
| 57 | the stream files. |
| 58 | |
| 59 | A compcls:source.ctf.fs component does not recurse into directories to |
| 60 | find CTF traces. However, the component class provides the |
| 61 | `babeltrace.support-info` query object which indicates whether or not a |
| 62 | given directory looks like a CTF trace directory (see |
| 63 | <<support-info,```babeltrace.support-info`''>>). |
| 64 | |
| 65 | The component creates one output port for each logical CTF data stream. |
| 66 | More than one physical CTF data stream file can support a single logical |
| 67 | CTF data stream (LTTng's trace file rotation and tracing session |
| 68 | rotation can cause this). |
| 69 | |
| 70 | If two or more data stream files contain the same packets, a |
| 71 | compcls:source.ctf.fs message iterator reads each of them only once so |
| 72 | that it never emits duplicated messages. This feature makes it possible, |
| 73 | for example, to open overlapping |
| 74 | https://lttng.org/docs/#doc-taking-a-snapshot[LTTng snapshots] with a |
| 75 | single compcls:source.ctf.fs component and silently discard the |
| 76 | duplicated packets. |
| 77 | |
| 78 | |
| 79 | === Trace quirks |
| 80 | |
| 81 | Many tracers produce CTF traces. A compcls:source.ctf.fs component makes |
| 82 | some effort to support as many CTF traces as possible, even those with |
| 83 | malformed streams. |
| 84 | |
| 85 | Generally: |
| 86 | |
| 87 | * If the `timestamp_begin` or `timestamp_end` packet context field class |
| 88 | exists, but it is not mapped to a clock class, and there's only one |
| 89 | clock class at this point in the metadata stream, the component maps |
| 90 | the field class to this unique clock class. |
| 91 | |
| 92 | A compcls:source.ctf.fs component has special quirk handling for some |
| 93 | https://lttng.org/[LTTng] and https://lttng.org/[barectf] traces, |
| 94 | depending on the tracer's version: |
| 95 | |
| 96 | All LTTng versions:: |
| 97 | + |
| 98 | -- |
| 99 | * The component sets the `monotonic` clock class's origin to the Unix |
| 100 | epoch so that different LTTng traces are always correlatable. |
| 101 | + |
| 102 | This is the equivalent of setting the |
| 103 | param:force-clock-class-origin-unix-epoch parameter to true. |
| 104 | |
| 105 | * For a given data stream, for all the contiguous last packets of which |
| 106 | the `timestamp_end` context field is 0, the message iterator uses the |
| 107 | packet's last event record's time as the packet end message's time. |
| 108 | + |
| 109 | This is useful for the traces which man:lttng-crash(1) generates. |
| 110 | -- |
| 111 | |
| 112 | LTTng-UST up to, but excluding, 2.11.0:: |
| 113 | LTTng-modules up to, but excluding, 2.9.13:: |
| 114 | LTTng-modules from 2.10.0 to 2.10.9:: |
| 115 | + |
| 116 | -- |
| 117 | * For a given packet, the message iterator uses the packet's last |
| 118 | event record's time as the packet end message's time, ignoring the |
| 119 | packet context's `timestamp_end` field. |
| 120 | -- |
| 121 | |
| 122 | barectf up to, but excluding, 2.3.1:: |
| 123 | + |
| 124 | -- |
| 125 | * For a given packet, the message iterator uses the packet's first event |
| 126 | record's time as the packet beginning message's time, ignoring the |
| 127 | packet context's `timestamp_begin` field. |
| 128 | -- |
| 129 | |
| 130 | |
| 131 | == INITIALIZATION PARAMETERS |
| 132 | |
| 133 | param:clock-class-offset-ns='NS' vtype:[optional signed integer]:: |
| 134 | Add 'NS' nanoseconds to the offset of all the clock classes that the |
| 135 | component creates. |
| 136 | + |
| 137 | You can combine this parameter with the param:clock-class-offset-s |
| 138 | parameter. |
| 139 | |
| 140 | param:clock-class-offset-s='SEC' vtype:[optional signed integer]:: |
| 141 | Add 'SEC' seconds to the offset of all the clock classes that the |
| 142 | component creates. |
| 143 | + |
| 144 | You can combine this parameter with the param:clock-class-offset-ns |
| 145 | parameter. |
| 146 | |
| 147 | param:force-clock-class-origin-unix-epoch=`yes` vtype:[optional boolean]:: |
| 148 | Force the origin of all clock classes that the component creates to |
| 149 | have a Unix epoch origin, whatever the detected tracer. |
| 150 | |
| 151 | param:inputs='DIRS' vtype:[array of strings]:: |
| 152 | Open and read the physical CTF traces located in 'DIRS'. |
| 153 | + |
| 154 | Each element of 'DIRS' is the path to a physical CTF trace directory |
| 155 | containing the trace's stream files. |
| 156 | + |
| 157 | All the specified physical CTF traces must belong to the same logical |
| 158 | CTF trace. See <<input,``Input''>> to learn more about logical and |
| 159 | physical CTF traces. |
| 160 | |
| 161 | param:trace-name='NAME' vtype:[optional string]:: |
| 162 | Set the name of the trace object that the component creates to |
| 163 | 'NAME'. |
| 164 | |
| 165 | |
| 166 | == PORTS |
| 167 | |
| 168 | ---- |
| 169 | +--------------------+ |
| 170 | | src.ctf.fs | |
| 171 | | | |
| 172 | | ...5c847 | 0 | 1 @ |
| 173 | | ... @ |
| 174 | +--------------------+ |
| 175 | ---- |
| 176 | |
| 177 | |
| 178 | === Output |
| 179 | |
| 180 | A compcls:source.ctf.fs component creates one output port for each |
| 181 | logical CTF data stream. See <<input,``Input''>> to learn more about |
| 182 | logical and physical CTF data streams. |
| 183 | |
| 184 | Each output port's name has one of the following forms: |
| 185 | |
| 186 | [verse] |
| 187 | __TRACE-ID__ | __STREAM-CLASS-ID__ | __STREAM-ID__ |
| 188 | __TRACE-ID__ | __STREAM-ID__ |
| 189 | |
| 190 | The component uses the second form when the stream class ID is not |
| 191 | available. |
| 192 | |
| 193 | __TRACE-ID__:: |
| 194 | Trace's UUID if available, otherwise trace's absolute directory |
| 195 | path. |
| 196 | |
| 197 | __STREAM-CLASS-ID__:: |
| 198 | Stream class ID. |
| 199 | |
| 200 | __STREAM-ID__:: |
| 201 | Stream ID if available, otherwise stream's absolute file path. |
| 202 | |
| 203 | |
| 204 | [[query-objs]] |
| 205 | == QUERY OBJECTS |
| 206 | |
| 207 | [[support-info]] |
| 208 | === `babeltrace.support-info` |
| 209 | |
| 210 | See man:babeltrace2-query-babeltrace.support-info(7) to learn more |
| 211 | about this query object. |
| 212 | |
| 213 | For a directory input which is the path to a CTF trace directory, |
| 214 | the result object contains: |
| 215 | |
| 216 | nlqres:weight:: |
| 217 | 0.75 |
| 218 | |
| 219 | nlqres:group:: |
| 220 | Trace's UUID if available, otherwise the entry does not exist. |
| 221 | |
| 222 | You can leverage this query object's nlqres:group entry to assemble many |
| 223 | physical CTF traces as a single logical CTF trace (see |
| 224 | <<input,``Input''>> to learn more about logical and physical CTF |
| 225 | traces). This is how the man:babeltrace2-convert(1) command makes it |
| 226 | possible to specify as non-option arguments the paths to multiple |
| 227 | physical CTF traces which belong to the same logical CTF trace and |
| 228 | create a single compcls:source.ctf.fs component. |
| 229 | |
| 230 | |
| 231 | === `babeltrace.trace-infos` |
| 232 | |
| 233 | See man:babeltrace2-query-babeltrace.trace-infos(7) to learn more |
| 234 | about this query object. |
| 235 | |
| 236 | |
| 237 | === `metadata-info` |
| 238 | |
| 239 | You can query the `metadata-info` object for a specific CTF trace to get |
| 240 | its plain text metadata stream as well as whether or not it is |
| 241 | packetized. |
| 242 | |
| 243 | Parameters: |
| 244 | |
| 245 | nlparam:path='PATH' vtype:[string]:: |
| 246 | Path to the physical CTF trace directory which contains the |
| 247 | `metadata` file. |
| 248 | |
| 249 | Result object (map): |
| 250 | |
| 251 | qres:is-packetized vtype:[boolean]:: |
| 252 | True if the metadata stream file is packetized. |
| 253 | |
| 254 | qres:text vtype:[string]:: |
| 255 | Plain text metadata stream. |
| 256 | |
| 257 | |
| 258 | include::common-footer.txt[] |
| 259 | |
| 260 | |
| 261 | == SEE ALSO |
| 262 | |
| 263 | man:babeltrace2-intro(7), |
| 264 | man:babeltrace2-plugin-ctf(7), |
| 265 | man:lttng-crash(1) |