NetLogo’s logging facility allows researchers to record student actions for later analysis.
Logging in NetLogo, once initiated, is invisible to the student. The researcher can choose the type of events logged through a configuration file.
NetLogo uses the log4j package for logging. If you have previous experience with this package you’ll find logging in NetLogo familiar.
Logging is supported only by the special NetLogo Logging application.
This depends on what operating system you are using.
There is a special logging launcher in the NetLogo directory called NetLogo Logging. Double click on the icon.
On Windows, the NetLogo directory can be found at
C:\Program Files, unless you
chose a different location when you installed NetLogo.
To enable logging, invoke the
netlogo.sh script as follows:
netlogo.sh --logging netlogo_logging.xml
You could also modify the script to include these flags, or copy the script and modify the copy.
You can replace netlogo_logging.xml with any valid log4j XML configuration file, which will be discussed in more detail later.
When NetLogo starts up it will ask for a user name. This name will appear in all the logs generated during this session.
Logs are stored in the OS-specific temp directory. On most Unix-like systems
/tmp. On Windows Vista the logs can be found in
<user> is the logged in user. On
Mac OS X, the temp directory varies for each user. You can determine your temp
directory by opening the Terminal application and typing
echo $TMPDIR> at the
There are two convenience commands that will help you manage the logs.
__zip-log-files filename will gather all the logs in the temp
directory and put them in one zip file, at the location specified. After doing
__zip-log-files the existing logs are not deleted, you can do so
explicitly by using
The following is a chart describing the name of the loggers available, the type
of events each logs, at what level, and provides a sample output using the
XMLLayout. All the loggers are found in
org.nlogo.log.Logger. When referring
to the loggers in the configuration file you should use the fully qualified
name. So, for example, the logger
GLOBALS would actually be
The default logging configuration (netlogo_logging.xml) looks something like this:
NetLogo defines 8 loggers, all descend directly from the root logger, which
means unless you explicitly set the properties (appender, layout, and output
level) in the configuration they will inherit them from the root. In the default
configuration the root is set to level INFO, the appender is
org.nlogo.log.XMLFileAppender and layout is
Together these generate a nicely formatted XML file as defined in the
netlogo_logging.dtd which is based on the log4j dtd. If the appender is a
FileAppender (including the
XMLFileAppender) a new file is start each time
the user opens a model.
<?xml version="1.0" encoding="UTF-8" ?> <!DOCTYPE log4j:configuration SYSTEM "log4j.dtd"> <log4j:configuration debug="false" xmlns:log4j='http://jakarta.apache.org/log4j/'> <appender name="A1" class="org.nlogo.log.XMLFileAppender"> <layout class="org.nlogo.log.XMLLayout"/> </appender> <category name="org.nlogo.log.Logger.WIDGETS"> <priority value="off" /> </category> <category name="org.nlogo.log.Logger.TURTLES"> <priority value="off" /> </category> <category name="org.nlogo.log.Logger.LINKS"> <priority value="off" /> </category> <root> <priority value ="info" /> <appender-ref ref="A1" /> </root> </log4j:configuration>
This configuration, first defines an appender named “A1” of type XMLFileAppender with an XMLLayout. The appender defines where the logging data goes, in this case the data goes into a file. In fact, if NetLogo is given a FileAppender it will automatically start a new file every time the user opens a new model. The XMLFileAppender also does some formatting and writes the appropriate headers to the file. The layout defines how to write each individual message. Unless you are an advanced user there is no need change (or worry about) the appender or the layout.
At the end of the configuration notice the definition of the root logger. All of the other loggers descend from the root logger and, thus, inherit the properties of the root unless explicitly set. This case is fairly simple, having set up the appender A1 we make that the default appender for the root (and all other loggers) and make the default priority “INFO”. Messages that are logged at the INFO level or higher will be written, messages logged at lower levels will not. Note that with only one exception NetLogo always logs at level INFO. Sets to globals that don’t change the value of the global are logged at level DEBUG. Which means that these messages are disabled by default, since debug is lower level than info. The rest of the body of the configuration file overrides properties of the root logger in a few specific loggers (or categories as they are known in the configuration file, the terms can be assumed to be synonymous for the proposes of this document). That is it turns off the WIDGET, TURTLES, and LINKS loggers, by default. To re-enable them you can changes the priority from off to info, like this:
<category name="org.nlogo.log.Logger.TURTLES"> <priority value="info" /> </category>
or you can simply remove the entire reference to the category from the configuration file, as it is not serving any other purpose.
This is only a basic introduction to configuration files for logging in NetLogo. There are many more configuration options available through the log4j framework. See the log4j documentation.