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

   1 = babeltrace2-sink.text.details(7)
   2 :manpagetype: component class
   3 :revdate: 14 September 2019
   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-name, param:with-time, param:with-trace-name, and
  89 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=`yes` vtype:[optional boolean]::
 117     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 param:with-metadata=`no` vtype:[optional boolean]::
 127     Do not print metadata blocks.
 128
 129 param:with-stream-class-name=`no` vtype:[optional boolean]::
 130     Do not print stream class names.
 131
 132 param:with-stream-name=`no` vtype:[optional boolean]::
 133     Do not print stream names.
 134
 135 param:with-time=`no` vtype:[optional boolean]::
 136     Do not print timing information.
 137
 138 param:with-trace-name=`no` vtype:[optional boolean]::
 139     Do not print trace names.
 140
 141 param:with-uuid=`no` vtype:[optional boolean]::
 142     Do not print UUIDs.
 143
 144
 145 == PORTS
 146
 147 ----
 148 +-------------------+
 149 | sink.text.details |
 150 |                   |
 151 @ in                |
 152 +-------------------+
 153 ----
 154
 155
 156 === Input
 157
 158 `in`::
 159     Single input port.
 160
 161
 162 == ENVIRONMENT VARIABLES
 163
 164 include::common-common-env.txt[]
 165
 166
 167 include::common-footer.txt[]
 168
 169
 170 == SEE ALSO
 171
 172 man:babeltrace2-intro(7),
 173 man:babeltrace2-plugin-text(7)