This is the mail archive of the systemtap@sourceware.org mailing list for the systemtap project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Basics of new sample command within interactive mode


Hello,

Back near the end of September, a new command was added to interactive
mode, sample.  The intention of sample was to give users a convenient
way to search through the example scripts included with Systemtap.
Recently the command was updated to accept FTS3 MATCH statements
rather than a single keyword.  After searching using a statement, all
matching example scripts are returned for the user to select and load
then edit, inspect, run, etc...

Within interactive mode, a short help message demonstrates some of the
available keywords and statement options but not all.  I'm going to
cover a few examples to showcase everything the new command supports.

There are three basic query types: token/token prefix, phrase and near.

Token/token prefix are the simplest.  A specific term is searched for such as:

    sample socket
    sample socket trace

'*' can be appended to a token as a wildcard.
'^' can be prefixed to a token which will only return an example if
the token is the first in any column.
A column name can be prefixed to a term to search only a specific
column rather than every column:

    sample title:socket

The available columns are title, name, description, keywords, and path.

The second query type is phrase which will return anything that
contains a specified set of terms or term prefixes in a specific
order.

    sample "socket trace"
    sample "^sock* t*"

The third type of query is a near query.  It will return when there
are two or more specified terms/phrases within a specific proximity to
each other.  By default, there cannot be 10 or more intervening terms
in order for there to be a return.

    sample socket NEAR trace

Using NEAR/<N>, the maximum number of intervening terms can be changed
from the default 10 to N.  Phrases can also be used with the NEAR
operator.

    sample network NEAR/5 "trace* thread*"

More than one NEAR operator can be used in the same query.

    sample network NEAR/5 trace* NEAR/2 thread*

In this example, "network" needs to be within 5 terms of "trace*" and
"trace*" needs to be within 2 terms of "thread*".

In addition to the three types of queries, there are also three
operators.  AND, OR, and NOT.  These are performed on results of the
basic queries.

    sample network NEAR/5 trace* OR ^socket*

The sample command is using the enhanced query syntax.  As a result,
the operators have a precedence.  NOT is the highest precedence while
OR is the lowest.  Parenthesis may be used to override this
precedence.

    sample network AND (trace* OR pid)
    sample network AND trace* OR pid

The second example will give more results as it includes any example
that contains "pid" while the first example only includes examples
from "pid" that also include "network".

If anyone has any feedback regarding the examples I went over or the
sample command as a whole I would love to hear it.

Thank you,

Cody Santing


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]