
=head1 NAME

sample-summary.pod - An annotated version of t/sample_output/sample.csv

=head1 SYNOPSIS

This is an annotated version of F<t/sample_output/sample.csv>, the
sample summary file generated by L<Net::Traces::TSH|Net::Traces::TSH>
after processing F<t/sample_input/sample.tsh> (see also
F<t/process_trace.t>).

=head1 DESCRIPTION 

The following sections explain the contents of the comma separated
values (CSV) file F<t/sample_output/sample.csv>.

=head2 General Trace Information

This section contains the trace filename, date, duration (in seconds),
and the number of records it contains.  The date is calculated from
the timestamp, usually part of the filename.  Since the trace filename
(F<sample.tsh>) does not contain a timestamp, "Unknown" is displayed. 

 Filename,t/sample_input/sample.tsh,Unknown
 Duration,0.937457
 Records,1000
 Number of Interfaces,2
 Link Capacity,155520000

If the trace filename was F<AIX-1072917725-1.csv>, instead of
F<sample.tsh>, then first line would have been

 Filename,AIX-1072917725-1.csv,Thu Jan 1 00:42:05 2004 GMT

=head2 Interface Information and Traffic Density

These two sections are present only in per-interface summary files
(see t/sample_output/sample.if-1.csv and
t/sample_output/sample.if-2.csv. The first section,

 INTERFACE INFORMATION
 Interface Number,1
 Duration,0.937457
 Records,673

provides information similar to the general trace described above.

The second section, below, presents the number of packets per second,
bytes per packet, and bits per second for IP and TCP for this
particular interface:

 INTERFACE TRAFFIC DENSITY
 ,Pkts/s,Bytes/Pkt,b/s
 IP Total,718,230,1323231
 TCP Total,596,234,1117338

=head2 Traffic Statistics

The next two sections present the tally of packets and bytes,
respectively, for IP and each transport present in the trace. We keep
counts of the total packets/bytes, the number of packets/bytes with
the DF (don't fragment) bit set, the MF (more fragments) bit set, the
packets/bytes from ECN-aware connections (ECT and CE), and traffic
requesting differentiated services (DiffServ - Normal, Class Selector,
Assured Forwarding, Expedited Forwarding).  We also count the number
of packets/bytes that carry IP options.

 IP STATISTICS (PACKETS)
 ,,Fragmentation,,Explicit Congestion Notification,,Differentiated Services,,,,IP Options
 ,Total ,DF ,MF ,ECT ,CE ,Normal ,Class Selector ,AF PHB ,EF PHB ,No IP Options ,IP Options 
 IP,1000,895,0,0,0,1000,0,0,0,1000,0
 ICMP,22,6,0,0,0,22,0,0,0,22,0
 TCP,842,829,0,0,0,842,0,0,0,842,0
 UDP,133,60,0,0,0,133,0,0,0,133,0
 Unknown,3,0,0,0,0,3,0,0,0,3,0

It can be seen that the transport protocols present in this small
trace are ICMP, TCP, UDP, and some other "unknown".  No packets belong
to ECN-aware traffic.  All packets ask for "normal" delivery (best
effort, no DiffServ) and no packets carry IP options.

 IP STATISTICS (BYTES)
 ,,Fragmentation,,Explicit Congestion Notification,,Differentiated Services,,,,IP Options
 ,Total ,DF ,MF ,ECT ,CE ,Normal ,Class Selector ,AF PHB ,EF PHB ,No IP Options ,IP Options 
 IP,356422,340088,0,0,0,356422,0,0,0,356422,0
 ICMP,1700,336,0,0,0,1700,0,0,0,1700,0
 TCP,326308,325656,0,0,0,326308,0,0,0,326308,0
 UDP,28198,14096,0,0,0,28198,0,0,0,28198,0
 Unknown,216,0,0,0,0,216,0,0,0,216,0


=head2 TCP Acknowledgements

This section presents how TCP receivers acknowledge segments.

 Total ACKs,576
 Cumulative ACKs,506
 Pure ACKs,151
 Options ACKs,70

Note that

 Total ACKs = Cumulative ACKs + Options ACKs

and

 Pure ACKs <= Cumulative ACKs

"Pure ACKs" are just this: 40-byte TCP segments with the ACK bit set
and no options or payload.  "Options ACKs" are acknowledgements that
carry some TCP options, such as SACK blocks or timestamps, and may
carry a payload.

=head2 (TCP) Receiver Advertised Window

This section presents counts of the receiver advertised window
recorded in the TCP header of a SYN or a SYN/ACK segment. The "hard
count" includes only 40-byte SYN(/ACK)s. The "soft count" includes all
SYN and SYN/ACK segments regardless of size. The issue with the "soft
count" is that it may include SYN(/ACK)s that feature a window scale
factor. That is, the value read in the receiver advertised window
field of the TCP header may be the much less than the actually
advertised window.

 Size (Bytes),Soft Count,Hard Count
 5840,4,0
 8192,2,0
 8760,42,0
 10767,1,0
 16384,85,0
 17019,1,0
 24616,3,0
 24820,5,0
 25200,2,0
 32000,1,0
 34932,1,0
 44620,1,0
 46080,1,0
 46424,0,1
 49640,1,0
 60015,1,0
 60352,2,0
 64170,1,0
 64240,42,0
 64512,24,0
 64800,1,0
 65280,5,0
 65535,46,0

For example, 46 SYN(/ACK)s carry a receiver advertised window of 65535
bytes. All 46 of them carry some TCP options, because the "hard count"
is empty, that is, 0.  We have only one case where we actually find a
"hard count" value: a peer advertising a receiver window of 46424
bytes.

=head2 TCP Options Negotiation

This section presents counts of the SYN and SYN/ACK segments and their
respective TCP header length. We can use this information to quantify
TCP options deployment. A TCP header length of 20 bytes means that the
SYN(/ACK) carried no options.

 TCP Header Length (Bytes),SYN,SYN/ACK
 20,0,1
 24,2,0
 28,252,1
 32,2,4
 40,3,0
 44,5,3
 SYN/Payload,0

The last line (SYN/Payload) shows how many SYN(/ACK)s carry a payload
(in this case, none).

=head2 TCP Options ACK Usage

This section details the "Options ACKs" L<above|"TCP
Acknowledgements">, presenting the TCP header length of the ACKs
carrying some TCP option(s).

 TCP Header Length (Bytes),Count
 28,1
 32,63
 40,1
 44,5

=head2 Packet Size Distribution

The last section presents the "protocol-packet count" matrix,
essentially a set of histograms of the total packet sizes for IP and
each transport protocol in the trace (in this case, ICMP, TCP, UDP,
and Unknown).

 Bytes,IP,ICMP,TCP,UDP,Unknown
 38,1,0,0,1,0
 39,1,0,0,1,0
 40,160,0,153,7,0
 41,4,0,4,0,0
 43,2,0,0,2,0
 44,3,0,3,0,0
 45,3,0,0,3,0
 46,3,0,2,1,0
 48,305,0,305,0,0
 52,48,0,48,0,0
 53,3,0,0,3,0
 56,14,9,4,1,0
 57,1,0,1,0,0
 58,1,0,1,0,0
 60,5,0,4,1,0
 63,3,0,1,2,0
 64,11,0,10,1,0
 65,2,0,1,1,0
 66,2,0,1,1,0
 68,1,0,1,0,0
 70,2,0,0,2,0
 71,2,0,0,2,0
 72,7,0,0,4,3
 74,9,0,0,9,0
 75,6,0,0,6,0
 76,1,0,1,0,0
 78,1,0,0,1,0
 79,1,0,1,0,0
 80,1,0,1,0,0
 82,2,0,0,2,0
 84,4,0,3,1,0
 86,1,0,1,0,0
 88,12,0,12,0,0
 90,1,0,1,0,0
 92,13,13,0,0,0
 95,1,0,0,1,0
 96,2,0,2,0,0
 97,1,0,1,0,0
 98,1,0,1,0,0
 99,1,0,1,0,0
 101,1,0,1,0,0
 102,3,0,1,2,0
 108,2,0,1,1,0
 110,1,0,1,0,0
 112,1,0,1,0,0
 113,1,0,1,0,0
 114,1,0,0,1,0
 115,1,0,0,1,0
 120,4,0,0,4,0
 130,1,0,0,1,0
 138,2,0,0,2,0
 139,1,0,1,0,0
 141,1,0,0,1,0
 145,1,0,1,0,0
 146,1,0,0,1,0
 147,1,0,0,1,0
 149,1,0,0,1,0
 151,2,0,0,2,0
 164,2,0,0,2,0
 168,1,0,1,0,0
 178,1,0,0,1,0
 181,1,0,0,1,0
 182,4,0,1,3,0
 183,1,0,0,1,0
 184,1,0,0,1,0
 186,1,0,1,0,0
 188,1,0,0,1,0
 195,1,0,0,1,0
 199,3,0,0,3,0
 211,3,0,0,3,0
 217,1,0,0,1,0
 228,1,0,1,0,0
 234,2,0,0,2,0
 249,1,0,0,1,0
 254,1,0,0,1,0
 263,1,0,0,1,0
 265,1,0,0,1,0
 266,1,0,0,1,0
 267,1,0,1,0,0
 325,1,0,0,1,0
 330,2,0,2,0,0
 333,2,0,0,2,0
 339,1,0,0,1,0
 341,1,0,0,1,0
 343,1,0,0,1,0
 345,2,0,0,2,0
 354,1,0,0,1,0
 377,1,0,1,0,0
 404,12,0,0,12,0
 445,1,0,0,1,0
 472,1,0,1,0,0
 476,1,0,1,0,0
 488,1,0,1,0,0
 500,1,0,1,0,0
 504,1,0,1,0,0
 506,1,0,0,1,0
 512,1,0,0,1,0
 518,1,0,1,0,0
 521,1,0,0,1,0
 538,2,0,0,2,0
 632,1,0,1,0,0
 638,8,0,0,8,0
 647,2,0,0,2,0
 660,28,0,28,0,0
 680,1,0,1,0,0
 684,1,0,1,0,0
 706,21,0,21,0,0
 708,25,0,25,0,0
 712,1,0,1,0,0
 728,19,0,19,0,0
 920,1,0,1,0,0
 952,1,0,1,0,0
 999,1,0,1,0,0
 1000,1,0,1,0,0
 1020,1,0,1,0,0
 1039,2,0,2,0,0
 1048,1,0,1,0,0
 1168,1,0,1,0,0
 1273,2,0,2,0,0
 1400,18,0,18,0,0
 1420,66,0,66,0,0
 1427,1,0,1,0,0
 1454,21,0,21,0,0
 1480,6,0,6,0,0
 1492,2,0,2,0,0
 1500,34,0,34,0,0

Note that the largest recorded packet size is 1500 bytes.

=head1 AUTHOR

Kostas Pentikousis, kostas@cpan.org.

=head1 COPYRIGHT

Copyright 2004 by Kostas Pentikousis. All Rights Reserved.

=cut