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.