=pod

=head1 NAME

B<rwcount> - Print traffic summary across time

=head1 SYNOPSIS

  rwcount [--bin-size=SIZE] [--load-scheme=LOADSTYLE]
        [--start-epoch=TIME] [--epoch-slots] [--bin-slots]
        [--skip-zeroes] [--no-titles] [--no-columns]
        [--column-separator=CHAR] [{--delimited | --delimited=CHAR}]
        [--print-filenames] [--copy-input=PATH] [--output-path=PATH]
        [--pager=PAGER_PROG] [--site-config-file=FILENAME]
        [{--legacy-timestamps | --legacy-timestamps=NUM}] [FILES...]

=head1 DESCRIPTION

B<rwcount> summarizes SiLK flow records across time.  It counts the
records in the input stream, and groups their byte and packet totals
into time bins.  B<rwcount> produces textual output with a row for
each bin.

When input files are not specified on the command line, B<rwcount>
will read records from the standard input.

=head1 OPTIONS

Option names may be abbreviated if the abbreviation is unique or is an
exact match for an option.  A parameter to an option may be specified
as B<--arg>=I<param> or B<--arg> I<param>, though the first form is
required for options that take optional parameters.

=over 4

=item B<--bin-size>=I<SIZE>

Denotes the size of each time bin, in seconds; defaults to 30 seconds.

=item B<--load-scheme>=I<LOADSTYLE>

Determines how the duration of each flow is mapped onto the time bins.
I<LOADSTYLE> can be one of the following:

=over 4

=item 0

Assumes the traffic is evenly distributed across the bins that contain
any part of the flow's duration.  For a flow whose duration spans five
bins, each bin's packet- and byte-counts will be incremented with 1/5
of the values for the entire flow.

The traffic is NOT evenly distributed across the flow's duration,
since, when using a bin-size of 30 seconds, a particularly placed
32 second flow will span three bins, and each bin will receive 1/3 of
the flow.  Compare with option B<4>.

=item 1

Assumes all of the traffic occurs in the initial second of the flow's
duration.  For a flow whose duration spans five bins, the first bin's
packet- and byte-counts will be incremented with the values for the
entire flow.

=item 2

Assumes all of the traffic occurs in the last second of the flow's
duration.  For a flow whose duration spans five bins, the fifth bin's
packet- and byte-counts will be incremented with the values for the
entire flow.

=item 3

Assumes all of the traffic occurs in the middle second of the flow's
duration.  For a flow whose duration spans five bins, the third bin's
packet- and byte-counts will be incremented with the values for the
entire flow.

=item 4

Assumes the traffic is evenly distributed during each second that the
flow is active.  For a flow whose duration spans five bins, each bin
will receive a portion of the flow-, packet-, and byte-counts weighted
by the amount of time the flow spent in each bin.

When using 30 second bins, a particularly placed 32 second flow will
add 1/32 of its value to the first and last bins, and 30/32 to the
middle bin.

=back

The default I<LOADSTYLE> is 4.

=item B<--start-epoch>=I<TIME>

Denotes the time to use for the first bin.  I<TIME> may be in UNIX
epoch seconds or in C<YYYY/MM/DD:hh[:mm[:ss]]> format.

=item B<--epoch-slots>

Uses the UNIX epoch time as the label for each bin in the output; the
default is to label each bin with the time in a human-readable format.

=item B<--bin-slots>

Uses the internal bin index as the label for each bin in the output;
the default is to label each bin with the time in a human-readable
format.

=item B<--skip-zeroes>

Disables printing of bins with no traffic.  By default, all bins are
printed.

=item B<--no-titles>

Turns off column titles.  By default, titles are printed.

=item B<--no-columns>

Disables fixed-width columnar output.

=item B<--column-separator>=I<C>

Uses the specified character between columns.  When this switch is not
specified, the default of C<|> is used.

=item B<--delimited>

=item B<--delimited>=I<C>

Runs as if B<--no-columns> B<--column-sep>=I<C> had been specified.
That is, disables fixed-width column output; if character I<C> is
provided, it is used as the delimiter between columns instead of the
default 'B<|>'.

=item B<--print-filenames>

Prints to the standard error the names of input files as they are
opened.

=item B<--copy-input>=I<PATH>

Copy all binary input to the specified file or named pipe.  I<PATH>
can be C<stdout> to print flows to the standard output as long as the
B<--output-path> switch has been used to redirect B<rwcount>'s ASCII
output.

=item B<--output-path>=I<PATH>

Determines where the output of B<rwcount> (ASCII text) is written.  If
this option is not given, output is written to the standard output.

=item B<--pager>=I<PAGER_PROG>

When output is to a terminal, invokes the program I<PAGER_PROG> to
view the output one screen full at a time.  This switch overrides the
SILK_PAGER environment variable, which in turn overrides the PAGER
variable.  If the value of the pager is determined to be the empty
string, no paging will be performed and all output will be printed to
the terminal.

=item B<--site-config-file>=I<FILENAME>

Read the SiLK site configuration from the named file I<FILENAME>.
When this switch is not provided, the location specified by the
C<$SILK_CONFIG_FILE> environment variable is used if that variable is
not empty.  The value of C<$SILK_CONFIG_FILE> should include the name
of the file.  Otherwise, the application looks for a file named
F<silk.conf> in the following directories: the directory specified in
the F<$SILK_DATA_ROOTDIR> environment variable; the data root
directory that is compliled into SiLK (use the B<--version> switch to
view this value); the directories F<$SILK_PATH/share/silk/>,
F<$SILK_PATH/share/>, or F<$SILK_PATH>; or in the F<share/silk/> and
F<share/> directories parallel to the application's directory.

=item B<--legacy-timestamps>

=item B<--legacy-timestamps>=I<NUM>

Specify the format for human readable timestamps, either the new
style, C<I<YYYY>/I<MM>/I<DD>TI<hh>:I<mm>:I<ss>>, or the legacy style,
S<C<I<MM>/I<DD>/I<YYYY> I<hh>:I<mm>:I<ss>>>.  When this switch is not
present, the timestamps will be in the default format, which depends
on how SiLK was compiled (whether SiLK was configured with the
B<--enable-legacy-timestamp> switch).  When this switch is present and
no argument is given, timestamps are in the legacy format.  When an
argument is supplied, timestamps will be in the new format if the
argument begins with 0, and in the old format if the argument begins
with 1.  Any other argument to the switch is an error.

=item B<--delimiter>=I<C>

THIS SWITCH IS DEPRECATED.  Use the B<--column-separator> switch
instead.  Any abbreviation of B<delimiter> will be treated as the
B<delimited> switch.

=back

=head1 EXAMPLES

To count all web traffic on Jan 1, 2003, into 1 hour bins:

  rwfilter --pass=stdout --start-date=2003/01/01:00 \
        --end-date=2003/01/01:24 --proto=6 --aport=80 \
        | rwcount --bin-size=3600
                 Date|       Records|          Bytes|      Packets|
  2003/01/01T00:00:00|      12947.00|     1968190.00|     34312.00|
  2003/01/01T01:00:00|      65318.00|     5783959.00|    100143.00|
  2003/01/01T02:00:00|      13765.00|     1895933.00|     36121.00|
  2003/01/01T03:00:00|      69599.00|     7062388.00|    144130.00|
  2003/01/01T04:00:00|     204717.00|    18491693.00|    385293.00|
  2003/01/01T05:00:00|      18664.00|     2352966.00|     45296.00|
  ....

To force the hourly bins in the previous example to run from 30
minutes past the hour, use the B<--start-epoch> switch:

  rwfilter ...| \
        rwcount --bin-size=3600 --start-epoch=2002/12/31:23:30

=head1 NOTES

B<rwuniq(1)>'s B<--bin-time> switch can do time-binning similar to
what B<rwcount> supports, but B<rwuniq> cannot divide a SiLK record
among multiple bins, i.e., there is no support for a B<--load-factor>
type switch.  Such a feature could greatly increase B<rwuniq>'s
already large memory requirements.


=head1 SEE ALSO

B<rwfilter(1)>, B<rwuniq(1)>

=cut

$SiLK: rwcount.pod 8269 2007-08-03 18:54:48Z mthomas $

Local Variables:
mode:text
indent-tabs-mode:nil
End: