lttng cli: Accept human readable sizes for --subbuf-size

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

diff --git a/doc/man/lttng.1 b/doc/man/lttng.1
index 814e1c64fad9bb62fa4b24088f8ba2baf20a8eb9..65fa3d17f465e2a2fcd1dbfb4ef0da8fd1d1c477 100644 (file)
--- a/doc/man/lttng.1
+++ b/doc/man/lttng.1
@@ -230,7 +230,7 @@ Using these options, each API call can be controlled individually. For
 instance, \-C does not enable the consumer automatically. You'll need the \-e
 option for that.
 
-\-U, \-\-set-uri=URL
+\-U, \-\-set-url=URL
         Set URL for the consumer output destination. It is persistent for the
         session lifetime. Redo the command to change it. This will set both
         data and control URL for network.
@@ -297,10 +297,15 @@ If NAME is omitted, the session name is taken from the .lttngrc file.
 .nf
 Enable tracing channel
 
-To enable event, you must first enable a channel which contains event(s).
+To enable an event, you must enable both the event and the channel that
+contains it.
 
 If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
 file.
+
+It is important to note that if a certain type of buffers is used, the session
+will be set with that type and all other subsequent channel need to have the
+same type.
 .fi
 
 .B OPTIONS:
@@ -322,17 +327,47 @@ file.
 \-\-overwrite
         Flight recorder mode : overwrites events when subbuffers are full
 \-\-subbuf-size SIZE
-        Subbuffer size in bytes (default: 4096, kernel default: 262144)
+        Subbuffer size in bytes {+k,+M,+G} (default: 4096, kernel default: 262144)
+        Needs to be a power of 2 for both tracers
 \-\-num-subbuf NUM
         Number of subbuffers (default: 4)
-        Needs to be a power of 2 for kernel and ust tracers
+        Needs to be a power of 2 for both tracers
 \-\-switch-timer USEC
-        Switch subbuffer timer interval in usec (default: 0)
-        Needs to be a power of 2 for kernel and ust tracers
+        Switch subbuffer timer interval in µsec (default: 0)
 \-\-read-timer USEC
-        Read timer interval in usec (default: 200)
+        Read timer interval in µsec (UST default: 0, kernel default: 200000)
 \-\-output TYPE
         Channel output type. Possible values: mmap, splice
+\-\-buffers-uid
+        Use per UID buffer (\-u only). Buffers are shared between applications
+        that have the same UID.
+\-\-buffers-pid
+        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).
+\-W, \-\-tracefile-count COUNT
+        Used in conjunction with \-C option, this will limit the number
+        of files created to the specified count.
+
+.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
@@ -396,12 +431,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:
 
@@ -412,7 +447,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]"