babeltrace2-query(1)

1BABELTRACE2-QUERY(1)          Babeltrace 2 manual         BABELTRACE2-QUERY(1)
2
3
4

NAME

6       babeltrace2-query - Query an object from a Babeltrace 2 component class
7

SYNOPSIS

9       babeltrace2 [GENERAL OPTIONS] query [--params=PARAMS]
10                   COMP-CLS-TYPE.PLUGIN-NAME.COMP-CLS-NAME OBJECT
11

DESCRIPTION

13       The query command queries the object named OBJECT from the component
14       class named COMP-CLS-NAME of the type COMP-CLS-TYPE found in the
15       Babeltrace 2 plugin named PLUGIN-NAME and prints the results.
16
17       See babeltrace2-intro(7) to learn more about the Babeltrace 2 project
18       and its core concepts.
19
20       The available values for COMP-CLS-TYPE are:
21
22       source, src
23           Source component class.
24
25       filter, flt
26           Filter component class.
27
28       sink
29           Sink component class.
30
31       The exact object names and the parameters that a given component class
32       expects are described in its own documentation. babeltrace2-help(1) can
33       generally provide this information.
34
35       You can use the --params option to pass parameters to the component
36       class’s query operation.
37
38       The output of the query command can look like YAML (see
39       <https://yaml.org/>), but it’s not guaranteed to be YAML-compliant.
40
41       See “EXAMPLES” for usage examples.
42

OPTIONS

44   General
45       You can use those options before the command name.
46
47       See babeltrace2(1) for more details.
48
49       -d, --debug
50           Legacy option: this is equivalent to --log-level=TRACE.
51
52       -l LVL, --log-level=LVL
53           Set the log level of all known Babeltrace 2 loggers to LVL.
54
55       --omit-home-plugin-path
56           Do not search for plugins in $HOME/.local/lib/babeltrace2/plugins.
57
58       --omit-system-plugin-path
59           Do not search for plugins in /usr/local/lib/babeltrace2/plugins.
60
61       --plugin-path=PATH[:PATH]...
62           Add PATH to the list of paths in which plugins can be found.
63
64       -v, --verbose
65           Legacy option: this is equivalent to --log-level=INFO.
66
67   Query parameters
68       -p PARAMS, --params=PARAMS
69           Set the query parameters to PARAMS.
70
71           The format of PARAMS is a comma-separated list of NAME=VALUE
72           assignments:
73
74               NAME=VALUE[,NAME=VALUE]...
75
76           NAME
77               Parameter name (C identifier plus the :, ., and - characters).
78
79           VALUE
80               One of:
81
82               ·   null, nul, NULL: null value.
83
84               ·   true, TRUE, yes, YES: true boolean value.
85
86               ·   false, FALSE, no, NO: false boolean value.
87
88               ·   Binary (0b prefix), octal (0 prefix), decimal, or
89                   hexadecimal (0x prefix) unsigned (with + prefix) or signed
90                   64-bit integer.
91
92               ·   Double precision floating point number (scientific notation
93                   is accepted).
94
95               ·   Unquoted string with no special characters, and not
96                   matching any of the null and boolean value symbols above.
97
98               ·   Double-quoted string (accepts escape characters).
99
100               ·   Array, formatted as an opening [, a comma-separated list of
101                   VALUE, and a closing ].
102
103               ·   Map, formatted as an opening {, a comma-separated list of
104                   NAME=VALUE assignments, and a closing }.
105
106               You may put whitespaces around the individual = (assignment), ,
107               (separator), [ (array beginning), ] (array end), { (map
108               beginning), and } (map end) characters.
109
110           Example:
111
112               --params='many=null, fresh=yes, condition=false, squirrel=-782329,
113                         play=+23, observe=3.14, simple=beef,
114                         needs-quotes="some string",
115                         escape.chars-are:allowed="a \" quote",
116                         things=[1, "hello", 2.71828],
117                         frog={slow=2, bath=[bike, 23], blind=NO}'
118
119               Important
120               Like in the example above, make sure to single-quote the whole
121               argument when you run this command from a shell, as it can
122               contain many special characters.
123
124   Command information
125       -h, --help
126           Show the command’s help and quit.
127

EXAMPLES

129       Example 1. Query the available tracing sessions of a local LTTng relay
130       daemon.
131
132           $ babeltrace2 query src.ctf.lttng-live sessions \
133                               --params='url="net://localhost"'
134
135       Example 2. Query the metadata info (includes the decoded plain text) of
136       a CTF trace located on the local file system.
137
138           $ babeltrace2 query src.ctf.fs metadata-info \
139                               --params='path="/path/to/trace"'
140
141       Example 3. Query the trace infos of a CTF trace located on the local
142       file system.
143
144           $ babeltrace2 query src.ctf.fs babeltrace.trace-infos \
145                               --params='path="/path/to/trace"'
146
147       Example 4. Query some object from a sink component class without
148       parameters.
149
150           $ babeltrace2 query sink.my-plugin.my-sink some-object
151

ENVIRONMENT VARIABLES

153   Babeltrace 2 library
154       BABELTRACE_EXEC_ON_ABORT=CMDLINE
155           Execute the command line CMDLINE, as parsed like a UNIX 98 shell,
156           when any part of the Babeltrace 2 project unexpectedly aborts.
157
158           The application only aborts when the executed command returns,
159           ignoring its exit status.
160
161           This environment variable is ignored when the application has the
162           setuid or the setgid access right flag set.
163
164       BABELTRACE_TERM_COLOR=(AUTO | NEVER | ALWAYS)
165           Force the terminal color support for the babeltrace2(1) program and
166           the project’s plugins.
167
168           The available values are:
169
170           AUTO
171               Only emit terminal color codes when the standard output and
172               error streams are connected to a color-capable terminal.
173
174           NEVER
175               Never emit terminal color codes.
176
177           ALWAYS
178               Always emit terminal color codes.
179
180       BABELTRACE_TERM_COLOR_BRIGHT_MEANS_BOLD=0
181           Set to 0 to emit SGR (see
182           <https://en.wikipedia.org/wiki/ANSI_escape_code>) codes 90 to 97
183           for bright colors instead of bold (SGR code 1) and standard color
184           codes (SGR codes 30 to 37).
185
186       BABELTRACE_PLUGIN_PATH=PATHS
187           Set the list of directories, in order, in which dynamic plugins can
188           be found before other directories are considered to PATHS
189           (colon-separated, or semicolon on Windows).
190
191       LIBBABELTRACE2_DISABLE_PYTHON_PLUGINS=1
192           Disable the loading of any Babeltrace 2 Python plugin.
193
194       LIBBABELTRACE2_INIT_LOG_LEVEL=LVL
195           Force the Babeltrace 2 library’s initial log level to be LVL.
196
197           If this environment variable is set, it overrides the log level set
198           by the --log-level option for the Babeltrace 2 library logger.
199
200           The available values for LVL are:
201
202           NONE, N
203               Logging is disabled.
204
205           FATAL, F
206               Severe errors that lead the execution to abort immediately.
207
208               This level should be enabled in production.
209
210           ERROR, E
211               Errors that might still allow the execution to continue.
212
213               Usually, once one or more errors are reported at this level,
214               the application, plugin, or library won’t perform any more
215               useful task, but it should still exit cleanly.
216
217               This level should be enabled in production.
218
219           WARN, WARNING, W
220               Unexpected situations which still allow the execution to
221               continue.
222
223               This level should be enabled in production.
224
225           INFO, I
226               Informational messages that highlight progress or important
227               states of the application, plugins, or library.
228
229               This level can be enabled in production.
230
231           DEBUG, D
232               Debugging information, with a higher level of details than the
233               TRACE level.
234
235               This level should NOT be enabled in production.
236
237           TRACE, T
238               Low-level debugging context information.
239
240               This level should NOT be enabled in production.
241
242       LIBBABELTRACE2_NO_DLCLOSE=1
243           Make the Babeltrace 2 library leave any dynamically loaded modules
244           (plugins and plugin providers) open at exit. This can be useful for
245           debugging purposes.
246
247       LIBBABELTRACE2_PLUGIN_PROVIDER_DIR=DIR
248           Set the directory from which the Babeltrace 2 library dynamically
249           loads plugin provider shared objects to DIR.
250
251           If this environment variable is set, it overrides the default
252           plugin provider directory.
253
254   Babeltrace 2 Python bindings
255       BABELTRACE_PYTHON_BT2_LOG_LEVEL=LVL
256           Force the Babeltrace 2 Python bindings log level to be LVL.
257
258           If this environment variable is set, it overrides the log level set
259           by the --log-level option for the Python bindings logger.
260
261           The available values for LVL are:
262
263           NONE, N
264               Logging is disabled.
265
266           FATAL, F
267               Severe errors that lead the execution to abort immediately.
268
269               This level should be enabled in production.
270
271           ERROR, E
272               Errors that might still allow the execution to continue.
273
274               Usually, once one or more errors are reported at this level,
275               the application, plugin, or library won’t perform any more
276               useful task, but it should still exit cleanly.
277
278               This level should be enabled in production.
279
280           WARN, WARNING, W
281               Unexpected situations which still allow the execution to
282               continue.
283
284               This level should be enabled in production.
285
286           INFO, I
287               Informational messages that highlight progress or important
288               states of the application, plugins, or library.
289
290               This level can be enabled in production.
291
292           DEBUG, D
293               Debugging information, with a higher level of details than the
294               TRACE level.
295
296               This level should NOT be enabled in production.
297
298           TRACE, T
299               Low-level debugging context information.
300
301               This level should NOT be enabled in production.
302
303   CLI
304       BABELTRACE_CLI_LOG_LEVEL=LVL
305           Force babeltrace2 CLI’s log level to be LVL.
306
307           If this environment variable is set, it overrides the log level set
308           by the --log-level option for the CLI logger.
309
310           The available values for LVL are:
311
312           NONE, N
313               Logging is disabled.
314
315           FATAL, F
316               Severe errors that lead the execution to abort immediately.
317
318               This level should be enabled in production.
319
320           ERROR, E
321               Errors that might still allow the execution to continue.
322
323               Usually, once one or more errors are reported at this level,
324               the application, plugin, or library won’t perform any more
325               useful task, but it should still exit cleanly.
326
327               This level should be enabled in production.
328
329           WARN, WARNING, W
330               Unexpected situations which still allow the execution to
331               continue.
332
333               This level should be enabled in production.
334
335           INFO, I
336               Informational messages that highlight progress or important
337               states of the application, plugins, or library.
338
339               This level can be enabled in production.
340
341           DEBUG, D
342               Debugging information, with a higher level of details than the
343               TRACE level.
344
345               This level should NOT be enabled in production.
346
347           TRACE, T
348               Low-level debugging context information.
349
350               This level should NOT be enabled in production.
351
352       BABELTRACE_CLI_WARN_COMMAND_NAME_DIRECTORY_CLASH=0
353           Disable the warning message which babeltrace2-convert(1) prints
354           when you convert a trace with a relative path that’s also the name
355           of a babeltrace2 command.
356
357       BABELTRACE_DEBUG=1
358           Legacy variable: equivalent to setting the --log-level option to
359           TRACE.
360
361       BABELTRACE_VERBOSE=1
362           Legacy variable: equivalent to setting the --log-level option to
363           INFO.
364

FILES

366       $HOME/.local/lib/babeltrace2/plugins
367           User plugin directory.
368
369       /usr/local/lib/babeltrace2/plugins
370           System plugin directory.
371
372       /usr/local/lib/babeltrace2/plugin-providers
373           System plugin provider directory.
374

EXIT STATUS

376       0 on success, 1 otherwise.
377

BUGS

379       If you encounter any issue or usability problem, please report it on
380       the Babeltrace bug tracker (see
381       <https://bugs.lttng.org/projects/babeltrace>).
382

RESOURCES

384       The Babeltrace project shares some communication channels with the
385       LTTng project (see <https://lttng.org/>).
386
387       ·   Babeltrace website (see <https://babeltrace.org/>)
388
389       ·   Mailing list (see <https://lists.lttng.org>) for support and
390           development: lttng-dev@lists.lttng.org
391
392       ·   IRC channel (see <irc://irc.oftc.net/lttng>): #lttng on
393           irc.oftc.net
394
395       ·   Bug tracker (see <https://bugs.lttng.org/projects/babeltrace>)
396
397       ·   Git repository (see <https://git.efficios.com/?p=babeltrace.git>)
398
399       ·   GitHub project (see <https://github.com/efficios/babeltrace>)
400
401       ·   Continuous integration (see
402           <https://ci.lttng.org/view/Babeltrace/>)
403
404       ·   Code review (see <https://review.lttng.org/q/project:babeltrace>)
405

AUTHORS

407       The Babeltrace 2 project is the result of hard work by many regular
408       developers and occasional contributors.
409
410       The current project maintainer is Jérémie Galarneau
411       <mailto:jeremie.galarneau@efficios.com>.
412

COPYRIGHT

414       This command is part of the Babeltrace 2 project.
415
416       Babeltrace is distributed under the MIT license (see
417       <https://opensource.org/licenses/MIT>).
418