The eventlog feature and related tools have been added to OMNeT++ with the aim of helping the user understand complex simulation models and correctly implement the desired component behaviors. Using these tools, one can examine details of recorded history of a simulation, focusing on the behavior instead of the statistical results.
The eventlog file is created automatically during a simulation run upon explicit request configurable in the ini file. The resulting file can be viewed in the OMNeT++ IDE using the Sequence Chart and the Eventlog Table or can be processed by the command line Eventlog Tool. These tools support filtering the collected data to allow you to focus on events relevant to what you are looking for. They allow examining causality relationships and provide filtering based on simulation times, event numbers, modules and messages.
The simulation kernel records into the eventlog among others: user level messages, creation and deletion of modules, gates and connections, scheduling of self messages, sending of messages to other modules either through gates or directly, and processing of messages (that is events). Optionally, detailed message data can also be automatically recorded based on a message filter. The result is an eventlog file which contains detailed information of the simulation run and later can be used for various purposes.
To record an eventlog file during the simulation, insert the following line into the ini file:
record-eventlog = true
The simulation kernel will write the eventlog file during the simulation into the file specified by the following ini file configuration entry (showing the default file name pattern here):
eventlog-file = ${resultdir}/${configname}-${runnumber}.elog
The size of an eventlog file is approximately proportional to the number of events it contains. To reduce the file size and speed up the simulation, it might be useful to record only certain events. The eventlog-recording-intervals configuration option instructs the kernel to record events only in the specified intervals. The syntax is similar to that of vector-recording-intervals.
An example:
eventlog-recording-intervals = ..10.2, 22.2..100, 233.3..
Another factor that affects the size of an eventlog file is the number of modules for which the simulation kernel records events during the simulation. The module-eventlog-recording per-module configuration option instructs the kernel to record only the events that occurred in the matching modules. The default is to record events from all modules. This configuration option only applies to simple modules.
The following example records events from any of the routers whose index is between 10 and 20, and turns off recording for all other modules.
**.router[10..20].**.module-eventlog-recording = true **.module-eventlog-recording = false
Since recording message data dramatically increases the size of the eventlog file and also slows down the simulation, it is turned off by default, even if writing the eventlog is enabled. To turn on message data recording, supply a value for the eventlog-message-detail-pattern option in the ini file.
An example configuration for an IEEE 80211 model that records the encapsulationMsg field and all other fields whose name ends in Address, from messages whose class name ends in Frame looks like this:
eventlog-message-detail-pattern = *Frame:encapsulatedMsg,*Address
An example configuration for a TCP/IP model that records the port and address fields in all network packets looks like the following:
eventlog-message-detail-pattern = PPPFrame:encapsulatedPacket|IPDatagram:encapsulatedPacket,*Address|TCPSegment:*Port
%
% eventlog-message-detail-pattern = WirelessFrame:declaredOn(WirelessFrame) or bitLength %
The Eventlog Tool is a command line tool to process eventlog files. Invoking it without parameters will display usage information. The following are the most useful commands for users.
The eventlog tool provides off line filtering that is usually applied to the eventlog file after the simulation has been finished and before actually opening it in the OMNeT++ IDE or processing it by any other means. Use the filter command and its various options to specify what should be present in the result file.
Since the eventlog file format is text based and users are encouraged to implement their own filters, a way is needed to check whether an eventlog file is correct. The echo command provides a way to check this and help users creating custom filters. Anything not echoed back by the eventlog tool will not be taken into consideration by the other tools found in the OMNeT++ IDE.