doc/man/babeltrace2-sink.ctf.fs.7.txt

   1 = babeltrace2-sink.ctf.fs(7)
   2 :manpagetype: component class
   3 :revdate: 14 September 2019
   4
   5
   6 == NAME
   7
   8 babeltrace2-sink.ctf.fs - Babeltrace 2's file system CTF sink component
   9 class
  10
  11
  12 == DESCRIPTION
  13
  14 A Babeltrace~2 compcls:sink.ctf.fs component writes the messages it
  15 consumes to one or more https://diamon.org/ctf/[CTF]~1.8 traces on
  16 the file system.
  17
  18 ----
  19             +-------------+
  20             | sink.ctf.fs |
  21             |             +--> CTF trace(s) on
  22 Messages -->@ in          |    the file system
  23             +-------------+
  24 ----
  25
  26 include::common-see-babeltrace2-intro.txt[]
  27
  28 A compcls:sink.ctf.fs component does not merge traces: it writes the
  29 messages of different input traces to different output traces.
  30
  31
  32 === Special trace IR to CTF translations
  33
  34 A compcls:sink.ctf.fs component makes a best effort to write CTF traces
  35 that are semantically equivalent to the input traces. As of this
  36 version, the component writes CTF~1.8 traces, so the following
  37 field class translations can occur:
  38
  39 * The component translates a boolean field class to a CTF unsigned 8-bit
  40   integer field class.
  41 +
  42 The unsigned integer field's value is 0 when the boolean field's value
  43 is false and 1 when the boolean field's value is true.
  44
  45 * The component translates a bit array field to a CTF unsigned
  46   integer field class having the same length.
  47
  48 * The component translates an option field class to a CTF variant
  49   field class where the options are an empty structure field class
  50   and the optional field class itself.
  51 +
  52 The empty structure field is selected when the option field has no
  53 field.
  54
  55 In all the cases above, the component adds a comment in the metadata
  56 stream, above the field class, to indicate that a special translation
  57 occured.
  58
  59
  60 === Input message constraints
  61
  62 Because of limitations in CTF~1.8 regarding how discarded events
  63 and packets are encoded:
  64
  65 * If a stream class supports discarded events and the
  66   param:ignore-discarded-events parameter is :not: true:
  67
  68 ** The stream class must support packets.
  69 ** Discarded events messages must have times.
  70 ** Any discarded events message must occur between a packet end
  71    and a packet beginning message.
  72 ** The beginning time of a discarded events message must be the same
  73    as the time of the last packet end message.
  74 ** The end time of a discarded events message must be the same
  75    as the time of the next packet end message.
  76 ** Time ranges of discarded events messages must not overlap.
  77
  78 * If a stream class supports discarded packets and the
  79   param:ignore-discarded-packets parameter is :not: true:
  80
  81 ** The stream class must support packets.
  82 ** Discarded packets messages must have times.
  83 ** The beginning time of a discarded events message must be the same
  84    as the time of the last packet end message.
  85 ** The end time of a discarded events message must be the same
  86    as the time of the next packet beginning message.
  87 ** Time ranges of discarded packets messages must not overlap.
  88
  89 The messages which a compcls:source.ctf.fs component creates satisfy all
  90 the requirements above.
  91
  92 If a discarded events or packets message has no events/packets count,
  93 the compcls:sink.ctf.fs component adds 1 to the corresponding CTF
  94 stream's counter.
  95
  96
  97 === Alignment and byte order
  98
  99 A compcls:sink.ctf.fs component always aligns data fields as such:
 100
 101 Integer fields with a size which is not a multiple of 8::
 102     1-bit.
 103
 104 All other scalar fields (integer, enumeration, real, string)::
 105     8-bit.
 106
 107 The component writes fields using the machine's native byte order. As of
 108 this version, there's no way to force a custom byte order.
 109
 110
 111 [[output-path]]
 112 === Output path
 113
 114 The path of a CTF trace is the directory which directly contains the
 115 metadata and data stream files.
 116
 117 The current strategy to build a path in which to write the streams of
 118 a given input trace is, in this order:
 119
 120 . If the param:assume-single-trace parameter is true, then the output
 121   trace path to use for the single input trace is the directory
 122   specified by the param:path parameter.
 123
 124 . If the component recognizes the input trace as an LTTng (2.11 or
 125   greater) trace, then it checks specific trace environment values to
 126   build a trace path relative to the directory specified by the
 127   param:path parameter:
 128 +
 129 --
 130
 131 Linux kernel domain::
 132 +
 133 [verse]
 134 __HOST__/__SNAME__-__STIME__/kernel
 135
 136 User space domain, per-UID buffering::
 137 +
 138 [verse]
 139 __HOST__/__SNAME__-__STIME__/ust/uid/__UID__/__ARCHW__-bit
 140
 141 User space domain, per-PID buffering::
 142 +
 143 [verse]
 144 __HOST__/__SNAME__-__STIME__/ust/pid/__PNAME__-__PID__-__PTIME__
 145
 146 --
 147 +
 148 With:
 149 +
 150 --
 151 __HOST__::
 152     Target's hostname.
 153
 154 __SNAME__::
 155     Tracing session name.
 156
 157 __STIME__::
 158     Tracing session creation date/time.
 159
 160 __UID__::
 161     User ID.
 162
 163 __ARCHW__::
 164     Architecture's width (`32` or `64`).
 165
 166 __PNAME__::
 167     Process name.
 168
 169 __PID__::
 170     Process ID.
 171
 172 __PTIME__::
 173     Process's date/time.
 174 --
 175
 176 . If the input trace has a name, then the component sanitizes this name
 177   and uses it as a relative path to the directory specified by the
 178   param:path parameter.
 179 +
 180 The trace name sanitization operation:
 181 +
 182 * Replaces `.` subdirectories with `_`.
 183 * Replaces `..` subdirectories with `__`.
 184 * Removes any trailing `/` character.
 185
 186 . The component uses the subdirectory `trace` relative to the directory
 187   specified by the param:path parameter.
 188
 189 In all the cases above, if the effective output trace path already
 190 exists on the file system, the component appends a numeric suffix to the
 191 name of the last subdirectory. The suffix starts at 0 and increments
 192 until the path does not exist.
 193
 194
 195 == INITIALIZATION PARAMETERS
 196
 197 param:assume-single-trace=`yes` vtype:[optional boolean]::
 198     Assume that the component only receives messages related to a single
 199     input trace.
 200 +
 201 This parameter affects how the component builds the output trace path
 202 (see <<output-path,``Output path''>>).
 203
 204 param:ignore-discarded-events=`yes` vtype:[optional boolean]::
 205     Ignore discarded events messages.
 206
 207 param:ignore-discarded-packets=`yes` vtype:[optional boolean]::
 208     Ignore discarded packets messages.
 209
 210 param:path='PATH' vtype:[string]::
 211     Base output path.
 212 +
 213 See <<output-path,``Output path''>> to learn how the component uses this
 214 parameter to build the output path for a given input trace.
 215
 216 param:quiet=`yes` vtype:[optional boolean]::
 217     Do not write anything to the standard output.
 218
 219
 220 == PORTS
 221
 222 ----
 223 +-------------+
 224 | sink.ctf.fs |
 225 |             |
 226 @ in          |
 227 +-------------+
 228 ----
 229
 230
 231 === Input
 232
 233 `in`::
 234     Single input port.
 235
 236
 237 include::common-footer.txt[]
 238
 239
 240 == SEE ALSO
 241
 242 man:babeltrace2-intro(7),
 243 man:babeltrace2-plugin-ctf(7)