[babeltrace.git] / doc / man / babeltrace2-query.1.txt

= babeltrace2-query(1)
:manpagetype: command
:revdate: 14 September 2019


== NAME

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


== SYNOPSIS

[verse]
*babeltrace2* [<<gen-opts,'GENERAL OPTIONS'>>] *query* [opt:--params='PARAMS']
            'COMP-CLS-TYPE'.'PLUGIN-NAME'.'COMP-CLS-NAME' 'OBJECT'


== DESCRIPTION

The `query` command queries the object named 'OBJECT' from the component
class named 'COMP-CLS-NAME' of the type 'COMP-CLS-TYPE' found in the
Babeltrace~2 plugin named 'PLUGIN-NAME' and prints the results.

include::common-see-babeltrace2-intro.txt[]

The available values for 'COMP-CLS-TYPE' are:

`source`::
`src`::
    Source component class.

`filter`::
`flt`::
    Filter component class.

`sink`::
    Sink component class.

The exact object names and the parameters that a given component class
expects are described in its own documentation. man:babeltrace2-help(1)
can generally provide this information.

You can use the opt:--params option to pass parameters to the component
class's query operation.

The output of the `query` command can look like https://yaml.org/[YAML],
but it's not guaranteed to be YAML-compliant.

See <<examples,``EXAMPLES''>> for usage examples.


== OPTIONS

include::common-gen-options.txt[]


=== Query parameters

opt:-p 'PARAMS'::
opt:--params='PARAMS'::
    Set the query parameters to 'PARAMS'.
+
--
include::common-cmd-params-format.txt[]
--


include::common-cmd-info-options.txt[]


[[examples]]
== EXAMPLES

.Query the available tracing sessions of a local LTTng relay daemon.
====
[role="term"]
----
$ babeltrace2 query src.ctf.lttng-live sessions \
                    --params='url="net://localhost"'
----
====

.Query the metadata info (includes the decoded plain text) of a CTF trace located on the local file system.
====
[role="term"]
----
$ babeltrace2 query src.ctf.fs metadata-info \
                    --params='inputs=["/path/to/trace"]'
----
====

.Query the trace infos of a CTF trace located on the local file system.
====
[role="term"]
----
$ babeltrace2 query src.ctf.fs babeltrace.trace-infos \
                    --params='inputs=["/path/to/trace"]'
----
====

.Query some object from a sink component class without parameters.
====
[role="term"]
----
$ babeltrace2 query sink.my-plugin.my-sink some-object
----
====


include::common-cli-env.txt[]


include::common-cli-files.txt[]


include::common-cmd-footer.txt[]


== SEE ALSO

man:babeltrace2-intro(7),
man:babeltrace2(1)
Commit	Line	Data
	1	= babeltrace2-query(1)
	2	:manpagetype: command
	3	:revdate: 14 September 2019
	4
	5
	6	== NAME
	7
	8	babeltrace2-query - Query an object from a Babeltrace 2 component class
	9
	10
	11	== SYNOPSIS
	12
	13	[verse]
	14	babeltrace2 [<<gen-opts,'GENERAL OPTIONS'>>] query [opt:--params='PARAMS']
	15	'COMP-CLS-TYPE'.'PLUGIN-NAME'.'COMP-CLS-NAME' 'OBJECT'
	16
	17
	18	== DESCRIPTION
	19
	20	The `query` command queries the object named 'OBJECT' from the component
	21	class named 'COMP-CLS-NAME' of the type 'COMP-CLS-TYPE' found in the
	22	Babeltrace~2 plugin named 'PLUGIN-NAME' and prints the results.
	23
	24	include::common-see-babeltrace2-intro.txt[]
	25
	26	The available values for 'COMP-CLS-TYPE' are:
	27
	28	`source`::
	29	`src`::
	30	Source component class.
	31
	32	`filter`::
	33	`flt`::
	34	Filter component class.
	35
	36	`sink`::
	37	Sink component class.
	38
	39	The exact object names and the parameters that a given component class
	40	expects are described in its own documentation. man:babeltrace2-help(1)
	41	can generally provide this information.
	42
	43	You can use the opt:--params option to pass parameters to the component
	44	class's query operation.
	45
	46	The output of the `query` command can look like https://yaml.org/[YAML],
	47	but it's not guaranteed to be YAML-compliant.
	48
	49	See <<examples,``EXAMPLES''>> for usage examples.
	50
	51
	52	== OPTIONS
	53
	54	include::common-gen-options.txt[]
	55
	56
	57	=== Query parameters
	58
	59	opt:-p 'PARAMS'::
	60	opt:--params='PARAMS'::
	61	Set the query parameters to 'PARAMS'.
	62	+
	63	--
	64	include::common-cmd-params-format.txt[]
	65	--
	66
	67
	68	include::common-cmd-info-options.txt[]
	69
	70
	71	[[examples]]
	72	== EXAMPLES
	73
	74	.Query the available tracing sessions of a local LTTng relay daemon.
	75	====
	76	[role="term"]
	77	----
	78	$ babeltrace2 query src.ctf.lttng-live sessions \
	79	--params='url="net://localhost"'
	80	----
	81	====
	82
	83	.Query the metadata info (includes the decoded plain text) of a CTF trace located on the local file system.
	84	====
	85	[role="term"]
	86	----
	87	$ babeltrace2 query src.ctf.fs metadata-info \
	88	--params='inputs=["/path/to/trace"]'
	89	----
	90	====
	91
	92	.Query the trace infos of a CTF trace located on the local file system.
	93	====
	94	[role="term"]
	95	----
	96	$ babeltrace2 query src.ctf.fs babeltrace.trace-infos \
	97	--params='inputs=["/path/to/trace"]'
	98	----
	99	====
	100
	101	.Query some object from a sink component class without parameters.
	102	====
	103	[role="term"]
	104	----
	105	$ babeltrace2 query sink.my-plugin.my-sink some-object
	106	----
	107	====
	108
	109
	110	include::common-cli-env.txt[]
	111
	112
	113	include::common-cli-files.txt[]
	114
	115
	116	include::common-cmd-footer.txt[]
	117
	118
	119	== SEE ALSO
	120
	121	man:babeltrace2-intro(7),
	122	man:babeltrace2(1)