| 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) |