Logging

NetLogo’s logging facility allows researchers to record student actions for later analysis.

Logging in NetLogo is invisible to the student once initiated. 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.

• Starting logging
• Using logging
• Advanced Configuration

Starting logging

There is a NetLogo preference to enable logging:

• Open NetLogo, then open Preferences from the Tools menu.
• Check the box for Enable Logging: then click OK.
• Restart NetLogo and logging will be enabled.

The setting will remain in effect until it is unchecked and NetLogo is restarted again.

You can also specify the Logging configuration file: to use in the NetLogo Preferences as well. If you leave this value blank, then a default configuration file will be used (see below for more information).

Starting with the command line

You can also enable logging and specify the configuration file to use by using a command line switch on Windows and Linux.

Let’s assume you are running on Linux and you have NetLogo installed in a NetLogo 6.1.1 directory in your home folder. To enable logging, invoke the NetLogo executable like so:

~/NetLogo\ 6.1.1/NetLogo --logging ~/NetLogo\ 6.1.1/app/netlogo_logging.xml

You can replace the path to netlogo_logging.xml with any valid log4j XML configuration file (see below for more information).

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 home directory. On most Unix-like systems that is /home/<username>/. On Windows the logs can be found in C:\Users\<username>\, where <username> is the logged in user. On macOS the usual location is /Users/<username>/.

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.