This is the mail archive of the systemtap@sourceware.org mailing list for the systemtap project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: Draft: SystemTap Instrumentation Script Cataloging and Archiving


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


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]