Draft: SystemTap Instrumentation Script Cataloging and Archiving

[William Cohen]

Ananth N Mavinakayanahalli wrote:
> 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?)

Thinking something like the following steps:

1) person gets idea for script
2) person writes script
3) person tries out script in their environment
4) person goes through checklist for acceptable scripts e.g.:
	no guru mode
	no line statement
5) script posted on mailing list
6) script checked into an incubator directory in code repo
	the incubator directory would test build the script (but not run)
7) people manually test run script on various machines
8) developer moves script from incubator to normal directory in code repo
	script built and run as part of normal tests

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

bz5679? For the cataloging probably want more details than single lines.

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

With example output certainly more than couple lines of output.

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

-Will