Eventlog¶

Introduction¶

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. By using these tools, one can examine the details of the recorded history of a simulation, focusing on the behavior rather than the statistical results.

The eventlog file is created automatically during a simulation run upon explicit request, which can be configured in the ini file. The resulting file can be viewed in the OMNeT++ IDE using the Sequence Chart and the Eventlog Table, or it can be processed by the command line Eventlog Tool. These tools support filtering the collected data to allow you to focus on events that are 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, among other things, 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 that contains detailed information of the simulation run and can later be used for various purposes.

Configuration¶

To record an eventlog file during the simulation, insert the following line into the ini file:

record-eventlog = true

File Name¶

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

Recording Intervals¶

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..

Recording Modules¶

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

Recording Message Data¶

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 with 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 Tool¶

The Eventlog Tool is a command-line tool for processing eventlog files. Invoking it without parameters will display usage information. The following are the most useful commands for users.

Filter¶

The eventlog tool provides offline filtering that is usually applied to the eventlog file after the simulation has 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.

Echo¶

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 helps users create 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.