[RFC] SystemTap FAQ

[RFC] SystemTap FAQ

[Srinivasa Ds]

Literally, just the questions as of now :-)

Please add any questions we've missed; more importantly, please attempt
to answer a few of them too.

Once answered, this will live in the SystemTap wiki.

1) I have installed SystemTap but am getting a "semantic error: libdwfl
failure (missing kernel debuginfo): No such file or directory", when I
try to run a script. What am I missing? How do I fix it?

2) What config options need to be enabled to be able to use SystemTap on
custom built kernels?

3) I have a kernel built with options listed in (2), but still can't get
SystemTap to work. What am I missing?

4) Is it possible for me to view the kernel module generated by SystemTap?

5) How do I run prebuilt SystemTap modules?

6) What should I do when some tapsets functions fails to resolve like 
"semantic error: unresolved arity-1 function: identifier 'log'"

7) This is way cool! I want to write my own scripts. Where do I look for
more information?

8)Is it possible to override some of the macros in SystemTap generated "C" 
module.

9) What are tapsets?

10) I see that there is no tapset for my favourite subsystem. What do I
do?

11) I hear the latest Linux Kernels come with marker support. Does
SystemTap support markers?

12) I am a non-root user, but still want to run SystemTap scripts. Is
that possible?

13) This is fantastic! But how does it all work?

14) Do I have to be a RedHat Enterprise Linux/Fedora user to be able to
use SystemTap?

15) I found a bug when using the tool. How do I report it?

16) I'd like to contribute to the project. Where to I start?


Regards,
Srinivasa 

Re: [RFC] SystemTap FAQ

[Eugene Teo]

Hi Srinivasa,

<quote sender="Srinivasa Ds">
> Literally, just the questions as of now :-)
>
> Please add any questions we've missed; more importantly, please attempt
> to answer a few of them too.

It's probably good to include some common error messages that one may
encounter: http://sources.redhat.com/systemtap/tutorial/node23.html

> 1) I have installed SystemTap but am getting a "semantic error: libdwfl
> failure (missing kernel debuginfo): No such file or directory", when I
> try to run a script. What am I missing? How do I fix it?

There was a problem processing the debugging information. It may simply
be missing, or may have some consistency / correctness problems. Later
compilers tend to produce better debugging information, so if you can
upgrade and recompile your kernel/application, it may help.

Ref: http://sources.redhat.com/systemtap/tutorial/node27.html

> 2) What config options need to be enabled to be able to use SystemTap on
> custom built kernels?

There are instructions at:
http://sources.redhat.com/systemtap/wiki/SystemTapWithSelfBuiltKernel

> 3) I have a kernel built with options listed in (2), but still can't get
> SystemTap to work. What am I missing?

See question 2.

> 4) Is it possible for me to view the kernel module generated by SystemTap?

You can specify -p3 to look at the kernel module code translated by
SystemTap.

stap -p3 <script> | less
stap -p3 -e '...' | less
/sbin/lsmod | grep stap

man stap
[...]
   -p NUM     stop after pass NUM 1-5, instead of 5
              (parse, elaborate, translate, compile, run)

> 5) How do I run prebuilt SystemTap modules?

You can run:

staprun /path/to/<name>.ko

Useful options:
man staprun
[...]
-L  Load module and start probes, then detach.
-A modname.  Attach to systemtap module modname.

> 6) What should I do when some tapsets functions fails to resolve like 
> "semantic error: unresolved arity-1 function: identifier 'log'"

Do ensure that the tapsets are installed at the default location:
/usr/share/systemtap/tapset/ (in RHEL or Fedora) or /usr/local/systemtap/tapset 
if you install from source.

> 7) This is way cool! I want to write my own scripts. Where do I look for
> more information?

You can sign up for our mailing list at:
http://sources.redhat.com/systemtap/getinvolved.html

Read our tutorial at:
http://sources.redhat.com/systemtap/tutorial/

Find out more at:
http://sources.redhat.com/systemtap/wiki

> 8)Is it possible to override some of the macros in SystemTap generated "C" 
> module.

Yes, it is possible:

man stap
[...]
-D NM=VAL  emit macro definition into generated C code

> 9) What are tapsets?

A tapset is just a script that designed for reuse by installation
into a special directory.

http://sources.redhat.com/systemtap/tutorial/node15.html

> 10) I see that there is no tapset for my favourite subsystem. What do I
> do?

You can contribute to the project by writing a tapset for it. Check out
the Tapset Developer's Guide at:
http://sources.redhat.com/cgi-bin/cvsweb.cgi/~checkout~/src/tapset/DEVGUIDE?cvsroot=systemtap
or you can learn how to write a tapset by looking at the existing
collection of tapsets at /usr/share/systemtap/tapset.

> 11) I hear the latest Linux Kernels come with marker support. Does
> SystemTap support markers?

David wrote some information about using markers at:
http://sources.redhat.com/systemtap/wiki/UsingMarkers

> 12) I am a non-root user, but still want to run SystemTap scripts. Is
> that possible?

Yes, it is possible.

Add yourself as a member of 'stapusr' group. Members of stapusr group
can run SystemTap scripts/modules located at /lib/modules/`uname
-r`/systemtap directory.

> 13) This is fantastic! But how does it all work?

src/INTERNALS has some documentation on how the translator work:
http://sources.redhat.com/cgi-bin/cvsweb.cgi/~checkout~/src/INTERNALS?cvsroot=systemtap

> 14) Do I have to be a RedHat Enterprise Linux/Fedora user to be able to
> use SystemTap?

Nope. It is possible to use SystemTap on other Linux distributions. Take
a look at our wiki for more information:
http://sources.redhat.com/systemtap/wiki

> 15) I found a bug when using the tool. How do I report it?

You can file a bug at:
http://sources.redhat.com/bugzilla/enter_bug.cgi?product=systemtap

> 16) I'd like to contribute to the project. Where to I start?

You can join our mailing list:
http://sources.redhat.com/systemtap/getinvolved.html

and/or look at our current bugs/pending features list in the bugzilla:
http://sources.redhat.com/bugzilla/buglist.cgi?query_format=&short_desc_type=allwordssubstr&short_desc=&product=systemtap&long_desc_type=substring&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&gcchost_type=allwordssubstr&gcchost=&gcctarget_type=allwordssubstr&gcctarget=&gccbuild_type=allwordssubstr&gccbuild=&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=SUSPENDED&bug_status=WAITING&bug_status=REOPENED&emailassigned_to1=1&emailtype1=substring&email1=&emailassigned_to2=1&emailreporter2=1&emailcc2=1&emailtype2=substring&email2=&bugidtype=include&bug_id=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Bug+Number&field0-0-0=noop&type0-0-0=noop&value0-0-0=

Thanks,
Eugene

Re: [RFC] SystemTap FAQ

[Eugene Teo]

<quote sender="Eugene Teo">
> > 1) I have installed SystemTap but am getting a "semantic error: libdwfl
> > failure (missing kernel debuginfo): No such file or directory", when I
> > try to run a script. What am I missing? How do I fix it?
> 
> There was a problem processing the debugging information. It may simply
> be missing, or may have some consistency / correctness problems. Later
> compilers tend to produce better debugging information, so if you can
> upgrade and recompile your kernel/application, it may help.
> 
> Ref: http://sources.redhat.com/systemtap/tutorial/node27.html

On RHEL/Fedora, it is missing the kernel-debuginfo rpm.

For RHEL, you can find the rpm at: http://people.redhat.com/duffy/debuginfo.
For Fedora, you can run: yum --enablerepo=fedora-debuginfo install kernel-debuginfo

17) How can I find a list of blacklisted functions?

You can run:
stap -vvv -e 'probe kernel.function("*") {}' -p4 2>&1 | grep blacklisted

Eugene

Re: [RFC] SystemTap FAQ

[Srinivasa Ds]

Srinivasa Ds wrote:
> Literally, just the questions as of now :-)
> 
> Please add any questions we've missed; more importantly, please attempt
> to answer a few of them too.
> 
> Once answered, this will live in the SystemTap wiki.
> 
 
I have put up the SystemTap FAQ page in wiki, http://sourceware.org/systemtap/wiki/SystemTapFAQ.
Please go through it and feel free to add questions(along with answer) to improve it further.

Thanks 
 Srinivasa DS 

Re: [RFC] SystemTap FAQ

[William Cohen]

Srinivasa Ds wrote:
> Srinivasa Ds wrote:
>> Literally, just the questions as of now :-)
>>
>> Please add any questions we've missed; more importantly, please attempt
>> to answer a few of them too.
>>
>> Once answered, this will live in the SystemTap wiki.
>>
> 
> I have put up the SystemTap FAQ page in wiki, 
> http://sourceware.org/systemtap/wiki/SystemTapFAQ.
> Please go through it and feel free to add questions(along with answer) 
> to improve it further.
> 
> Thanks Srinivasa DS

Hi Srinivasa,

Thanks for the FAQ. I have some comments about the FAQ (maybe some comments on 
how SystemTap handles some of the things in FAQ).


1) Seems like systemtap should be able to handle lack of proper debuginfo
    more clearly. It should be possible to distinguish between non-existent
    debug information and incorrect/inconsistent debuginfo.
    The strip files from the rpms have tags to debug file name.

2) Why doesn't systemtap attempt to search for
    /usr/modules/`uname -r`/build/vmlinux?

4) Also mention the -k option to save the resulting stap directory.

17) For RHEL5 can use "yum --enablerepo=rhel-debuginfo" to get debuginfo.

18) What happens when someone forgets the "-p4" option?  bz#2725 can
     cause machine to crash. Are there going to be purpose built
     options in systemtap to print out this information?

-Will

Re: [RFC] SystemTap FAQ

[Srinivasa Ds]

William Cohen wrote:
> Hi Srinivasa,
> 
> Thanks for the FAQ. I have some comments about the FAQ (maybe some 
> comments on how SystemTap handles some of the things in FAQ).
> 
> 
> 1) Seems like systemtap should be able to handle lack of proper debuginfo
>    more clearly. It should be possible to distinguish between non-existent
>    debug information and incorrect/inconsistent debuginfo.
>    The strip files from the rpms have tags to debug file name.

    Let me go through the systemtap error messages in these situations and 
update the wiki.

> 
> 2) Why doesn't systemtap attempt to search for
>    /usr/modules/`uname -r`/build/vmlinux?

Done

> 
> 4) Also mention the -k option to save the resulting stap directory.

Already updated.

> 
> 17) For RHEL5 can use "yum --enablerepo=rhel-debuginfo" to get debuginfo.

Already updated.

> 
> 18) What happens when someone forgets the "-p4" option?  bz#2725 can
>     cause machine to crash. Are there going to be purpose built
>     options in systemtap to print out this information?

There is no specific option for listing blacklisted functions. I think
it is good to have this option.

Thanks
 Srinivasa DS