Re: [RFC PATCH] Add information about userspace probing

[Josh Stone <jistone@redhat.com>]

On 09/29/2009 02:27 PM, Robb Romans wrote:
>> > Here's a patch to add information about userspace probing from the
>> > manual pages and also supplied by Prerna Saxena (thank you!) to the
>> > Language Reference Guide. Please review.
> Committed as 6242e2388294143545af3c10ab9ab33a1bed835e.  If you have
> comments or corrections, I'll be happy to include them.

Sorry for the late review -- I do have a few comments.

> +Userspace probing has several forms.  A non-symbolic probe point such
> +as \newline\texttt{process(PID).statement(ADDRESS).absolute} is
> +analogous to \texttt{kernel.statement(ADDRESS).absolute} in that both
> +use raw, unverified virtual addresses and provide no
> +\texttt{\$variables}.  The target \texttt{PID} parameter must identify
> +a running process and \texttt{ADDRESS} must identify a valid
> +instruction address.  All threads of the listed process will be
> +probed.  This is a guru-level probe.

I think that the .absolute variant should be the last thing mentioned in
this section, since it's a more advanced/difficult construct.

> +You can probe non-symbolic user-kernel interface events handled by
> +utrace. The following constructs are available:
> +\begin{vindent}
> +\begin{verbatim}
> [...]
> +process(PID).insn
> +process("PATH").insn.block
> +process(PID).insn.block
> +process("PATH").insn

The order is a little funny here.

> +process("PATH").mark("LABEL")
> +process("PATH").function("NAME")
> +process("PATH").statement("*@FILE.c:123")
> +process("PATH").function("*").return
> +process("PATH").function("myfun").label("foo")

These aren't really part of the "non-symbolic" set, so they should be
discussed separately.

> +In addition, full symbolic source-level probes in userspace programs
> +and shared libraries are supported.  These are exactly analogous to
> +the symbolic DWARF-based kernel or module probes described previously
> +and expose similar contextual \texttt{\$-variables}.

Can we make "described previously" an actual section reference?

> +\begin{vindent}
> +\begin{verbatim}
> +process("PATH").function("NAME")
> +process("PATH").statement("*@FILE.c:123")
> +process("PATH").function("*").return
> +process("PATH").function("myfun").label("foo")
> +\end{verbatim}
> +\end{vindent}
> +
> +For all process probes, \texttt{PATH} names refer to executables that
> +are searched the same way that shells do: either the explicit path
> +specified, or relative to the working directory if they begin with a
> +dot-slash (./) character sequence. Otherwise, \texttt{\$PATH} is
> +searched.  For example, the following probe syntax:

It's not really "./" that's significant.  Leading with "/" is an
absolute path; containing a "/" anywhere else makes it a relative path;
otherwise it will be $PATH-searched.

> +If a process probe is specified without a \texttt{PID} or
> +\texttt{PATH} parameter, all user threads are probed. However, if
> +systemtap is invoked in target process mode, process probes are
> +restricted to the process hierarchy associated with the target
> +process.

Also, if running in --unprivileged mode, only processes owned by the
current user will be selected.

> +The \texttt{.insn} probe is called for every single-stepped instruction of
> +the process described by \texttt{PID} or \texttt{PATH}.
> +
> +The \texttt{.insn.block} probe is called for every block-stepped
> +instruction of the process described by \texttt{PID} or \texttt{PATH}.
> +
> [...]
> +Using this feature can slow process execution.

Ha -- this is perhaps the understatement of the year. :)  All
instrumentation will slow the target to some degree, but for the .insn
probes it's pretty drastic.

> +\subsubsection{Static userspace probing}

I like that this has a subsection, and I think we should divide up more
of the userspace probing into respective subsections.  This could
possibly be organized as begin/end, syscall, insn[.block], markers,
function/statement, and absolute.

> +Here is an example of prototype symbolic userspace probing support:
> +\begin{vindent}
> +\begin{verbatim}
> +# stap -e 'probe process("ls").function("*").call {
> +           log (probefunc()." ".$$parms)
> +           }' \
> +       -c 'ls -l'
> +\end{verbatim}
> +\end{vindent}

Hmm, this example is in the .mark subsection, but it's using a .function
probe...


Thanks,

Josh