Commit | Line | Data |
---|---|---|
2facbdc3 PP |
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) |