Project

General

Profile

Bug #689

Filters and context: the man pages need a clarification

Added by Daniel U. Thibault over 6 years ago. Updated about 6 years ago.

Status:
Resolved
Priority:
Normal
Assignee:
-
Target version:
Start date:
11/19/2013
Due date:
% Done:

100%

Estimated time:

Description

Reading the enable-event man pages, one can get the impression that filters have the same relation with context that they have with the event's payload fields: one could expect them to fail (and thus exclude events) if the context fields they use have not been added to the channel.

That is not the case: filters have global access to the context, and the add-context command acts quite independently of event filtering.

#1

Updated by David Goulet over 6 years ago

  • Status changed from New to Confirmed
#2

Updated by David Goulet over 6 years ago

  • Status changed from Confirmed to Feedback

Not sure what to clarify here but what about maybe rephrasing this part:

Context information can be used for filtering. The examples below shows...

to something like:

Filters can be applied on context fields. The examples below shows...

Is this the part that is not clear?

#3

Updated by Daniel U. Thibault over 6 years ago

       add-context [OPTIONS]
              Add context to event(s) and/or channel(s).

              A context is basically extra information appended to a  channel.
              For  instance,  you could ask the tracer to add the PID informa?
              tion for all events in a channel. You can also  add  performance
              monitoring unit counters (perf PMU) using the perf kernel API).

              For  example,  this  command  will  add  the context information
              'prio' and two perf counters (hardware branch misses  and  cache
              misses), to all events in the trace data output:

              # lttng add-context -k -t prio -t perf:branch-misses \
                        -t perf:cache-misses
[...]
       enable-event NAME[,NAME2,...] [-k|-u] [OPTIONS]
              Enable tracing event
[...]
              OPTIONS:
[...]
              --filter 'expression'
                     Set  a filter on a newly enabled event. Filter expression
                     on event 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.
[...]
                     Context  information can be used for filtering. The exam?
                     ples 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'

I think this part:

              --filter 'expression'
[...]
                     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.
[...]
                     Context  information can be used for filtering. The exam?
                     ples 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'

needs a paragraph added:

                     Context information is available to all filters whether
                     or not the add-context command has been used to add it to
                     the event's channel, as long as the context field exists
                     for that domain. For example, the filter examples given
                     above will never fail to link: no add-context is required
                     for the event's channel.

My point is simply that add-context does change the filter's context, it only serves to make chosen context fields explicit in the event record.

#4

Updated by David Goulet about 6 years ago

  • Status changed from Feedback to Confirmed
#5

Updated by David Goulet about 6 years ago

  • Status changed from Confirmed to Resolved
  • % Done changed from 0 to 100

Also available in: Atom PDF