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

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 location of the log files is usually a subfolder ".structorizer" of the user's home directory. The name or even the path of this subfolder may differ, though, depending on the platform and some non-standard constellation (e.g. use of some app data subfolder specified):

  • On Windows it might be "%APPDATA%\Structorizer" or "Application Data\Structorizer";
  • on Mac OS X it could be "Library/Application Support/Structorizer";
  • on Linux it might be ".unimozer".

From version 3.28-10 on, you will find the actual paths of important folders or files on a new tab of the "About" dialog (which can be opened via the "Help" menu or key combination <Ctrl><F1>) in order to spare you from wild guessing:

Paths tab on the About window

The log files will match the name pattern "structorizer*.log" by default.

On Structorizer startup, the logging parameters will be read from a file "logging.properties" (see section below), which is supposed to be placed in the log folder as discussed above. Among them are

  • the target folder for the log files (the very subfolder of the user home directory discussed above),
  • the log file naming pattern (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 structure of the log entries(s) (by default using an XML schema), and
  • the minimum log level for which 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 incremented 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">
<log>
<record>
  <date>2018-06-04T15:53:05</date>
  <millis>1528120385399</millis>
  <sequence>0</sequence>
  <logger>lu.fisch.structorizer.gui.Mainform</logger>
  <level>INFO</level>
  <class>lu.fisch.structorizer.gui.Mainform</class>
  <method>&lt;init&gt;</method>
  <thread>1</thread>
  <message>Structorizer 1 starting up.</message>
</record>
<record>
  <date>2018-06-04T15:53:05</date>
  <millis>1528120385470</millis>
  <sequence>1</sequence>
  <logger>lu.fisch.structorizer.locales.Locale</logger>
  <level>INFO</level>
  <class>lu.fisch.structorizer.locales.Locale</class>
  <method>&lt;init&gt;</method>
  <thread>1</thread>
  <message>Loading now locale: en.txt</message>
</record>
<record>
  <date>2018-06-04T15:53:09</date>
  <millis>1528120389136</millis>
  <sequence>2</sequence>
  <logger>lu.fisch.structorizer.gui.Mainform</logger>
  <level>INFO</level>
  <class>lu.fisch.structorizer.gui.Mainform$4</class>
  <method>windowClosing</method>
  <thread>19</thread>
  <message>Structorizer 1 shutting down.</message>
</record>
</log>

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" (see discussion in "Location of the log file" above) subfolder of the user's home directory.

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 development 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 they might contain file paths and therefore user account names. So you can of course review the contents and make sure there aren't privacy risks 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.