|
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 standard location of the log files is subfolder ".structorizer" of the user's home directory. If you are in doubt, you will find the actual paths of important folders or files on the "Paths" 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 (since version 3.28-10):
The log files match the name pattern "structorizer*.log" by default. But the exact naming scheme was modified with release 3.30 (though it did not become effective before version 3.30-08):
- Before release 3.30, the standard log file name was "structorizer0.log". In case of several concurrently running Structorizer instances, they used increasing "unique" numbers ("structorizer1.log", "structorizer2.log", etc.) lest they should merge their contents. There were no backups, and log entries may not have become visible before Structorizer was closed. By restarting Structorizer, the previous log file was immediately overwritten.
- Since release 3.30 (version 3.30-08, actually), the log files are named with two numbers, the "unique" number (as described above), and a "generation" counter as second number. The first log file will be named "structorizer0.0.log". In case of concurrent Structorizer sessions, they use differing first numbers ("structorizer0.*.log", "structorizer1.*.log" etc.). When Structorizer starts then it looks for the lowest unlocked unique (first) number; it will then rename all existing log files with this first number by incrementing the second number (e.g. "structorizer0.0.log" will become "structorizer0.1.log" etc.) before it creates its new log file with generation number 0. Hence: The larger the second number the older the log file. The obvious advantage of the file versioning is that restarting Structorizer does not destroy the previous log.
An empty file with additional extension ".lck" (e.g. "structorizer1.0.log.lck") signalizes that a Structorizer instance is logging to the corresponding log file and holds a handle of it. This will hinder other Structorizer instances opening it in parallel to mix in their logging data. Instead, these would use or create own log files with higher (first) number (e.g. "structorizer2.0.log").
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 the parameters there are:
- the target folder for the log files (the very subfolder of the user home directory discussed above),
- the log file naming pattern (where placeholders "%h", "%u", "%g" designate the user home directory, the unique number, and the generation number, respectively, see above),
- the structure of the log entries (by default using an XML schema), and
- the minimum log level for which notifications are allowed to be logged (by default: CONFIG).
If you had already used Structorizer versions < 3.30 then you will have to remove the file "logging.properties" from the ".structorizer" folder in order to get the new configuration (if a configuration file is found then it will be preserved as it might contain a user-specfic configuration). Alternatively you might edit the existing configuration file manually (see below). The same holds with version 3.30-08, which corrects the naming scheme. (If your log files are named like "structorizer0.log.0" then you had obtained a flawed logging.properties file on installation, though this is not critical at all.)
Note: It may seem as if the logging information were written with some detention to the log file, the size of the file may be displayed as 0 in your file manager, even after a reported error. But don't get fooled. Just open the log file with some text viewer or editor — you will see that it actually contains log entries you may copy.
If you have restarted Structorizer after some misbehaviour that you would like to have analysed, the information will not immediately get lost: If the logging configuration is up to date, the logs of the last five sessions will still be maintained (their second number just gets incremented each time you close Structorizer and start it again, as explained above).
In Linux and OS X, the logging folder will usually be hidden (due to the naming scheme). So you may have to make it visible in order to inspect it, e.g. in Mac OS X you may have to press key combination <Shift><Cmd><H> in the Finder to show the home directory and then <Shift><Cmd><.> to make visible the directories and files named with an initial dot. With a GUI file manager in Linux, you might have to check an option "Show hidden files" in the "View" menu.
Logging content sample
The simplest log file content may look like this:
<?xml version="1.0" encoding="windows-1252" standalone="no"?>
<!DOCTYPE log SYSTEM "logger.dtd">
<log>
<record>
<date>2019-10-05T21:17:22</date>
<millis>1570303042244</millis>
<sequence>0</sequence>
<logger>Structorizer</logger>
<level>INFO</level>
<class>Structorizer</class>
<method>main</method>
<thread>1</thread>
<message>Command line: </message>
</record>
<record>
<date>2019-10-05T21:17:22</date>
<millis>1570303042416</millis>
<sequence>1</sequence>
<logger>lu.fisch.structorizer.gui.Mainform</logger>
<level>INFO</level>
<class>lu.fisch.structorizer.gui.Mainform</class>
<method><init></method>
<thread>1</thread>
<message>Structorizer 1 (version 3.30) starting up.</message>
</record>
<record>
<date>2019-10-05T21:17:22</date>
<millis>1570303042478</millis>
<sequence>2</sequence>
<logger>lu.fisch.structorizer.locales.Locale</logger>
<level>INFO</level>
<class>lu.fisch.structorizer.locales.Locale</class> <method><init></method> <thread>1</thread> <message>Loading now locale: en.txt</message>
</record>
<record>
<date>2019-10-05T21:18:04</date>
<millis>1570303084255</millis>
<sequence>22</sequence>
<logger>lu.fisch.structorizer.gui.Mainform</logger>
<level>INFO</level>
<class>lu.fisch.structorizer.gui.Mainform$4</class>
<method>windowClosing</method>
<thread>16</thread>
<message>Structorizer 1 (version 3.30) shutting down.</message>
</record>
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" is the ".structorizer" subfolder of the user's home directory (see discussion in "Location of the log file" above).
The default settings in the properties file are:
handlers= java.util.logging.FileHandler, java.util.logging.ConsoleHandler
(specifying that log records 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.%g.log
java.util.logging.FileHandler.limit = 100000
java.util.logging.FileHandler.count = 5
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 100000 bytes — which is about 100 KiB — per log file before logging rolls over to the next file,
- that at most 5 files (before release 3.30 it was only 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 log 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 is at least CONFIG, too).
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 of Structorizer or, contrarily, update to the new configurations of release 3.30 then just rename or delete the file "logging.properties" before you start Structorizer the next time — Structorizer will then create an new default configuration file in the ".structorizer" folder.
Use of logging results
After some functional problem in Structorizer or a crash, you may rescue (i.e. copy) 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 (privacy) remark
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 or e-mail them — the file contains XML by default (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, then you should of course preserve the well-formed XML structure. |
