From: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
Date: Wed, 27 Mar 2013 16:10:44 +0000 (-0400)
Subject: Documentation: filter $ctx manpage and --help
X-Git-Tag: v2.2.0-rc1~10
X-Git-Url: https://git.lttng.org./?a=commitdiff_plain;h=ee8ccafaa999089aa9f6cdc3bc5543cd829c422b;p=lttng-tools.git

Documentation: filter $ctx manpage and --help

Signed-off-by: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
---

diff --git a/doc/man/lttng.1 b/doc/man/lttng.1
index 0a548f825..a8e02fafa 100644
--- a/doc/man/lttng.1
+++ b/doc/man/lttng.1
@@ -408,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:
 
@@ -424,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]"
diff --git a/src/bin/lttng/commands/enable_events.c b/src/bin/lttng/commands/enable_events.c
index 93ef0c5a4..0e6bb55d8 100644
--- a/src/bin/lttng/commands/enable_events.c
+++ b/src/bin/lttng/commands/enable_events.c
@@ -154,8 +154,8 @@ static void usage(FILE *ofp)
 	fprintf(ofp, "                               TRACE_DEBUG          = 14\n");
 	fprintf(ofp, "                               (shortcuts such as \"system\" are allowed)\n");
 	fprintf(ofp, "    --filter \'expression\'\n");
-	fprintf(ofp, "                           Filter expression on event fields,\n");
-	fprintf(ofp, "                           event recording depends on evaluation.\n");
+	fprintf(ofp, "                           Filter expression on event fields and context.\n");
+	fprintf(ofp, "                           Event recording depends on evaluation.\n");
 	fprintf(ofp, "                           Only specify on first activation of\n");
 	fprintf(ofp, "                           a given event within a session.\n");
 	fprintf(ofp, "                           Filter only allowed when enabling\n");
@@ -175,7 +175,20 @@ static void usage(FILE *ofp)
 	fprintf(ofp, "                           'seqfield1 == \"te*\"'\n");
 	fprintf(ofp, "                           In string literals, the escape character is '\\'.\n");
 	fprintf(ofp, "                           Use '\\*' for the '*' character, and '\\\\' for\n");
-	fprintf(ofp, "                           the '\\' character.\n");
+	fprintf(ofp, "                           the '\\' character. Wildcard match any sequence of,\n");
+	fprintf(ofp, "                           characters including an empty sub-string (match 0 or\n");
+	fprintf(ofp, "                           more characters).\n");
+	fprintf(ofp, "\n");
+	fprintf(ofp, "                           Context information can be used for filtering. The\n");
+	fprintf(ofp, "                           examples below show usage of context filtering on\n");
+	fprintf(ofp, "                           process name (with a wildcard), process ID range, and\n");
+	fprintf(ofp, "                           unique thread ID for filtering. The process and\n");
+	fprintf(ofp, "                           thread ID of running applications can be found under\n");
+	fprintf(ofp, "                           columns \"PID\" and \"LWP\" of the \"ps -eLf\" command.\n");
+	fprintf(ofp, "\n");
+	fprintf(ofp, "                           '$ctx.procname == \"demo*\"'\n");
+	fprintf(ofp, "                           '$ctx.vpid >= 4433 && $ctx.vpid < 4455'\n");
+	fprintf(ofp, "                           '$ctx.vtid == 1234'\n");
 	fprintf(ofp, "\n");
 }