From ee8ccafaa999089aa9f6cdc3bc5543cd829c422b Mon Sep 17 00:00:00 2001 From: Mathieu Desnoyers Date: Wed, 27 Mar 2013 12:10:44 -0400 Subject: [PATCH] Documentation: filter $ctx manpage and --help Signed-off-by: Mathieu Desnoyers --- doc/man/lttng.1 | 26 +++++++++++++++++++------- src/bin/lttng/commands/enable_events.c | 19 ++++++++++++++++--- 2 files changed, 35 insertions(+), 10 deletions(-) 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"); } -- 2.34.1