Commit | Line | Data |
---|---|---|
e70712b3 PP |
1 | = babeltrace2-sink.text.details(7) |
2 | :manpagetype: component class | |
6f6e5e61 | 3 | :revdate: 1 September 2023 |
e70712b3 PP |
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 | ||
6f6e5e61 PP |
116 | param:compact='VAL' vtype:[optional boolean]:: |
117 | If 'VAL' is true, then enable compact mode. | |
e70712b3 PP |
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. | |
6f6e5e61 PP |
125 | + |
126 | Default: false. | |
e70712b3 | 127 | |
6f6e5e61 PP |
128 | param:with-metadata='VAL' vtype:[optional boolean]:: |
129 | If 'VAL' is false, then do not print metadata blocks. | |
130 | + | |
131 | Default: true. | |
e70712b3 | 132 | |
6f6e5e61 PP |
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. | |
e70712b3 | 137 | |
6f6e5e61 PP |
138 | param:with-stream-name='VAL' vtype:[optional boolean]:: |
139 | If 'VAL' is false, then do not print stream names. | |
140 | + | |
141 | Default: true. | |
e70712b3 | 142 | |
6f6e5e61 PP |
143 | param:with-time='VAL' vtype:[optional boolean]:: |
144 | If 'VAL' is false, then do not print timing information. | |
145 | + | |
146 | Default: true. | |
e70712b3 | 147 | |
6f6e5e61 PP |
148 | param:with-trace-name='VAL' vtype:[optional boolean]:: |
149 | If 'VAL' is false, then do not print trace names. | |
150 | + | |
151 | Default: true. | |
e70712b3 | 152 | |
6f6e5e61 PP |
153 | param:with-uuid='VAL' vtype:[optional boolean]:: |
154 | If 'VAL' is false, then do not print UUIDs. | |
155 | + | |
156 | Default: true. | |
e70712b3 PP |
157 | |
158 | ||
159 | == PORTS | |
160 | ||
161 | ---- | |
162 | +-------------------+ | |
163 | | sink.text.details | | |
164 | | | | |
165 | @ in | | |
166 | +-------------------+ | |
167 | ---- | |
168 | ||
169 | ||
170 | === Input | |
171 | ||
172 | `in`:: | |
173 | Single input port. | |
174 | ||
175 | ||
176 | == ENVIRONMENT VARIABLES | |
177 | ||
178 | include::common-common-env.txt[] | |
179 | ||
180 | ||
181 | include::common-footer.txt[] | |
182 | ||
183 | ||
184 | == SEE ALSO | |
185 | ||
186 | man:babeltrace2-intro(7), | |
187 | man:babeltrace2-plugin-text(7) |