NAME
    Net::Traces::SSFNet - Analyze traces generated by SSFNet

SYNOPSIS
     use Net::Traces::SSFNet qw( droptail_record_player droptail_record_plotter );

     $Net::Traces::SSFNet::PRINT_EXACT_DECIMAL_DIGITS = 0;
     $Net::Traces::SSFNet::SHOW_SOURCES = 1;
     $Net::Traces::SSFNet::SHOW_STATS = 0;

     # Use with traces created by either
     # SSF.Net.droptailQueueMonitor_1 or SSF.Net.droptailQueueMonitor_2
     #
     droptail_record_player('q.trace', 'text.output', 'some_stream_id.0');

     # Use with traces created by SSF.Net.droptailQueueMonitor_1
     #
     droptail_record_plotter('q.trace', 'some_stream_id.0', 'drops', 'pkts', 'av_qlen');

     # Use with traces created by SSF.Net.droptailQueueMonitor_2
     #
     droptail_record_plotter('q.trace', 'some_stream_id.0', 'drops', 'pkts', 'sumpkts', 'sumdrops');

ABSTRACT
    Net::Traces::SSFNet can analyze traces created by Scalable Simulator
    Framework Network Models. It efficiently emulates in Perl the
    functionality provided by Java-based, SSFNet-bundled trace analyzers,
    and adds new features, including allowing for finer granularity in the
    processed output.

INSTALLATION
    See perlmodinstall.

DESCRIPTION
    SSF, the Scalable Simulation Framework, is a public-domain standard for
    discrete-event simulation of large, complex systems in Java and C++.
    SSFNet is a collection of models used for simulating telecommunication
    networks. The main goal of this module to ease the analysis of traces
    produced by SSFNet.

    Net::Traces::SSFNet version 0.02 can analyze traces generated by
    SSF.Net.droptailQueueMonitor_1 and SSF.Net.droptailQueueMonitor_2.

  Analyzing SSF.Net.droptailQueueMonitor traces
    Net::Traces::SSFNet can analyze traces created by
    SSF.Net.droptailQueueMonitor_1 and SSF.Net.droptailQueueMonitor_2,
    effectively replicating the functionality of
    SSF.Net.droptailRecordPlayer_1 and SSF.Net.droptailRecordPlayer_2.

    To replicate the functionality of either

     java SSF.Net.droptailRecordPlayer_1 qlog.0 some_stream_id.0

    or

     java SSF.Net.droptailRecordPlayer_2 qlog.0 some_stream_id.0

    use the following code:

     use Net::Traces::SSFNet qw( droptail_record_player );

     $Net::Traces::SSFNet::PRINT_EXACT_DECIMAL_DIGITS = 0;
     droptail_record_player( 'qlog.0', *STDOUT, 'some_stream_id.0');

    Notice that you do not have to specify what kind of records are
    contained in the trace. In fact, a trace may contain records created
    from both SSF.Net.droptailQueueMonitor's.

  Finer granularity
    Although both SSF.Net.droptailQueueMonitor's capture simulation events
    using 64-bit "double"s, the SSFNet-bundled trace processing utilities
    (SSF.Net.droptailRecordPlayer_1 and SSF.Net.droptailRecordPlayer_2) use
    3 decimal digits when generating the processed output. Consequently, the
    text output is limited to millisecond granularity.

    This can be an issue when events occur in sub-millisecond intervals: the
    original SSFNet record players do not carry this information in the text
    output. The following example might make the issue more clear. Remember
    that each node in a network graph is uniquely identified via a *Network,
    Host, Interface* (NHI) string (see
    http://www.ssfnet.org/InternetDocs/ssfnetDMLReference.html#addresses).
    Suppose that NHI 4(0) is sampled every 0.1 ms and NHI 4(1) every 1 ms.
    When SSF.Net.droptailRecordPlayer_2 processes the trace file, it will
    generate something like this

     50.805 4(0) sumpkts 186 sumdrops 0 pkts 0 drops 0
     50.805 4(0) sumpkts 187 sumdrops 0 pkts 1 drops 0
     50.805 4(0) sumpkts 187 sumdrops 0 pkts 0 drops 0
     50.805 4(0) sumpkts 187 sumdrops 0 pkts 0 drops 0
     50.806 4(0) sumpkts 188 sumdrops 0 pkts 1 drops 0
     50.806 4(0) sumpkts 188 sumdrops 0 pkts 0 drops 0
     50.806 4(0) sumpkts 189 sumdrops 0 pkts 1 drops 0
     50.806 4(0) sumpkts 189 sumdrops 0 pkts 0 drops 0
     50.806 4(0) sumpkts 190 sumdrops 0 pkts 1 drops 0
     50.806 4(1) sumpkts 51 sumdrops 0 pkts 0 drops 0

    while droptail_record_player() will generate

     50.8051 4(0) sumpkts 186 sumdrops 0 pkts 0 drops 0
     50.8052 4(0) sumpkts 187 sumdrops 0 pkts 1 drops 0
     50.8053 4(0) sumpkts 187 sumdrops 0 pkts 0 drops 0
     50.8054 4(0) sumpkts 187 sumdrops 0 pkts 0 drops 0
     50.8055 4(0) sumpkts 188 sumdrops 0 pkts 1 drops 0
     50.8056 4(0) sumpkts 188 sumdrops 0 pkts 0 drops 0
     50.8057 4(0) sumpkts 189 sumdrops 0 pkts 1 drops 0
     50.8058 4(0) sumpkts 189 sumdrops 0 pkts 0 drops 0
     50.8059 4(0) sumpkts 190 sumdrops 0 pkts 1 drops 0
     50.806 4(1) sumpkts 51 sumdrops 0 pkts 0 drops 0

    provided that "$PRINT_EXACT_DECIMAL_DIGITS" is set.

  Improved Performance
    droptail_record_player() processes a queue trace generated by either
    SSF.Net.droptailQueueMonitor_1 or SSF.Net.droptailQueueMonitor_2
    significantly faster that SSF.Net.droptailRecordPlayer_1 or
    SSF.Net.droptailRecordPlayer_2, respectively.

  Additional functionality
    Use droptail_record_plotter() to process a queue trace and generate text
    files ready for plotting using *gnuplot*, *xgraph*, or even a
    spreadsheet application.

VARIABLES
    Net::Traces::SSFNet uses the following variables to control information
    generation. None is exported.

  $PRINT_EXACT_DECIMAL_DIGITS
    This variable is set by default in order to achieve finer granularity in
    the processed output. If you want to mimic the behavior of
    SSF.Net.droptailRecordPlayer_1 and SSF.Net.droptailRecordPlayer_2 use

     $Net::Traces::SSFNet::PRINT_EXACT_DECIMAL_DIGITS = 0;

  $SHOW_SOURCES
    If $SHOW_SOURCES is set, droptail_record_player() and
    droptail_record_plotter() print to STDERR the types of records and
    traffic sources (NHI) found in the trace. For example, you may see
    something like this:

     Trace contains records from NHI 4(2)
     Trace contains records of type "SSF.Net.QueueRecord_2"
     Trace contains records from NHI 4(1)
     Trace contains records from NHI 4(0)

    By default, no such information is sent to STDERR.

  $SHOW_STATS
    If $SHOW_STATS is set, droptail_record_player() and
    droptail_record_plotter() display trace processing statistics on STDERR.
    For example, you may see something like this:

     {Player processed 113776 records, 1820393 bytes in 7.05 seconds (252 KB/s)}

    This variable is set by default. If you want to suppress displaying the
    statistics use

     $Net::Traces::SSFNet::SHOW_STATS = 0;

FUNCTIONS
  droptail_assert_input
     droptail_assert_input LIST

    This function asserts that the input FILEHANDLE is valid and open before
    the real trace processing begins processing. LIST is expected to have up
    to two elements: IN and STREAM_ID. The queue trace IN may be either an
    open FILEHANDLE or a *filename*. STREAM_ID, if specified, must match the
    stream ID encoded in the queue trace file.

    droptail_assert_input() verifies that IN is open for reading and
    includes a valid preamble. If IN is not specified, it defaults to STDIN.

    droptail_assert_input() returns a list containing the input FILEHANDLE,
    and the actual stream ID found in the queue trace file.

  droptail_assert_output
     droptail_assert_output FILEHANDLE
     droptail_assert_output filename
     droptail_assert_output

    This function returns a valid and open output FILEHANDLE. If FILEHANDLE
    is open, it is returned as-is. If a *filename* is provided instead, this
    function attempts to open and return a filehandle to it. If neither a
    FILEHANDLE nor a *filename* is provided, the returned FILEHANDLE
    defaults to STDOUT.

  droptail_record_player
     droptail_record_player LIST

    This function processes binary traces generated by
    SSF.Net.droptailQueueMonitor_1 and SSF.Net.droptailQueueMonitor_2,
    generates text output based on the contents of the binary trace, and
    returns the number of records processed. In addition to seamlessly
    emulating the functionality of SSF.Net.droptailRecordPlayer_1 and
    SSF.Net.droptailRecordPlayer_2, droptail_record_player() can deal with
    traces that contain a mix of records from both types of
    droptailQueueMonitor's.

    LIST is expected to have up to three elements: IN, OUT, and STREAM_ID.
    IN and OUT may be either an open FILEHANDLE or a *filename*. STREAM_ID,
    if specified, must match the stream ID encoded in the queue trace file.
    LIST is asserted via droptail_assert_input() and
    droptail_assert_output().

    A record created from SSF.Net.droptailQueueMonitor_1 will generate a
    line like this in OUT

     6.01 4(1) pkts 7 drops 0 av_qlen 5.73492479324341

    where "6.01" is the simulation time when the queue at NHI "4(1)" was
    sampled. Since the last time the queue was sampled, 7 packets were
    enqueued, 0 were dropped, and the average number of bytes buffered
    during this interval was 5.73492479324341.

    Similarly, a record created from SSF.Net.droptailQueueMonitor_2 will
    generate a line like this

     99.1 4(2) sumpkts 55 sumdrops 0 pkts 0 drops 0

    where "99.1" is the simulation time when the queue at NHI "4(2)" was
    sampled. Since the beginning of the simulation, this interface has
    enqueued a total of 55 packets and has dropped none. Since the last time
    the queue was sampled, 0 packets were enqueued and 0 were dropped.

  droptail_record_plotter
     droptail_record_plotter LIST

    This function processes binary traces generated by
    SSF.Net.droptailQueueMonitor_1 and SSF.Net.droptailQueueMonitor_2, and
    generates text files suitable for plotting using, for example,
    *gnuplot*. It returns the number of records processed.

    LIST should start with an open FILEHANDLE or a *filename*, followed by a
    STREAM_ID, which must match the stream ID encoded in the queue trace
    file. This part of the LIST is asserted via droptail_assert_input().

    Following these two elements droptail_record_plotter() expects to see at
    least one of the following strings: 'pkts, 'drops', 'sumpkts',
    'sumdrops', and 'av_qlen'. For each of these strings and each source NHI
    found in the trace, droptail_record_plotter() creates a text file in the
    *current working directory*. For example, if a trace file includes
    records from two NHIs, 2(0) and 2(1), the following call

     droptail_record_plotter( 'qlog.0', 'some_stream_id.0', 'drops', 'pkts');

    will create 4 files: "2(0).pkts", "2(0).drops", "2(1).pkts", and
    "2(1).drops". Each of these files has two columns: the first one is the
    simulation time; the second is the value of the respective metric.

    Notice that you do not have to specify what kind of records are
    contained in the trace. In fact, a trace may contain records created
    from both SSF.Net.droptailQueueMonitor's.

DEPENDENCIES
    None.

EXPORTS
    None by default.

  Exportable
    droptail_assert_input(), droptail_assert_output(),
    droptail_record_player(), droptail_record_plotter().

CAVEATS
    Binary Queue Traces This module reads "float"s, "double"s, "int"s, and
    "long"s generated by Java code and stored in a *binary* file. It works
    fine with binary files created with J2SE 1.4.1 on GNU/Linux and Solaris
    2.6.

VERSION
    This is "Net::Traces::SSFNet" version 0.02.

SEE ALSO
    The Scalable Simulator Framework web site at http://www.ssfnet.org

AUTHOR
    Kostas Pentikousis, kostas@cpan.org

COPYRIGHT AND LICENSE
    Copyright 2003 by Kostas Pentikousis. All Rights Reserved.

    This library is free software with ABSOLUTELY NO WARRANTY. You can
    redistribute it and/or modify it under the same terms as Perl itself.