EVTRANALYZE(1)

NAME
evtranalyze - analyze a trace stream

SYNOPSIS
evtranalyze [-f infile] command [argument ...]

DESCRIPTION
The evtranalyze utility is used to analyze an event trace stream. It takes a few global options, after which the user should specify a subcommand, followed by the subcommands options.

  Global options
The global options are

-f path
    Specifies the file containing the event stream.

The subcommands are:

show
Lists the individual events, one per line. The timestamps are relative to the previous event. The flags it accepts are:

-f fmt
    Limits the displayed events to those matching fmt.

stats
Prints out statistics about the specified variable. It needs at least two additional parameters. The first one specifies the expected variable type. The second specifies the variable name. Currently, the supported variable types are integer and completion. The first is for 'continuous' values and will be treated as a floating point value. The second is for events that appear in pairs of data constructors with matching arguments. For example, “BeginEvent 4 2” and “EndEvent 4 2”. If the variable takes values of completion type, then there must be two more arguments: one specifying the “opening” constructor and another specifying the “closing” constructor. So in our example those would be BeginEvent and EndEvent, in that order. The command will display appropriate statistics for the chosen value type (if the variable is assigned values of different types, those assignments will be ignored). The user can specify additional flags immediatelly after the expected variable type. Those are:

-p basename
    Generates SVG plots of potentially interesting variable properties. For integer variables, it will plot the value of the variable versus time. For completion variables, it will generate a histogram of the time elapsed between matching Begin and End events. Currently, this will only work if the ploticus program is installed as /usr/local/bin/ploticus. The svg files will all start with basename. In addition, evtranalyze will leave behind the data files used to generate the plots (with the suffix .data replaced for .svg). These files can be used to create new plots with a program of the user's choosing.

svg
Generates an svg file (by default output.svg) in the current directory, displaying the stream events. The flags it accepts are:

-i interval
    Limits the displayed events to those occurring within the specified time interval. The interval is specified in the form [c|m]<num>:<num>. If interval starts with 'c', <num> is absolute (i.e. not relative to the start of the event stream) clock cycles (integral). If interval starts with 'm', <num> is a floating point number specifying milliseconds since the first event in the stream.

-o path
    Specifies an alternate output file.

summary
Displays summary information about the event stream.

EXAMPLES
Firstly, one can generate an event trace as described in ktrdump(8). Assume that our trace is in trace.evtr. Then

    evtranalyze -f trace.evtr summary

will display summary information for the number of events encountered on each processor.

    evtranalyze -f trace.evtr show

will display those events in chronological order, merging event traces from all system cpus.

    evtranalyze -f trace.evtr stats integer varname

will display statistics about the integer variable varname, while

    evtranalyze -f trace.evtr stats completion -p test varname Open Close

displays statistics for completion events (matching Open/Close constructors) on the variable varname and in addition generates appropriate plots in files named ‘test*.svg’.

SEE ALSO
ktrdump(8)

HISTORY
The evtranalyze utility first appeared in DragonFly 2.5.

AUTHORS
-nosplit The evtranalyze utility was implemented by Aggelos Economopoulos <aggelos@dragonflybsd.org> for DragonFly.