S T R U C T O R I Z E R - User Guide

Since version 3.28-02, Structorizer makes use of the standard Java.util.logging mechanism to provide internal status information, error messages, warnings, and other diagnostic help in a configurable way.

Location of the log files

The log files will by default be created in the ".structorizer" subfolder of the user's home directory and match the name pattern structorizer*.log.

On Structorizer startup, the logging parameters will be read from a file "logging.properties" (see section below). Among them are

  • the target folder for the log files (the subfolder ".structorizer" in the user home directory by default, as mentioned above),
  • the log file naming scheme (normally the log file will be named "structorizer0.log", but if this happens to be locked by some Structorizer instance or if rolling over is enabled, files "structorizer1.log", "structorizer2.log" etc. might occur for further instances),
  • the internal structure of the log file(s) (by default using an XML schema), and
  • the log level from which on notifications are allowed to be logged (by default: CONFIG).

Be aware that the logging information may be written to the log file with some detention due to internal buffering. A file with additional extension ".lock" signalizes that a Structorizer instance is logging to the file and holds a handle of it. This will hinder another Structorizer instance opened in parallel to mix in its logging data. Instead, it would use another log file with incremeneted number. By closing a Structorizer instance, however, you will flush the buffered content to the respective file and unlock the log file.

Logging content sample

The simplest log file content may look like this:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE log SYSTEM "logger.dtd">
  <message>Structorizer 1 starting up.</message>
  <message>Loading now locale: en.txt</message>
  <message>Structorizer 1 shutting down.</message>

As soon as you e.g. import a source file, however, or on certain trouble, you should expect many more entries (records) of different levels.

Logging configuration

The location of the file "logging.properties" differs between the versions:

  • version 3.28-02: in folder "Structorizer.app/Contents/Java" in the installed (or rather unzipped) Structorizer product directory (see Installation) next to the delivered Structorizer.jar file.
  • from version 3.28-03 on: in the ".structorizer" subfolder of the user's home directory (where the structorizer.ini file resides as well).

The default settings in the properties file are:

handlers= java.util.logging.FileHandler, java.util.logging.ConsoleHandler

(specifying that log records may be written first to file and then to the console);

.level= INFO

(specifying that by default only log records with level INFO and more important are qualified to be logged as far as the respective log handler doesn't impose an even stricter filter);

java.util.logging.FileHandler.pattern = %h/.structorizer/structorizer%u.log
java.util.logging.FileHandler.limit = 50000
java.util.logging.FileHandler.count = 1
java.util.logging.FileHandler.formatter = java.util.logging.XMLFormatter
java.util.logging.FileHandler.level = CONFIG

(configuring more specifically for the file logging:

  • how log files be named and where to be placed,
  • a maximum of 50000 bytes - which is about 50 KiB - per log file before logging rolls over to the next file,
  • that at most 1 file be used for rotating log, which means overwriting the log file cyclically, - you may specify a larger number -,
  • that the content of the be formatted as XML, and
  • that log records from level CONFIG on are principally allowed - which is more verbose than just INFO and already contains certain diagnosis records but requires that the default logging level ).

java.util.logging.ConsoleHandler.level = SEVERE
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter

(specifying that the console logging filter is raised to SEVERE - which means that nearly nothing is passed to the console, except very critical events -, and that the console messages use a very simple two-line format).

lu.fisch.structorizer.parsers.level = CONFIG

(specifying that on source code import the general log level threshold of INFO is lowered to CONFIG - thus including some developer diagnostics for those logging handlers - file or console - being open for it.)

You find more detailled information about logging configuration in the official Java documentation.

Your individual settings in this file will be preserved, even on updating Structorizer to a new version. If you want to get back to the original default settings with versions 3.28-03 or higher, then just rename or delete the file "logging.properties" before you start Structorizer the next time - Strictorizer will then restore the default configuration file in the ".structorizer" folder.

Use of logging results

After some functional problem in Structorizer or a crash, you may rescue the respective log file from the .structorizer folder and pass it with the bug report for further analysis to the Structorizer developmen team.

Be aware that the log file might be incomplete while Structorizer is still running (as mentioned above). You should avoid opening Structorizer again before you have copied the log file because starting Structorizer may override an existing log file.

Data protection hint

Log files won't contain personal data or sensitive data about your machine. But you can of course make sure of that before you upload them - the file contains XML (or plain text if you specify e.g. java.util.logging.SimpleFormatter as formatter). If you decide to clear some information you don't want to share, you should of course preserve the well-formed XML structure.