Draft: SystemTap Instrumentation Script Cataloging and Archiving

[William Cohen <wcohen at redhat dot com>]

Hi All,

I have been thinking on how to make life easier for people using SystemTap. The 
following are some thoughts on how things might be better organized for user 
scripts. There are still many holes and incomplete areas in it. I would 
appreciate feedback on this.

-Will

-----------------------------------------------------------

SystemTap Instrumentation Script Cataloging and Archiving
Version 0.1


SystemTap provides a powerful infrastructure to dynamically probe
various parts of a running Linux system.  However, the actual methods
to collect key information are often "left as an exercise for the
reader." Most people are not experts in the low-level implementation
details of the system.  Having them develop instrumentation from
scratch or search for existing scripts to collect data to test their
hypothesis can be slow and frustrating.  The SystemTap cataloging and
archiving is designed to improve this:

- Vetting scripts to ensure that Systemtap scripts work on variety of platforms
- Document scripts use and data collected
- Organize scripts to allow people quickly identify candidate scripts
- Packaging collected scripts, e.g. rpm for ready use on machines


Vetting Scripts

There should be review of the script before it is included into the
archive. The script should follow coding guidelines to ensure that
that script will work on a variety of platforms.  The script should be
checked that it actually works on the variety of platforms.  The
framework should ensure that already vetted scripts continue to work.

FIXME describe what is meant by "a variety of platforms."
FIXME more details on coding guidelines
FIXME how to handle combinations of bash and systemtap, e.g. pfiles.sh


Document Scripts

Each script being cataloged and archive needs documentation
describing: what hypothesis the script tests, the sub-systems the
script instruments, what data the script collects, and what output the
script generates.  This information should be included in the script
in a manner that it can be extracted from the script with an automated
tool, e.g. like doxyen.

FIXME how to extract information from script
FIXME describe format of documentation.


Organize and Catalog Scripts

One key to make the scripts convenient for use is to make it easy to
find appropriate instrumentation.  The scripts need to indexed so
people can find appropriate scripts quickly.  There are a number of
different ways of indexing the scripts: technique used (e.g. sampling,
tracing), sub-system instrumented, hypothesis tested, and problem
being diagnosed. Should have multiple indices to allow people to look
things up.

It would be nice if the indices could be generated as html and people
could browse the information as web pages.


Packaging Scripts

The vetted, documented, organized scripts should be included in the
systemtap main code repository.  As a part of the build process these
scripts should be put into a sub-package, systemtap-scripts.  As
mentioned in the "Organize and Catalog Scripts" sections there
probably should be a web page for this. There are scripts posted on the
"War Stories" section of SystemTap wiki, but the "war stories"
SystemTap scripts are not organized.