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.