doc/man: make default values of boolean init. params. clearer

[babeltrace.git] / doc / man / babeltrace2-sink.ctf.fs.7.txt

= babeltrace2-sink.ctf.fs(7)
:manpagetype: component class
:revdate: 1 September 2023


== NAME

babeltrace2-sink.ctf.fs - Babeltrace 2's file system CTF sink component
class


== DESCRIPTION

A Babeltrace~2 compcls:sink.ctf.fs component writes the messages it
consumes to one or more https://diamon.org/ctf/[CTF]~1.8 traces on
the file system.

----
            +-------------+
            | sink.ctf.fs |
            |             +--> CTF trace(s) on
Messages -->@ in          |    the file system
            +-------------+
----

include::common-see-babeltrace2-intro.txt[]

A compcls:sink.ctf.fs component does not merge traces: it writes the
messages of different input traces to different output traces.


=== Special trace IR to CTF translations

A compcls:sink.ctf.fs component makes a best effort to write CTF traces
that are semantically equivalent to the input traces. As of this
version, the component writes CTF~1.8 traces, so the following
field class translations can occur:

* The component translates a boolean field class to a CTF unsigned 8-bit
  integer field class.
+
The unsigned integer field's value is 0 when the boolean field's value
is false and 1 when the boolean field's value is true.

* The component translates a bit array field to a CTF unsigned
  integer field class having the same length.

* The component translates an option field class to a CTF variant
  field class where the options are an empty structure field class
  and the optional field class itself.
+
The empty structure field is selected when the option field has no
field.

In all the cases above, the component adds a comment in the metadata
stream, above the field class, to indicate that a special translation
occurred.


=== Input message constraints

Because of limitations in CTF~1.8 regarding how discarded events
and packets are encoded:

* If a stream class supports discarded events and the
  param:ignore-discarded-events parameter is :not: true:

** The stream class must support packets.
** Discarded events messages must have times.
** Any discarded events message must occur between a packet end
   and a packet beginning message.
** The beginning time of a discarded events message must be the same
   as the time of the last packet end message.
** The end time of a discarded events message must be the same
   as the time of the next packet end message.
** Time ranges of discarded events messages must not overlap.

* If a stream class supports discarded packets and the
  param:ignore-discarded-packets parameter is :not: true:

** The stream class must support packets.
** Discarded packets messages must have times.
** The beginning time of a discarded events message must be the same
   as the time of the last packet end message.
** The end time of a discarded events message must be the same
   as the time of the next packet beginning message.
** Time ranges of discarded packets messages must not overlap.

The messages which a compcls:source.ctf.fs component creates satisfy all
the requirements above.

If a discarded events or packets message has no events/packets count,
the compcls:sink.ctf.fs component adds 1 to the corresponding CTF
stream's counter.


=== Alignment and byte order

A compcls:sink.ctf.fs component always aligns data fields as such:

Integer fields with a size which is not a multiple of 8::
    1-bit.

All other scalar fields (integer, enumeration, real, string)::
    8-bit.

The component writes fields using the machine's native byte order. As of
this version, there's no way to force a custom byte order.


[[output-path]]
=== Output path

The path of a CTF trace is the directory which directly contains the
metadata and data stream files.

The current strategy to build a path in which to write the streams of
a given input trace is, in this order:

. If the param:assume-single-trace parameter is true, then the output
  trace path to use for the single input trace is the directory
  specified by the param:path parameter.

. If the component recognizes the input trace as an LTTng (2.11 or
  greater) trace, then it checks specific trace environment values to
  build a trace path relative to the directory specified by the
  param:path parameter:
+
--

Linux kernel domain::
+
[verse]
__HOST__/__SNAME__-__STIME__/kernel

User space domain, per-UID buffering::
+
[verse]
__HOST__/__SNAME__-__STIME__/ust/uid/__UID__/__ARCHW__-bit

User space domain, per-PID buffering::
+
[verse]
__HOST__/__SNAME__-__STIME__/ust/pid/__PNAME__-__PID__-__PTIME__

--
+
With:
+
--
__HOST__::
    Target's hostname.

__SNAME__::
    Tracing session name.

__STIME__::
    Tracing session creation date/time.

__UID__::
    User ID.

__ARCHW__::
    Architecture's width (`32` or `64`).

__PNAME__::
    Process name.

__PID__::
    Process ID.

__PTIME__::
    Process's date/time.
--

. If the input trace has a name, then the component sanitizes this name
  and uses it as a relative path to the directory specified by the
  param:path parameter.
+
The trace name sanitization operation:
+
* Replaces `.` subdirectories with `_`.
* Replaces `..` subdirectories with `__`.
* Removes any trailing `/` character.

. The component uses the subdirectory `trace` relative to the directory
  specified by the param:path parameter.

In all the cases above, if the effective output trace path already
exists on the file system, the component appends a numeric suffix to the
name of the last subdirectory. The suffix starts at 0 and increments
until the path does not exist.


== INITIALIZATION PARAMETERS

param:assume-single-trace='VAL' vtype:[optional boolean]::
    If 'VAL' is true, then assume that the component only receives
    messages related to a single input trace.
+
This parameter affects how the component builds the output trace path
(see <<output-path,``Output path''>>).
+
Default: false.

param:ignore-discarded-events='VAL' vtype:[optional boolean]::
    If 'VAL' is true, then ignore discarded events messages.
+
Default: false.

param:ignore-discarded-packets='VAL' vtype:[optional boolean]::
    If 'VAL' is true, then ignore discarded packets messages.
+
Default: false.

param:path='PATH' vtype:[string]::
    Base output path.
+
See <<output-path,``Output path''>> to learn how the component uses this
parameter to build the output path for a given input trace.

param:quiet='VAL' vtype:[optional boolean]::
    If 'VAL' is true, then do not write anything to the standard output.
+
Default: false.


== PORTS

----
+-------------+
| sink.ctf.fs |
|             |
@ in          |
+-------------+
----


=== Input

`in`::
    Single input port.


include::common-footer.txt[]


== SEE ALSO

man:babeltrace2-intro(7),
man:babeltrace2-plugin-ctf(7)