mi: add machine interface description to man page

[lttng-tools.git] / doc / man / lttng.1

diff --git a/doc/man/lttng.1 b/doc/man/lttng.1
index c8933441eaeff6aa410ffe2d0c59b60538ce9cd1..80861e905fdcefd9d296931d4f58cab240fd24d2 100644 (file)
--- a/doc/man/lttng.1
+++ b/doc/man/lttng.1
@@ -77,6 +77,26 @@ Simple listing of lttng options.
 .TP
 .BR "\-\-list\-commands"
 Simple listing of lttng commands.
+.TP
+.BR "\-m, \-\-mi TYPE
+Machine interface
+
+TYPE supported: XML
+
+Machine interface (MI) mode converts the traditional pretty printing to a
+machine output syntax. MI mode provides a format change-resistant way to access
+information generated via the lttng command line.
+
+When using MI mode, the data is printed on \fBstdout\fP. Error and warning are
+printed on \fBstderr\fP with the pretty print default format.
+
+If any errors occur during the execution of a command, the return value of the
+command will be different than zero. In this case, lttng does NOT guarantee the
+syntax and data validity of the generated MI output.
+
+For XML output type, a schema definition (XSD) file used for validation can be
+found under src/common/mi_lttng.xsd
+
 .SH "COMMANDS"
 
 .PP
@@ -252,9 +272,12 @@ Simple listing of options
 .BR "\-o, \-\-output PATH"
 Specify output path for traces
 .TP
+.BR "\-\-no-output"
+Traces will not be output
+.TP
 .BR "\-\-snapshot"
-Set the session in snapshot mode. Created without a consumer and uses the URL,
-if one is specified, as the default snapshot output. Every channel will be set
+Set the session in snapshot mode. Created in no-output mode and uses the
+URL, if one is specified, as the default snapshot output.  Every channel will be set
 in overwrite mode and with mmap output (splice not supported).
 .TP
 .BR "\-\-live [USEC]"
@@ -399,7 +422,8 @@ Apply to the user-space tracer
 Discard event when subbuffers are full (default)
 .TP
 .BR "\-\-overwrite"
-Flight recorder mode : overwrites events when subbuffers are full
+Flight recorder mode: overwrites events when subbuffers are full. The
+number of subbuffer must be 2 or more.
 .TP
 .BR "\-\-subbuf-size SIZE"
 Subbuffer size in bytes {+k,+M,+G}.
@@ -440,7 +464,7 @@ Use shared buffer for the whole system (\-k only)
 Maximum size of each tracefile within a stream (in bytes).
 0 means unlimited. (default: 0)
 Note: traces generated with this option may inaccurately report
-discarded events as per CTF 1.8.
+discarded events as of CTF 1.8.
 .TP
 .BR "\-W, \-\-tracefile-count COUNT"
 Used in conjunction with \-C option, this will limit the number of files
@@ -745,8 +769,10 @@ List available domain(s)
 Load tracing session configuration
 
 If NAME is omitted, all session configurations found in both the user's session
-configuration directory and the system session configuration directory will be
-loaded.
+configuration directory (default: ~/.lttng/sessions/) and the system session
+configuration directory (default: /etc/lttng/sessions/) will be loaded. Note
+that the sessions in the user directory are loaded first and then the system
+wide directory are loaded.
 
 .B OPTIONS:
 
@@ -758,7 +784,8 @@ Show summary of possible options and commands.
 Load all session configurations (default).
 .TP
 .BR "\-i, \-\-input-path PATH"
-Specify the input path for session configurations.
+Specify the input path for session configurations. This overrides the default
+session configuration directory.
 .TP
 .BR "\-f, -\-force"
 Overwrite current session configuration(s) if a session of the same name
@@ -772,8 +799,12 @@ already exists.
 Save tracing session configuration
 
 If SESSION is omitted, all session configurations will be saved to individual
-\fB.lttng\fP files under the user's session configuration directory. The
-default session configuration file naming scheme is \fBSESSION.lttng\fP.
+\fB.lttng\fP files under the user's session configuration directory (default:
+~/.lttng/sessions/). The default session configuration file naming scheme is
+\fBSESSION.lttng\fP.
+
+For instance, a user in the tracing group saving a session from a root session
+daemon will save it in her/his user directory.
 
 .B OPTIONS:
 
@@ -785,7 +816,8 @@ Show summary of possible options and commands.
 Save all session configurations (default).
 .TP
 .BR "\-o, \-\-output-path PATH"
-Specify the output path for saved sessions (default: ~/.lttng/sessions/).
+Specify the output path for saved sessions. This overrides the default session
+configuration directory.
 .TP
 .BR "\-f, -\-force"
 Overwrite session configuration file if session name clashes.
@@ -876,6 +908,10 @@ Name of the snapshot's output.
 Maximum size in bytes of the snapshot. The maxium size does not include the
 metadata file. Human readable format is accepted: {+k,+M,+G}. For instance,
 \-\-max-size 5M
+
+The minimum size of a snapshot is computed by multiplying the total amount of
+streams in the session by the largest subbuffer size. This is to ensure
+fairness between channels when extracting data.
 .TP
 .BR "\-C, \-\-ctrl-url URL"
 Set control path URL. (Must use -D also)