1.\"- 2.\" Copyright (c) 2009-10 Aggelos Economopoulos 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" 27.Dd June 13, 2010 28.Dt EVTRANALYZE 1 29.Os 30.Sh NAME 31.Nm evtranalyze 32.Nd analyze a trace stream 33.Sh SYNOPSIS 34.Nm 35.Op Fl f Ar infile 36.Ar command 37.Op Ar argument ... 38.Sh DESCRIPTION 39The 40.Nm 41utility is used to analyze an event trace stream. 42It takes a few global options, after which the user should 43specify a subcommand, followed by the subcommands options. 44.Ss Global options 45The global options are 46.Bl -tag -width indent 47.It Fl f Ar path 48Specifies the file containing the event stream. 49.El 50.Pp 51The subcommands are: 52.Bl -ohang 53.\" ==== show ==== 54.It Cm show 55Lists the individual events, one per line. 56The timestamps are relative to the previous event. 57The flags it accepts are: 58.Bl -tag -width indent-two 59.It Fl f Ar fmt 60Limits the displayed events to those matching 61.Ar fmt . 62.El 63.\" ==== stats ==== 64.It Cm stats 65Prints out statistics about the specified variable. 66It needs at least two additional parameters. 67The first one specifies the expected variable type. 68The second specifies the variable name. 69Currently, the supported variable types are 70.Ar integer 71and 72.Ar completion . 73The first is for 'continuous' values and will be treated as a floating 74point value. 75The second is for events that appear in pairs of data constructors with 76matching arguments. 77For example, 78.Dq BeginEvent 4 2 79and 80.Dq EndEvent 4 2 . 81If the variable takes values of 82.Ar completion 83type, then there must be two more arguments: one specifying the 84.Dq opening 85constructor and another specifying the 86.Dq closing 87constructor. 88So in our example those would be BeginEvent and EndEvent, in that order. 89The command will display appropriate statistics for the chosen value type 90(if the variable is assigned values of different types, those assignments 91will be ignored). 92The user can specify additional flags immediatelly after the expected 93variable type. Those are: 94.Bl -tag -width indent-two 95.It Fl p Ar basename 96Generates SVG plots of potentially interesting variable properties. 97For integer variables, it will plot the value of the variable versus time. 98For completion variables, it will generate a histogram of the time elapsed 99between matching Begin and End events. 100Currently, this will only work if the ploticus program is installed as 101.Pa /usr/local/bin/ploticus . 102The svg files will all start with 103.Ar basename . 104In addition, 105.Nm 106will leave behind the data files used to generate the plots (with the 107suffix 108.Pa .data 109replaced for 110.Pa .svg ) . 111These files can be used to create new plots with a program of the user's 112choosing. 113.El 114.\" ==== svg ==== 115.It Cm svg 116Generates an svg file (by default 117.Pa output.svg ) 118in the current directory, displaying the stream events. 119The flags it accepts are: 120.Bl -tag -width indent-two 121.It Fl i Ar interval 122Limits the displayed events to those occurring within the 123specified time interval. 124The interval is specified in the form [c|m]<num>:<num>. 125If 126.Ar interval 127starts with 'c', <num> is absolute (i.e. not relative to the start of the 128event stream) clock cycles (integral). 129If 130.Ar interval 131starts with 'm', <num> is a floating point number specifying milliseconds 132since the first event in the stream. 133.It Fl o Ar path 134Specifies an alternate output file. 135.El 136.\" ==== summary ==== 137.It Cm summary 138Displays summary information about the event stream. 139.El 140.Sh EXAMPLES 141Firstly, one can generate an event trace as described in 142.Xr ktrdump 8 . 143Assume that our trace is in 144.Pa trace.evtr . 145Then 146.Bd -literal -offset indent 147evtranalyze -f trace.evtr summary 148.Ed 149.Pp 150will display summary information for the number of events encountered 151on each processor. 152.Bd -literal -offset indent 153evtranalyze -f trace.evtr show 154.Ed 155.Pp 156will display those events in chronological order, merging event traces 157from all system cpus. 158.Bd -literal -offset indent 159evtranalyze -f trace.evtr stats integer varname 160.Ed 161.Pp 162will display statistics about the integer variable 163.Ar varname , 164while 165.Bd -literal -offset indent 166evtranalyze -f trace.evtr stats completion -p test varname Open Close 167.Ed 168.Pp 169displays statistics for completion events (matching Open/Close constructors) 170on the variable 171.Ar varname 172and in addition generates appropriate plots in files named 173.Sq Pa test*.svg . 174.Sh SEE ALSO 175.Xr ktrdump 8 176.Sh HISTORY 177The 178.Nm 179utility first appeared in 180.Dx 2.5 . 181.Sh AUTHORS 182.An -nosplit 183The 184.Nm 185utility was implemented by 186.An Aggelos Economopoulos Aq Mt aggelos@dragonflybsd.org 187for 188.Dx . 189