Atomic Debug Logging

Last updated on 26th March 2024

What is Atomic Logging?

A new feature added as of v2.5 to the SDK is Atomic Logging. Atomic Logging is a optional functionality that when enabled will work with the Health Check to determine if your model is deterministic. It does this by having it's own internal output of core actions to a set of files. These files are then compared, and can thereafter be interrogated automatically by the Determinism Linter, or by a user.

Additionally various helper functions have been added which allow a user to write their own information directly to a log. This can be used both to have a dedicated file output that will only run when enabled (as opposed to use a SL4LJ logging setup), and additionally shoudl there be an element of potentially non-determinism in a model that isn't made clear via the existing output information - a user is able to set their own checks anywhere in the model.

Enabling Atomic Logging

To enable Atomic Logging, you need simply call the model function to do so. The best place for this is as the first function call in your setup function as below.

Using a logger (Java)

@Override
public void setup() {
	enableAtomicLogging();
	...
}

Health Check

Take note that the Health Check will run for any and all models registered to the server, but that the additional creation and verification of atomic logging will only occur if the model has enabled it.

Once enabled a directory called 'logging' will be created underneath the main project directory. Within that there will be a series of folders created every time the model is run (with multiple created if Health Check is enabled). These folders will be named according to the simulation run UUID value.

Within 6 .log files will be written related to ACTIONS, AGENTS, MESSAGES, METADATA, USER, VARIABLES corresponding to different outputs from the atomic logger. At this time not all of these contain multiple verbose information, but may do so in the future as discrete atomic interactions become necessary for interrogation.

Writing to Atomic Log

To write out to the USER.log file you need simply call the model function writeToLog as long as you have enabled atomic logging.

Using a logger (Java)

@Override
public void setup() {
	enableAtomicLogging();
	...
	
	writeToLog("Some result: " + variable);
	
	...
}

Alternatively you can specify which log file you want said information to be written and can do so from within an agent like so:

Using a logger (Java)

public static Action<MyAgent> logAction = Action.create(MyAgent.class, agent -> {
        agent.getContext().write(ALCat.USER, "Info to Output");
	}
);

You'll notice the reference to ALCat this is an enum to determine which type of output you are working with corresponding to the above 6 types.