Re: Draft: SystemTap Instrumentation Script Cataloging and Archiving

[Ananth N Mavinakayanahalli <ananth at in dot ibm dot com>]

On Tue, Mar 25, 2008 at 02:55:00PM -0400, William Cohen wrote:
> 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.

Thanks for kicking this off Will!

...

> 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

FIXME Process for verifying the script works on a variety of platforms
given people may not have access to all platforms. Cross compiling
solves only part of the problem; running the script on hardware is
important.
FIXME Review process for scripts (post to SystemTap lists?)

> 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.

Can't Frank's tapset documentation method be extended for scripts too?

Sample outputs a script generates is very useful for potential users to
determine if it's useful to them. Also, its important to list any
caveats for running the scripts.

Another possible section could be "Future work" or "Possible
Improvements" for the script.

Ananth