tests: implement context filtering tests

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

diff --git a/doc/man/lttng.1 b/doc/man/lttng.1
index 0de06d7cbec62ede56a73a24b40bf452ae486269..a8e02fafa11718c70436559071d6069c9d3f4f82 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,7 +297,8 @@ 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.
@@ -327,14 +328,14 @@ same type.
         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
 \-\-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 (default: 200)
 \-\-output TYPE
         Channel output type. Possible values: mmap, splice
 \-\-buffers-uid
@@ -407,12 +408,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:
 
@@ -423,7 +424,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]"