lttng-view(1)
=============
+:revdate: 14 June 2021
NAME
----
-lttng-view - View the traces of an LTTng tracing session
+lttng-view - Launch an LTTng trace reader
SYNOPSIS
--------
[verse]
-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *view* [option:--viewer='CMD'] [option:--trace-path='PATH' | 'SESSION']
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *view* [option:--viewer='READER']
+ ['SESSION' | option:--trace-path='DIR']
DESCRIPTION
-----------
-The `lttng view` command launches an external trace viewer to view the
-current trace of a tracing session.
+The `lttng view` command launches an external trace reader to read the
+current traces of:
-If 'SESSION' is omitted, the viewer is launched for the current tracing
-session (see linklttng:lttng-create(1) for more information
-about the current tracing session). Otherwise, it is launched for the
-existing tracing session named 'SESSION'. `lttng list`
-outputs all the existing tracing sessions (see linklttng:lttng-list(1)).
+With the option:--session='SESSION' option::
+ The recording session named 'SESSION'.
-By default, the linklttng:babeltrace(1) trace viewer is launched.
-Another trace viewer command can be specified using the
-option:--viewer option.
+With the option:--trace-path='DIR' option::
+ The local file system directory 'DIR'.
-By default, the trace path of the chosen tracing session is given
-as the first positional argument to the trace viewer. This path can
-be overridden using the option:--trace-path option.
+Otherwise::
+ The current recording session (see man:concepts(1) to learn more
+ about the current recording session).
+With the option:--session option or without the option:--trace-path
+option, the mode of the selected recording session may :not: be network
+streaming or live.
-include::common-cmd-options-head.txt[]
+By default, the `view` command attempts to launch man:babeltrace2(1) or,
+if it's not available, man:babeltrace(1). Override which trace reader to
+launch with the option:--viewer option.
+See the ``<<examples,EXAMPLES>>'' section below for usage examples.
-option:-t, option:--trace-path='PATH'::
- View trace at path 'PATH' instead of using the chosen tracing
- session's trace path.
-option:-e, option:--viewer='CMD'::
- Use 'CMD' as the trace viewer.
+include::common-lttng-cmd-options-head.txt[]
-include::common-cmd-help-options.txt[]
+option:-t 'DIR', option:--trace-path='DIR'::
+ Pass 'DIR' as the last argument of the trace reader command instead
+ of the output directory of the selected recording session.
+option:-e 'READER', option:--viewer='READER'::
+ Use the trace reader 'READER' to read the traces.
++
+'READER' is the absolute path to the reader command to use, and it can
+contain command arguments as well. The `view` command passes the trace
+directory path to read to the 'READER' command as its last argument.
++
+Without this option, the `view` command uses man:babeltrace2(1) if it's
+available. Otherwise, it tries to use man:babeltrace(1).
-include::common-cmd-footer.txt[]
+
+include::common-lttng-cmd-help-options.txt[]
+
+
+include::common-lttng-cmd-after-options.txt[]
+
+
+[[examples]]
+EXAMPLES
+--------
+.Read the traces of the current recording session with Babeltrace.
+====
+[role="term"]
+----
+$ lttng view
+----
+====
+
+.Read the traces of a specific recording session with a custom trace reader.
+====
+See the option:--viewer option.
+
+[role="term"]
+----
+$ lttng view --viewer='/usr/bin/my-reader -zK --details=3' \
+ my-session
+----
+====
+
+
+include::common-footer.txt[]
SEE ALSO
--------
-linklttng:lttng(1)
+man:babeltrace2(1),
+man:lttng(1)