Proposed tags for cataloging

[William Cohen <wcohen at redhat dot com>]

William Cohen wrote:

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

I am working on cataloging the systemtap scripts and figuring out a
list of tags for the catalog to describe the scripts.  The following
is a list of tags with quick outline what each does. I have also coded
up some scripts from the systemtap/examples directory to see whether
these tags are enough.

-Will


"title:" Descriptive title for the script (required)

"name:" the file name for the script, e.g. iotime.stp (required)

"version:" versioning if any fixes and developed can be identified (required)

"author:" name of author(s), "anonymous" if unknown (required)


"exclusivearch:" Stated if the script can only run on some arches
		 this concept borrowed from rpm, matches types for rpm:
		 x86 i386 x86_64 ppc ppc64, s390
		 (optional)

"requires:" Some scripts may require software to be available. In some cases
	    may need version numbering, e.g. kernel >= 2.6
	    Can have multiple "requires:" tags. (optional)

"keywords:" list of likely words to categorize the script (required)
	    #FIXME have list of keyword

"subsystem:" list what part of the kernel the instrumentation probes (required)
	audit
	cpu
	blockio
	file
	filesystem
	locking
	memory
	numa
	network
	process
	scheduler
	user-space	probes are in the user-space

"application:" when user-space probing becomes available (optional)
	       a script might probe a particular application
	       this tag indicates the applicaton

"status:" describes the state of development for the script (required)
	proposed    	just an idea
	experimental	an implemented idea, but use at own risk
	alpha		
	beta
	production	should be safe to use

"exit:" how long do the script run? (required)
	fixed			exits in a fixed amount of time
	user-controlled		exits with "cntrl-c"
	event-ended		exits with some arbitrary event

"output:" what kind of output does the script generate? (required)
	trace
	histogram
	graph
	sorted
	batch
	timed

"scope:" How much of the processes on the machine does the script watch?
	system-wide
	pid

"arg_[0-9]+": Describe what the arguments into the script are. (optional)

"description:" A text description what the script does. (required)



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

title: System-Wide Futex Contention
name: futex.stp
version: 1.0
author: anonymous
keywords: systemcall locking futex
subsystem: locking
status: production
exit: user-controlled
output: sorted-list on-exit
scope: system-wide
description:

The script watches the futex systemcalls on the system. The resulting
output is the number of times there was contention on a particular
futex on a per process basis and computes the average amount of time
per contention. This information is printed when the script exits.


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

title: SystemTap "Hello World" Program
name: hello.stp
version: 1.0
author: anonymous
keywords: simple
subsystem: none
status: production
exit: fixed
output: text
scope: system-wide
description:

A basic "Hello World" program implemented in SystemTap script. It
prints out "hello world" message and then immediately exits.

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

title: Track amount of data and time spent in read and write syscalls
name: iotime.stp
version: 1.0
author: Daniel Berrange and Will Cohen
keywords: read write systemcall
subsystem: io
status: production
exit: user-controlled
output: trace
scope: system-wide
description:

Print out the amount of time spent in the read and write systemcall
when a process closes each file is closed. Note that the systemtap
script needs to be running before the open operations occur for
the script to record data.

This script could be used to to find out which files are slow to load
on a machine.

-------------------
title: Network Traffic by Network Interface, Process, and User
name: nettop.stp
version: 1.0
author: anonymous
keywords:
subsystem: network
status: production
exit: user-controlled
output: sorted timed
scope: system-wide
description:

Every 5 seconds prints out the number of transmitted packets, recieved
packets, bytes sent, and bytes received for each process, device name,
and uid tuple that occurred within the 5 second interval.