Document filter (help and manpage)

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

diff --git a/doc/man/lttng.1 b/doc/man/lttng.1
index 417f799c49c25a48275d35ba0c5e7e67315af96d..089d87fa09861188d8e38551b1c4fde7b54829cf 100644 (file)
--- a/doc/man/lttng.1
+++ b/doc/man/lttng.1
@@ -1,4 +1,4 @@
-.TH "LTTNG" "1" "February 9, 2012" "" ""
+.TH "LTTNG" "1" "July 17, 2012" "" ""

 
 .SH "NAME"
 lttng \(em LTTng 2.0 tracer control command line tool
 
 .SH "NAME"
 lttng \(em LTTng 2.0 tracer control command line tool


@@ -340,13 +340,29 @@ file.
         Enabling syscalls tracing (kernel tracer), you will not be able to disable them
         with disable-event. This is a known limitation. You can disable the entire
         channel to do the trick.
         Enabling syscalls tracing (kernel tracer), you will not be able to disable them
         with disable-event. This is a known limitation. You can disable the entire
         channel to do the trick.

+

 \-\-filter 'expression'
        Set a filter on a newly enabled event.
 \-\-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.
+       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.
+       Expression examples:
+
+       'intfield > 500 && intfield < 503'
+       '(stringfield == "test" || intfield != 10) && intfield > 33'
+       'doublefield > 1.1 && intfield < 5.3'
+
+       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.
+

 .fi
 
 .IP "\fBdisable-channel\fP NAME[,NAME2,...] [\-k|\-u] [OPTIONS]"
 .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 de1796ad8ed0e7fa8f6fe06d363c7ad33787e8f0..45354573207cc9995106d5862e01e106526eccd1 100644 (file)
--- a/src/bin/lttng/commands/enable_events.c
+++ b/src/bin/lttng/commands/enable_events.c
@@ -172,7 +172,22 @@ static void usage(FILE *ofp)
        fprintf(ofp, "                           a given event within a session.\n");
        fprintf(ofp, "                           Filter only allowed when enabling\n");
        fprintf(ofp, "                           events within a session before tracing\n");
        fprintf(ofp, "                           a given event within a session.\n");
        fprintf(ofp, "                           Filter only allowed when enabling\n");
        fprintf(ofp, "                           events within a session before tracing\n");

-       fprintf(ofp, "                           is started.\n");
+       fprintf(ofp, "                           is started. If the filter fails to link\n");
+       fprintf(ofp, "                           with the event within the traced domain,\n");
+       fprintf(ofp, "                           the event will be discarded. Currently,\n");
+       fprintf(ofp, "                           filter is only implemented for the user-space\n");
+       fprintf(ofp, "                           tracer.\n");
+       fprintf(ofp, "                           Expression examples:.\n");
+       fprintf(ofp, "                           \n");
+       fprintf(ofp, "                           'intfield > 500 && intfield < 503'\n");
+       fprintf(ofp, "                           '(stringfield == \"test\" || intfield != 10) && intfield > 33'\n");
+       fprintf(ofp, "                           'doublefield > 1.1 && intfield < 5.3'\n");
+       fprintf(ofp, "                           \n");
+       fprintf(ofp, "                           Wildcards are allowed at the end of strings:\n");
+       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, "\n");
 }
 
        fprintf(ofp, "\n");
 }