Logging

This section tells you how to correctly use the logging mechanism built into Java to log messages about a SimStadt program to the console and/or log files.

Comprehensive logging helps to debug or trace a program run (log-levels FINE, FINER, FINEST), to inform about the current configuration of a system (log-level CONFIG), to display interesting facts, e.g. used computation time (log-level INFO), and to inform about recoverable and irrecoverable exceptions (log-levels WARNING and SEVERE). https://en.wikipedia.org/wiki/Log4j#Log4j_1_Log_level and http://www.thejoyofcode.com/Logging_Levels_and_how_to_use_them.aspx display more information about log-levels and how to use them.

Each class that has to log something should instantiate its own logger like in this example for class SunWindExposedEngine:

private static final Logger LOGGER = Logger.getLogger(SunWindExposedEngine.class.getName());

Then, log your messages like this

LOGGER.finest(String.format("inspect polygon %s", subject));

using the appropriate log level

• SEVERE (highest value)
• WARNING
• INFO
• CONFIG
• FINE
• FINER
• FINEST (lowest value)

For performance reasons use String.format() instead of concatenating Strings with '+'.

When running a program (JUnit test or SImStadt Client) you can specify a file with special logging properties by setting the VM runtime argument "-Djava.util.logging.config.file". In Eclipse this setting can be found at Run -> Run Configurations... -> Arguments-Tab -> VM arguments. E.g. in the run configuration SimStadtApp of project SimStadtFrontend looks like this:

-Djava.util.logging.config.file=loggingInsel.properties

Look at comments in this file to learn how to enable/disable logging levels for different parts of the system and utilize other settings.

############################################################
#  	Logging Configuration File for SimStadtFrontEnd
#
# You can use a different file by specifying a filename
# with the java.util.logging.config.file system property.  
# For example java -Djava.util.logging.config.file=myfile
############################################################

# By default we only log to the ConsoleHandler.
handlers=java.util.logging.ConsoleHandler

# To also activate logging to log-files, use the following line instead.
#handlers= java.util.logging.FileHandler, java.util.logging.ConsoleHandler

# Default global logging level
.level=CONFIG

# This can be overridden by package or class specific levels in both directions.
# For example, to log at level FINE for class eu.simstadt.geompreproc.FacadeCalculator
# and restrict logging for all other classes in package eu.simstadt.geompreproc to
# level INFO use the following two lines:
#eu.simstadt.geompreproc.FacadeCalculator.level=FINE
#eu.simstadt.geompreproc.level=INFO

# Note that the resulting log messages can be restricted for the ConsoleHandler
# separately. This setting does not limit the messages printed on the console:
java.util.logging.ConsoleHandler.level=ALL

# Use the following line to restrict console messages to WARNING 
#java.util.logging.ConsoleHandler.level=WARNING

# More specific configuration for Handlers:
java.util.logging.ConsoleHandler.formatter=java.util.logging.SimpleFormatter

java.util.logging.FileHandler.formatter=java.util.logging.SimpleFormatter
# default file output is in user's home directory.
# %t is the temporary fiels directory, eg. ..user/AppData/Local/Temp on Windows 7
java.util.logging.FileHandler.pattern=%t/SimStadt%g_%u.log
java.util.logging.FileHandler.limit=1000000
java.util.logging.FileHandler.count=3