From 9bd578f50a1e2438c40ca10789ca90d63c8f8829 Mon Sep 17 00:00:00 2001 From: Mathieu Desnoyers Date: Tue, 17 Jul 2012 11:26:54 -0400 Subject: [PATCH] Document filter (help and manpage) Signed-off-by: Mathieu Desnoyers --- doc/man/lttng.1 | 28 ++++++++++++++++++++------ src/bin/lttng/commands/enable_events.c | 17 +++++++++++++++- 2 files changed, 38 insertions(+), 7 deletions(-) diff --git a/doc/man/lttng.1 b/doc/man/lttng.1 index 417f799c4..089d87fa0 100644 --- 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 @@ -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. + \-\-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]" diff --git a/src/bin/lttng/commands/enable_events.c b/src/bin/lttng/commands/enable_events.c index de1796ad8..453545732 100644 --- 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, " 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"); } -- 2.34.1