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 the NetLogo preferences or by using a custom command line switch to start NetLogo.

In NetLogo version 6.2.2 and earlier, log4j was the library used and the logging output was in XML format. See the documentation for that prior version if you’re not on the latest NetLogo release.

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 Directory to store logs: in the NetLogo Preferences. If you leave this value blank with logging enabled the default location of the user’s home directory will be used. See below for more information on the default location.

You can also specify the Events to log: in the NetLogo Preferences. This is a comma-separate list of the event names or “shortcut” names. If you leave this value blank with logging enabled a set of default events will be logged. See below for more information on the event names and what the defaults are.

Command Line Switches

You can also enable logging and set the log directory and log events with command line switches. If you specify either the --log-directory or --log-events switch, then logging will be enabled and the switch values will override any preferences set in the NetLogo UI.

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

~/NetLogo\ 6.2.3/NetLogo --log-directory ~/NetLogoLogs/ --log-events "default, ticks, globals"

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.

Events

Below are all of the events that can be logged with the logging app. By default all of these events are logged except “global”, “link”, “tick”, and “turtle” since they can cause a large number of log entries to be created.

• button - button widget presses
• chooser - chooser widget changes
• comment - any user comments, currently only generated for compiler errors
• compile - when the model code is recompiled
• command-center - when code is run through the command center
• global - when a global variable value changes
• input-box - when an input box widget changes
• link - when a link agent is created or dies
• model-open - when a model is opened
• slider - when a slider widget changes
• speed-slider - when the speed slider changes
• start - always the first entry of a log, contains system info
• switch - when a switch widget changes
• stop - always the last entry of a log
• turtle - when a turtle agent is created or dies
• widget-edit - when a widget is added to or removed from the model
• tick - when the tick counter is advanced

There are also some shortcut names you can use in the preferences to refer to collections of events:

• all - button, chooser, comment, compile, command-center, global, input-box, link, model-open, slider, speed-slider, start, switch, stop, turtle, widget-edit, tick
• agents - link, turtle
• defaults - everything but global, link, tick, and turtle
• greens - chooser, input-box, slider, switch - the “global variable” widgets

Example logging strings you could put in the Events to log: setting in preferences dialog or use via the --log-events command line switch.

• “button, model-open, widget-edit” - log only button widget presses, model open events, and widget add/remove
• “defaults, global” - add global variable change events to the defaults list
• “button, greens, model-open” - log widget use and model open events.

JSON Output

The output is in JSON text format. Below is an example log file with some small modifications to content to fit better in this document.

Each line has an “event” identifying its type along with a “timeStamp” of when it occurred. Then there is an “eventInfo” entry that contains further information specific to the event. For example, “model-open” event contains the model “name”, and the “button” events contain the “buttonName” and whether the click stopped a forever button, “wasStopped”.

[
  {"event":"start","timeStamp":"2022-06-17 11:29:56.737","eventInfo":{"studentName":"Larry","modelName":"Slime.nlogo","version":"NetLogo 6.#.#","ipAddress":"192.168.1.11","loginName":"cpu_user","events":["input-box","switch",...,"widget-edit"]}}
, {"event":"model-open","timeStamp":"2022-06-17 11:29:56.738","eventInfo":{"name":"Slime.nlogo"}}
, {"event":"compile","timeStamp":"2022-06-17 11:29:57.201","eventInfo":{"code":"patches-own [chemical]\n...","success":true}}
, {"event":"button","timeStamp":"2022-06-17 11:29:58.617","eventInfo":{"buttonName":"setup","wasStopped":false}}
, {"event":"tick","timeStamp":"2022-06-17 11:29:58.675","eventInfo":{"ticks":0.0}}
, {"event":"button","timeStamp":"2022-06-17 11:29:58.676","eventInfo":{"buttonName":"setup","wasStopped":true}}
, {"event":"button","timeStamp":"2022-06-17 11:29:58.961","eventInfo":{"buttonName":"go","wasStopped":false}}
, {"event":"tick","timeStamp":"2022-06-17 11:29:58.993","eventInfo":{"ticks":1.0}}
, {"event":"tick","timeStamp":"2022-06-17 11:29:59.030","eventInfo":{"ticks":2.0}}
, {"event":"tick","timeStamp":"2022-06-17 11:29:59.076","eventInfo":{"ticks":3.0}}
, {"event":"tick","timeStamp":"2022-06-17 11:29:59.123","eventInfo":{"ticks":4.0}}
, {"event":"button","timeStamp":"2022-06-17 11:29:59.921","eventInfo":{"buttonName":"go","wasStopped":true}}
, {"event":"slider","timeStamp":"2022-06-17 11:30:01.681","eventInfo":{"valueChanged":true,"min":1.0,"globalName":"population","max":1500.0,"inc":1.0,"buttonReleased":false,"newValue":399.0}}
, {"event":"slider","timeStamp":"2022-06-17 11:30:01.698","eventInfo":{"valueChanged":true,"min":1.0,"globalName":"population","max":1500.0,"inc":1.0,"buttonReleased":false,"newValue":391.0}}
, {"event":"slider","timeStamp":"2022-06-17 11:30:02.317","eventInfo":{"valueChanged":true,"min":1.0,"globalName":"population","max":1500.0,"inc":1.0,"buttonReleased":false,"newValue":179.0}}
, {"event":"button","timeStamp":"2022-06-17 11:30:02.910","eventInfo":{"buttonName":"setup","wasStopped":false}}
, {"event":"tick","timeStamp":"2022-06-17 11:30:02.919","eventInfo":{"ticks":-1.0}}
, {"event":"tick","timeStamp":"2022-06-17 11:30:02.922","eventInfo":{"ticks":0.0}}
, {"event":"button","timeStamp":"2022-06-17 11:30:02.922","eventInfo":{"buttonName":"setup","wasStopped":true}}
, {"event":"button","timeStamp":"2022-06-17 11:30:03.254","eventInfo":{"buttonName":"go","wasStopped":false}}
, {"event":"tick","timeStamp":"2022-06-17 11:30:03.258","eventInfo":{"ticks":1.0}}
, {"event":"tick","timeStamp":"2022-06-17 11:30:03.293","eventInfo":{"ticks":2.0}}
, {"event":"button","timeStamp":"2022-06-17 11:30:03.763","eventInfo":{"buttonName":"go","wasStopped":true}}
, {"event":"command-center","timeStamp":"2022-06-17 11:30:08.489","eventInfo":{"owner":"Command Center","code":"ask turtles [ set color black ]","agentType":"O","success":true}}
, {"event":"stop","timeStamp":"2022-06-17 11:30:09.703"}
]

JSON is a very common data format so there are numerous ways to use it. Most scripting and programming languages have easy ways to read JSON data in so that it can be processed, fed to another system (such as a database), or re-formatted somehow (perhaps to a plot using a plotting library).

Modern versions of Microsoft Excel can import JSON directly. Google Sheets does not yet support JSON import natively, but there are add-on scripts that can be used. There are also numerous online converters that can turn JSON to a “flattened” CSV or just convert it to XML as well.

Where Logs are Stored

By default logs are stored in the operating system specific user’s 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>/.

Managing Log Files

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. Both commands stop the current log file (so it can be zipped or deleted) and a new one is started afterwards.