Logging

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.

Starting logging

This depends on what operating system you are using.

Mac OS X or Windows

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.

Linux and others

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.

Using logging

When NetLogo starts up it will ask for a user name. This name will appear in all the logs generated during this session.

Where logs are stored

Logs are stored in the OS-specific temp directory. On most Unix-like systems that is /tmp. On Windows Vista the logs can be found in c:\Users\<user>\AppData\Local\Temp, where <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 prompt.

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 __delete-log-files.

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 org.nlogo.log.Logger.GLOBALS

<event logger="org.nlogo.log.Logger.GLOBALS"
       timestamp="1177341065988"
       level="INFO"
       type="globals">
   <name>FOO</name>
   <value>51.0</value>
</event>

<event logger="org.nlogo.log.Logger.GREENS"
       timestamp="1177341065988"
       level="INFO"
       type="slider">
  <action>changed</action>
  <name>foo</name>
  <value>51.0</value>
  <parameters>
    <min>0.0</min>
    <max>100.0</max>
    <inc>1.0</inc>
  </parameters>
</event>

<event logger="org.nlogo.log.Logger.CODE"
       timestamp="1177341072208"
       level="INFO"
       type="command center">
  <action>compiled</action>
  <code>crt 1</code>
  <agentType>O</agentType>
   <errorMessage>success</errorMessage>
</event>

<event logger="org.nlogo.log.Logger.WIDGETS"
       timestamp="1177341058351"
       level="INFO"
       type="slider">
  <name></name>
  <action>added</action>
</event>

<event logger="org.nlogo.log.Logger.BUTTONS"
        timestamp="1177341053679"
        level="INFO"
        type="button">
  <name>show 1</name>
  <action>released</action>
  <releaseType>once</releaseType>
</event>

<event logger="org.nlogo.log.Logger.SPEED"
       timestamp="1177341042202"
       level="INFO"
       type="speed">
  <value>0.0</value>
</event>

<event logger="org.nlogo.log.Logger.TURTLES"
       timestamp="1177341094342"
       level="INFO"
       type="turtle">
  <name>turtle 1</name>
  <action>born</action>
  <breed>TURTLES</breed>
</event>

<event logger="org.nlogo.log.Logger.LINKS"
       timestamp="1177341094342"
       level="INFO"
       type="link">
  <name>link 2 7</name>
  <action>born</action>
  <breed>LINKS</breed>
</event>

How to configure the logging output

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 org.nlogo.log.XMLLayout. 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.

Advanced Configuration

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.