This is the mail archive of the
systemtap@sourceware.org
mailing list for the systemtap project.
Re: [RFC PATCH] Add information about userspace probing
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