Index of /tools/traffic-gist

Icon  Name                      Last modified      Size  
[DIR] Parent Directory                               -   
[TXT] ChangeLog                 24-Feb-2011 12:16  682   
[TXT] LICENSE                   23-Sep-2010 09:05  1.4K  
[   ] checksums                 24-Feb-2011 13:33  134   
[   ] traffic-gist-0.1.0.tar.gz 30-Sep-2010 20:37  1.3M  
[   ] traffic-gist-0.2.0.tar.gz 24-Feb-2011 12:47  1.3M  

OVERVIEW
========

Traffic Gist is a network traffic statistics collection tool. Gist can
collect statistics about live traffic and do postmortem packet capture
analysis.  Currently supported protocols are DNS and DHCP.

Please ask questions and file bug reports at https://launchpad.net/gist

Help, including commercial support and development, is available from
The Measurement Factory (http://www.measurement-factory.com/).


BUILDING AND INSTALLING
=======================

    ./configure
    make
    make install


USAGE
=====

Traffic Gist supports two traffic sources: live interface capture and
pcap dump file.

* Capturing traffic from a live interface:

    $ traffic-gist --interface IFACE --duration TIME

    IFACE is a network interface name such as "lo" or "eth0". A special
    value "any" can be given to capture from all available interfaces.
    Capture is done in promiscuous mode.

    TIME sets capture duration such as "5min". After the given amount of
    time, Traffic Gist exits and prints collected statistic. If no
    duration parameter given, Traffic Gist runs until interrupted.

    You may also use the --filter option to detail which packets to
    capture. The default filter when capturing live traffic is:
    "(tcp port domain) or (udp port bootpc or bootps or domain)".

    Note: Capturing from network interfaces requires root permissions.


* Reading from pcap dump file:

    $ traffic-gist --pcap FILENAME

    There is an important difference between live capture (see above)
    and reading a pcap dump file. During live capture, all times are
    measured using the wall clock.  When reading from a pcap dump, all
    times are measured using packet timestamps.

    You may use the --filter option to detail which packets to read. All
    packets are read by default.


STATISTICS
==========

Traffic Gist reports collected statistic right before exit and also upon
receiving a HUP or USR1 signal.

The following statistics are reported:

    - duration: analysis duration

    - packet.count/rate: total number and rate of processed packets

    - *.errors: number of errors in various protocols

    - *.rate.*: min, mean, max and 90th percentile stats for rates

    - *.size.*: min, mean, max and histogram stats for sizes


    - TCP.packet.*: all TCP packets stats
    - TCP.packet.payload.*: TCP packets with payload stats
    - TCP.payload.size.*: TCP packets with payload size stats
    - TCP.connection.*: new TCP connection stats


    - DHCP.request.*: DHCP requests stats

    - DHCP.renewal.*: DHCP renewals stats

    - DHCP.reply.*: DHCP replies stats

    - DHCP.lease.*: DHCP leases stats


    - DNS.query.*: DNS queries stats

    - DNS.query.dynamic_update.*: DNS dynamic update queries stats

    - DNS.query.recursive.*: DNS recursive queries stats

    - DNS.reply.*: DNS replies stats

    - DNS.reply.dynamic_update.*: DNS dynamic update replies stats

    - DNS.reply.zone_transfer.*: DNS zone transfer replies stats

    - DNS.reply.codes.*: total number and rate for specific DNS reply codes

    - DNS.reply.hit.*: DNS hit replies stats

    - DNS.reply.miss.*: DNS miss replies stats

    - DNS.hit.ratio.obj: DNS hit ratio

    - DNS.connection.*: new DNS TCP connection stats

    - DNS.zone_transfer.level.max: maximum concurrent zone transfers level

When capturing from live network, some filtering is done before packets
get to Traffic Gist. Hence, packet.count/rate stats usually do not
include all packets on the wire.

Rate is reported in "events per second" and is measured using fixed time
intervals. Interval duration is set by the --interval option. Default
interval is 5sec. For example, if 10 packets were observed during a
5-second interval, the rate of 2 packets/second is recorded.


* DNS hit ratio calculation

    DNS hit ratio is calculated by comparing the number of recursive
    (RD) queries and the number of from-cache responses to those
    queries. The reported value is imprecise and may be very wrong in
    some environments due to the following heuristics.

    Traffic Gist currently does not match individual queries and
    responses. Instead, any DNS message with the QR, RD and RA flags set
    and the AA flag not set is considered a response to some client
    query.  Messages with no answer RR (e.g., errors and NXDOMAIN) are
    currently ignored.

    Furthermore, we assume that most RRs received from authoritative
    servers have "round" TTL values, and that most from-cache replies
    have not "round" TTLs due to their aging in the cache. After the
    initial filtering described above, the TTLs are used to distinguish
    cache hits from cache misses: If the TTL value of the first answer
    RR is round, the reply is considered to be a hit. Otherwise, it is a
    miss. Currently, "round" is defined as "divisible by 60 seconds".

    These heuristics are likely to change in future.