source: tools/tracertstats/tracertstats.1

.TH TRACERTSTATS "1" "November 2006" "tracertstats (libtrace)" "User Commands"
.SH NAME
tracertstats \- perform simple filter based analysis on a trace
.SH SYNOPSIS
.B tracertstats 
[ -f | --filter bpf ]
[ -i | --interval interval ]
[ -t | --threads max ]
[ -c | --count count ]
[ -o | --output-format csv,txt,png,html ]
[ -m | --merge-inputs ]
[ -N | --nobuffer ]
[ -d | --report-drops ]
inputuri...
.P
.B tracertstats 
-H|--libtrace-help
.SH DESCRPTION
tracertstats takes a list of bpf expressions and outputs the number of packets
and bytes that match that expression every interval seconds, or count packets.
.TP
.PD 0
.BI \-f " bpf-filter"
.TP
.PD
.BI \-\^\-filter " bpf-filter"
Add another "bpf filter"

.TP
.PD 0
.BI \-i " interval"
.TP
.PD
.BI \-\^\-interval " interval"
Output results every \fIinterval\fR seconds.

.TP
.PD 0
.BI \-t " max"
.TP
.PD
.BI \-\^\-threads " max"
Use \fImax\fR packet processing threads. The default is 4 threads, but adding
more or less threads may improve performance.

.TP
.PD 0
.BI \-c " count"
.TP
.PD
.BI \-\^\-count " count"
Stop after processing this amount of packets. Note that this is only a
lower bound as this is only evaluated once per thread per interval.

.TP
.PD 0
.BI \-m 
.TP
.PD
.BI \-\^\-merge-inputs
Treats all inputs as a single input, resulting a single unified output rather
than an output for each input. Works best with traces that are consecutive to
create a single CSV, for instance.

.TP
.PD 0
.BI \-N
.TP
.PD
.BI \-\^\-nobuffer
Disable internal packet buffering in libtrace. If the packet rate is very low
(i.e. < 10 packets per interval), set this to ensure that tracertstats is more
likely to print results in time with the interval rather than producing bursts
of output for multiple intervals at a time.

.TP
.PD 0
.BI \-d
.TP
.PD
.BI \-\^\-report-drops
Include columns with the number of packets that were either dropped by the
capture process or went missing between the capture process and this
tracertstats instance. The numbers displayed are CUMULATIVE, as they are
pulled directly from the libtrace statistics API.

.TP
.PD 0
.BI \-o " format"
.TP
.PD
.BI \-\^\-output\-format " format"
Selects the output format.

.RS
.TP
txt
Human readable text.  This is the default output format which provides output
easily understood by a human.  This format has the disadvantage that it takes
up quite a bit of horizontal space.

.TP
csv
Comma Seperated Values. This is suitable for further analysis in a spreadsheet,
or other program.

.TP
png
PNG Graphic.  Produces a fairly incomprehensible png graph.  This relies on
gdc being available at compile time.

.TP
html
This produces output suitable for display to a human in a webbrowser.

.SH EXAMPLES
.nf
tracertstats \-\^\-filter 'host sundown' \\
        \-\^\-filter 'port http' \\
        \-\^\-filter 'port ftp or ftp-data' \\
        \-\^\-filter 'port smtp' \\
        \-\^\-filter 'tcp[tcpflags] & tcp-syn!=0' \\
        \-\^\-filter 'not ip' \\
        \-\^\-filter 'ether[0] & 1 == 1' \\
        \-\^\-filter 'icmp[icmptype] == icmp-unreach' \\
        \-\^\-output\-format html
        erf:/traces/trace1.gz \\
        erf:/traces/trace2.gz 
.fi

.SH LINKS
More details about tracertstats (and libtrace) can be found at
http://www.wand.net.nz/trac/libtrace/wiki/UserDocumentation

.SH SEE ALSO
libtrace(3), tracemerge(1), tracesplit(1), tracesplit_dir(1), tracefilter(1), 
traceconvert(1), tracereport(1), tracepktdump(1), traceanon(1), tracesummary(1),
traceconvert(1), tracereplay(1), tracediff(1), traceends(1), tracetopends(1)

.SH AUTHORS
Perry Lorier <perry@cs.waikato.ac.nz>