X-Git-Url: https://git.lttng.org/?a=blobdiff_plain;f=doc%2Fman%2Flttng.1;h=26fd44a69db986148a9b7150868a721b8ca8f4b1;hb=feb0f3e5900ff58202ea0c3f227de3c1b8291952;hp=0a548f825e9ab925e0c8bc274e99624b2f6f6966;hpb=004f3466ecdda5e828d27d4a077a4234f57a2707;p=lttng-tools.git

diff --git a/doc/man/lttng.1 b/doc/man/lttng.1
index 0a548f825..26fd44a69 100644
--- a/doc/man/lttng.1
+++ b/doc/man/lttng.1
@@ -1,7 +1,7 @@
 .TH "LTTNG" "1" "December 3rd, 2012" "" ""
 
 .SH "NAME"
-lttng \(em LTTng 2.1.x tracer control command line tool
+lttng \(em LTTng 2.x tracer control command line tool
 
 .SH "SYNOPSIS"
 
@@ -214,6 +214,10 @@ automatically created having this form: 'auto-yyyymmdd-hhmmss'.
 
 If no \fB\-o, \-\-output\fP is specified, the traces will be written in
 $HOME/lttng-traces.
+
+The $HOME environment variable can be overridden by defining the environment
+variable LTTNG_HOME. This is useful when the user running the commands has
+a non-writeable home directory.
 .fi
 
 .B OPTIONS:
@@ -327,17 +331,21 @@ same type.
 \-\-overwrite
         Flight recorder mode : overwrites events when subbuffers are full
 \-\-subbuf-size SIZE
-        Subbuffer size in bytes (default: 4096, kernel default: 262144)
-        Needs to be a power of 2 for both tracers
+        Subbuffer size in bytes {+k,+M,+G}
+        (default UST uid: 131072, UST pid: 4096, kernel: 262144, metadata: 4096)
+        Rounded up to the next power of 2.
 \-\-num-subbuf NUM
-        Number of subbuffers (default: 4)
-        Needs to be a power of 2 for both tracers
+        Number of subbuffers. (default UST uid: 4, UST pid: 4, kernel: 4, metadata: 2)
+        Rounded up to the next power of 2.
 \-\-switch-timer USEC
-        Switch subbuffer timer interval in µsec (default: 0)
+        Switch subbuffer timer interval in µsec.
+        (default UST uid: 0, UST pid: 0, kernel: 0, metadata: 0)
 \-\-read-timer USEC
-        Read timer interval in µsec (default: 200)
+        Read timer interval in µsec.
+        (default UST uid: 0, UST pid: 0, kernel: 200000, metadata: 0)
 \-\-output TYPE
         Channel output type. Possible values: mmap, splice
+        (default UST uid: mmap, UST pid: mmap, kernel: splice, metadata: mmap)
 \-\-buffers-uid
         Use per UID buffer (\-u only). Buffers are shared between applications
         that have the same UID.
@@ -345,6 +353,30 @@ same type.
         Use per PID buffer (\-u only). Each application has its own buffers.
 \-\-buffers-global
         Use shared buffer for the whole system (\-k only)
+\-C, \-\-tracefile-size SIZE
+        Maximum size of each tracefile within a stream (in bytes).
+		0 means unlimited. (default: 0)
+\-W, \-\-tracefile-count COUNT
+        Used in conjunction with \-C option, this will limit the number
+        of files created to the specified count. 0 means unlimited. (default: 0)
+
+.B EXAMPLES:
+
+$ lttng enable-channel -C 4096 -W 32 chan1
+For each stream, the maximum size of a trace file will be 4096 bytes divided
+over a \fBmaximum\fP of 32 different files. The file count is appended after
+the stream number as seen in the following example. The last trace file is
+smaller than 4096 since it was not completely filled.
+
+        ~/lttng-traces/[...]/chan1_0_0 (4096)
+        ~/lttng-traces/[...]/chan1_0_1 (4096)
+        ~/lttng-traces/[...]/chan1_0_2 (3245)
+        ~/lttng-traces/[...]/chan1_1_0 (4096)
+        ...
+
+$ lttng enable-channel -C 4096
+This will create trace files of 4096 bytes and will create new ones as long as
+there is data available.
 .fi
 
 .IP
@@ -408,12 +440,12 @@ file.
 
 \-\-filter 'expression'
         Set a filter on a newly enabled event. Filter expression on event
-        fields, event recording depends on evaluation. Only specify on first
-        activation of a given event within a session. Filter only allowed when
-        enabling events within a session before tracing is started. If the
-        filter fails to link with the event within the traced domain, the event
-        will be discarded. Currently, filter is only implemented for the
-        user-space tracer.
+	fields and context. Event recording depends on evaluation. Only
+	specify on first activation of a given event within a session.
+	Filter only allowed when enabling events within a session before
+	tracing is started. If the filter fails to link with the event
+	within the traced domain, the event will be discarded.
+	Currently, filter is only implemented for the user-space tracer.
 
         Expression examples:
 
@@ -424,7 +456,19 @@ file.
         Wildcards are allowed at the end of strings:
         'seqfield1 == "te*"'
         In string literals, the escape character is a '\\'. Use '\\*' for
-        the '*' character, and '\\\\' for the '\\' character.
+        the '*' character, and '\\\\' for the '\\' character. Wildcard
+	match any sequence of characters, including an empty sub-string
+	(match 0 or more characters).
+
+	Context information can be used for filtering. The examples
+	below show usage of context filtering on process name (with a
+	wildcard), process ID range, and unique thread ID for filtering.
+	The process and thread ID of running applications can be found
+	under columns "PID" and "LWP" of the "ps -eLf" command.
+
+	'$ctx.procname == "demo*"'
+	'$ctx.vpid >= 4433 && $ctx.vpid < 4455'
+	'$ctx.vtid == 1234'
 .fi
 
 .IP "\fBdisable-channel\fP NAME[,NAME2,...] [\-k|\-u] [OPTIONS]"