.\" -*- nroff -*-
.TH STAP 1 @DATE@ "Red Hat"
.SH NAME
stapgraph \- systemtap grapher

.\" macros
.de SAMPLE
.br
.RS
.nf
.nh
..
.de ESAMPLE
.hy
.fi
.RE
..

.SH SYNOPSIS

.br
.B stapgraph
[
.I OPTIONS
]
.I FILENAME
[
.I ARGUMENTS
]
.br
.B stapgraph
[
.I OPTIONS
]
.B \-
[
.I ARGUMENTS
]
.br
.B stapgraph
[
.I OPTIONS
]
.BI \-e " SCRIPT"
[
.I ARGUMENTS
]

.SH DESCRIPTION

The
.IR stapgraph
program is a simple frontend to
.IR stap
that produces graphs from the output of
.IR stap
scripts.
.PP
This manual corresponds to version @VERSION@.

.SH OPTIONS
.IR stapgraph
accepts all options accepted by
.IR stap.
They are passed through to the
.IR stap
process running the script or probe points.

.SH USER INTERFACE

The script that produces results can be started from a dialog within
the program, in addition to being launched using the program's command line
arguments. This dialog allows arguments to be passed to
.IR stap
and to the script.
.PP
When running, a mouse left click on a graph pauses the display of
data, even though it is still collected by the program. Dragging the
mouse scrolls the graph backwards and forwards in time; clicking the
displayed pause button restarts the display of new data.
.PP
The scroll wheel can be used to zoom in and out on the graph.

.SH SCRIPT OUTPUT SYNTAX
Scripts can output  Comma Seperated Values (CSV) which will be interpreted by
.IR stapgraph.
The first value is the X coordinate of the graph, usually a time value.
.IR stapgraph
assumes that this value is constantly increasing.
.PP
A different syntax allows the script to specify many details of the
graph's appearance.
.TP
.BR %DataSet: " DATA-SET-NAME " " SCALE " " COLOR " " GRAPHSTYLE "
.PP
The data set name identifies a data set that will be emitted by the script. 
"SCALE" is the overall vertical scale of the graph for this data
set. "COLOR" is a red-green-blue hex color. "GRAPHSTYLE" is one of
bar - a traditional bar graph
dot - plotted points
discreet - An event style timeline that records that an event
happened at a certain time.
.TP
.BR %Title: " TITLE "
A title for the whole graph.
.TP
.BR %XAxisTitle: " TITLE "
The legend for the X axis
.TP
.BR %YAxisTitle: " TITLE "
The legend for the Y axis.
.TP
.BR %YMax: " MAX VALUE "
The maximum value displayed on the graph.

.SH GRAPH DATA
.BR " DATA SET " " TIME " " VALUE "
Each data point that is to be plotted is tagged with the data set
name, followed by the time and value of the point.

.SH SEE ALSO
.IR stap (3stap),
.IR staprun (3stap),

.SH BUGS
Use the Bugzilla link off of the project web page or our mailing list.
.nh
.BR http://sources.redhat.com/systemtap/ , <systemtap@sources.redhat.com> .
.hy