This is the mail archive of the
systemtap@sourceware.org
mailing list for the systemtap project.
Re: Draft: SystemTap Instrumentation Script Cataloging and Archiving
- From: William Cohen <wcohen at redhat dot com>
- To: "Frank Ch. Eigler" <fche at redhat dot com>
- Cc: SystemTAP <systemtap at sources dot redhat dot com>
- Date: Wed, 26 Mar 2008 15:02:23 -0400
- Subject: Re: Draft: SystemTap Instrumentation Script Cataloging and Archiving
- References: <47E94A84.10001@redhat.com> <y0mmyolbgpq.fsf@ton.toronto.redhat.com>
Frank Ch. Eigler wrote:
wcohen wrote:
SystemTap Instrumentation Script Cataloging and Archiving
Version 0.1
Frank,
Thanks for the comments.
It's a good start. Here are some simple specifics I suggest:
Packaging Scripts
- Scripts should be placed under examples/CLASS/ in the following form:
- main script body: SAMPLE.stp
- runnable demo driver: SAMPLE.sh, which presumably includes a
call to "stap STAMPLE.stp ..."
- documentation: SAMPLE.txt, in a stylized form TBD,
including headers such as "Keyword: foo", "Summary: bar"
- preferably, no other files, so extra stuff like C code
would need to be stored within SAMPLE.sh
- examples/CATALOG should be a text file mechanically produced
by grepping for headers in the */*.txt stylized documentation files.
I was originally thinking about having things in one file. However, it might be
unwieldly to have everything in one file. Having extensions such as above is a
reasonable alternative. It would allow less modification of the originally
submitted script.
.txt file might not provide enough. Would like to have formatting for web pages
or printed version of the documentation. Maybe something like docbook would be
more appropriate.
Vetting Scripts
- Scripts be offered for review on the mailing list, so that
they can demonstrate good function and style.
As this gets more developed assume that there would be a style sheet that people
could check before they send it to the mailing list.
- Scripts should be at least buildok-tested by the dejagnu "make check".
This can be done by a generic .exp file that runs "stap -p4" on all
.stp files matching examples/*/*.stp, except those that require
command line arguments ($1 or @1).
- Scripts should be runok-tested by the dejagnu "make installcheck".
This can be done by a generic .exp file that runs each of the
examples/*/*.sh scripts, perhaps amended by per-sample tcl code.
Yes, testing certainly alluded to in the draft. Would there be some way to have
the testing done either buildok or runok? Seems redundant to do the buildok AND
the runok.
The one place that runok testing wouldn't work are examples that purposely
generate an oops such as "Panicking the system from systemtap":
http://sourceware.org/systemtap/wiki/WSPanicOnOom?highlight=%28%28WarStories%29%29
Document Scripts
- Need to propose a documentation template. As mentioned above, I
suggest a simple .txt file with a few standard headers that
we can extract for the catalog file. One could start from the
wiki WarStories template.
The war stories are a good starting point. The main thing they are missing is
the cataloging information.
- IMO, it is not necessary that this stuff be literally part of the
.stp file. It would make them hard to read (much longer) and use as
a basis for experimentation.
Keeping the scripts small seems like a good idea, but what happens as people
pull the script out of context, e.g. mail script to someone else?
Organize and Catalog Scripts
- Need to propose a set of CLASS subdirectories for examples/;
perhaps language/, profiling/, monitoring/
What happens when examples could be in multiple categories? Have symbolic links
to the master copy? Are symbolic links even allowed in revision control systems?
- Need to enumerate all the places where potential samples
currently reside (src/examples, src/testsuite/*, warstories,
tutorial, langref, mailing lists, "systemtap help" bugzillas).
- Need to actually collect them.
- Need to retire the old copies if possible, so as to make the
src/examples/ the sole copy.
There should be version information in the script, so one can determine whether
current up-to-date version.
- Need to post the samples back to the web for search engine
and casual onlooker visibility. It may be enough to link to
<http://sourceware.org/git/?p=systemtap.git;a=tree;f=examples>.
Having the library on the web is a goal. If someone's favorite search engine can
do a good job indexing the examples, all the better.
-Will