doc/man/babeltrace2-sink.text.details.7.txt

   1 = babeltrace2-sink.text.details(7)
   2 :manpagetype: component class
   3 :revdate: 1 September 2023
   4
   5
   6 == NAME
   7
   8 babeltrace2-sink.text.details - Babeltrace 2's detailed plain text sink
   9 component class
  10
  11
  12 == DESCRIPTION
  13
  14 A Babeltrace~2 compcls:sink.text.details component
  15 deterministically prints the messages it consumes, with all the possible
  16 details, to the standard output.
  17
  18 ----
  19             +-------------------+
  20             | sink.text.details |
  21             |                   +--> Detailed messages to the
  22 Messages -->@ in                |    standard output
  23             +-------------------+
  24 ----
  25
  26 include::common-see-babeltrace2-intro.txt[]
  27
  28 The purpose of a compcls:sink.text.details component is to always print
  29 the same text for the same sequence of consumed messages, whatever the
  30 build configuration of the Babeltrace~2 project. This can be
  31 helpful for testing, debugging, and support.
  32
  33 The output format is optimized for human reading, with colors when the
  34 terminal supports it. You can control how the component prints color
  35 codes with the param:color parameter.
  36
  37 To achieve a reproducible output, a compcls:sink.text.details component
  38 sorts the members of all unordered sets before it prints them. For
  39 example, the component sorts enumeration field class mappings by label
  40 and, for each mapping, sorts the contained ranges.
  41
  42 In normal mode, each message has at least three lines, the three first
  43 being:
  44
  45 . Timing information (cycles and nanoseconds since origin).
  46 +
  47 Example:
  48 +
  49 ----
  50 [102,423,274,041,829 cycles, 1,441,852,841,550,867,846 ns from origin]
  51 ----
  52
  53 . Unique stream identifier.
  54 +
  55 To be able to follow a specific trace object (the name and UUID
  56 properties of a trace object are optional), the component assigns a
  57 unique numeric ID to the trace object when it first encounters it in a
  58 stream beginning message.
  59 +
  60 Example:
  61 +
  62 ----
  63 {Trace 1, Stream class ID 0, Stream ID 2}
  64 ----
  65
  66 . Message type and basic information.
  67 +
  68 Examples:
  69 +
  70 ----
  71 Packet beginning:
  72 ----
  73 +
  74 ----
  75 Event `lttng_ust_statedump:build_id` (Class ID 2):
  76 ----
  77
  78 What follows depend on the specific message type. The component prints
  79 all the available properties and fields in a human-readable, structured
  80 format.
  81
  82 When a compcls:sink.text.details component consumes a stream beginning
  83 or an event message, it can print a metadata block for all the metadata
  84 objects which it did not print yet. You can use the param:with-metadata
  85 parameter to disable this.
  86
  87 You can hide specific properties with the param:with-stream-class-name,
  88 param:with-stream-class-namespace, param:with-stream-name,
  89 param:with-time, param:with-trace-name, and param:with-uuid parameters.
  90
  91 To make the component hide many message details and print a single
  92 message per line, you can enable the compact mode with the param:compact
  93 parameter.
  94
  95
  96 == INITIALIZATION PARAMETERS
  97
  98 param:color=(`never` | `auto` | `always`) vtype:[optional string]::
  99     Force the terminal color support, one of:
 100 +
 101 --
 102 `auto` (default)::
 103     Only emit terminal color codes when the standard output and error
 104     streams are connected to a color-capable terminal.
 105
 106 `never`::
 107     Never emit terminal color codes.
 108
 109 `always`::
 110     Always emit terminal color codes.
 111 --
 112 +
 113 The `BABELTRACE_TERM_COLOR` environment variable overrides this
 114 parameter.
 115
 116 param:compact='VAL' vtype:[optional boolean]::
 117     If 'VAL' is true, then enable compact mode.
 118 +
 119 In compact mode, the component prints one line per message, omitting
 120 many details about messages. This is useful if you only need the time,
 121 type, and very basic information of messages.
 122 +
 123 In compact mode, the component still prints the full metadata blocks.
 124 You can remove such blocks with the param:with-metadata parameter.
 125 +
 126 Default: false.
 127
 128 param:with-metadata='VAL' vtype:[optional boolean]::
 129     If 'VAL' is false, then do not print metadata blocks.
 130 +
 131 Default: true.
 132
 133 param:with-stream-class-name='VAL' vtype:[optional boolean]::
 134     If 'VAL' is false, then do not print stream class names.
 135 +
 136 Default: true.
 137
 138 param:with-stream-class-namespace='VAL' vtype:[optional boolean]::
 139     If 'VAL' is false, then do not print stream class namespaces.
 140 +
 141 Default: true.
 142
 143 param:with-stream-name='VAL' vtype:[optional boolean]::
 144     If 'VAL' is false, then do not print stream names.
 145 +
 146 Default: true.
 147
 148 param:with-time='VAL' vtype:[optional boolean]::
 149     If 'VAL' is false, then do not print timing information.
 150 +
 151 Default: true.
 152
 153 param:with-trace-name='VAL' vtype:[optional boolean]::
 154     If 'VAL' is false, then do not print trace names.
 155 +
 156 Default: true.
 157
 158 param:with-uuid='VAL' vtype:[optional boolean]::
 159     If 'VAL' is false, then do not print UUIDs.
 160 +
 161 Default: true.
 162
 163
 164 == PORTS
 165
 166 ----
 167 +-------------------+
 168 | sink.text.details |
 169 |                   |
 170 @ in                |
 171 +-------------------+
 172 ----
 173
 174
 175 === Input
 176
 177 `in`::
 178     Single input port.
 179
 180
 181 == ENVIRONMENT VARIABLES
 182
 183 include::common-common-env.txt[]
 184
 185
 186 include::common-footer.txt[]
 187
 188
 189 == SEE ALSO
 190
 191 man:babeltrace2-intro(7),
 192 man:babeltrace2-plugin-text(7)