Logging

Die Engine Pi nutzt das java.util.logging-Framework, um Informationen und Fehler zu protokollieren. Die Ausgabe der Protokollierung lässt sich konfigurieren, indem man eine Datei namens logging.properties im Ausführungsverzeichnis des Spiels ablegt. Diese Datei definiert, wohin Logs geschrieben werden (Handlers) und wie detailliert diese sein sollen (Levels).¹²³⁴⁵⁶⁷⁸⁹¹⁰¹¹

logging.properties-Datei

# Globale Handler definieren (Konsole und Datei)
handlers = java.util.logging.ConsoleHandler, java.util.logging.FileHandler

# Standard-Log-Level für die gesamte Anwendung
.level = INFO

# Konfiguration für die Konsolenausgabe
java.util.logging.ConsoleHandler.level = ALL
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter

# Konfiguration für die Dateiausgabe
java.util.logging.FileHandler.pattern = %h/java_app%u.log
java.util.logging.FileHandler.limit = 50000
java.util.logging.FileHandler.count = 1
java.util.logging.FileHandler.formatter = java.util.logging.XMLFormatter

Das Logging kann global über die Datei $JAVA_HOME/conf/logging.properties konfiguriert werden.¹² Auf Linux ist beispielsweise ist diese logging.properties-Datei im Verzeichnis /usr/lib/jvm/java-17-openjdk-amd64/conf/logging.properties zu finden, wenn das OpenJDK 17 installiert ist. Diese globale logging.properties-Datei ist folgendermaßen aufgebaut:

############################################################
#   Default Logging Configuration File
#
# 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
############################################################

############################################################
#   Global properties
############################################################

# "handlers" specifies a comma-separated list of log Handler
# classes.  These handlers will be installed during VM startup.
# Note that these classes must be on the system classpath.
# By default we only configure a ConsoleHandler, which will only
# show messages at the INFO and above levels.
handlers= java.util.logging.ConsoleHandler

# To also add the FileHandler, use the following line instead.
#handlers= java.util.logging.FileHandler, java.util.logging.ConsoleHandler

# Default global logging level.
# This specifies which kinds of events are logged across
# all loggers.  For any given facility this global level
# can be overridden by a facility-specific level
# Note that the ConsoleHandler also has a separate level
# setting to limit messages printed to the console.
.level= INFO

############################################################
# Handler specific properties.
# Describes specific configuration info for Handlers.
############################################################

# default file output is in user's home directory.
java.util.logging.FileHandler.pattern = %h/java%u.log
java.util.logging.FileHandler.limit = 50000
java.util.logging.FileHandler.count = 1
# Default number of locks FileHandler can obtain synchronously.
# This specifies maximum number of attempts to obtain lock file by FileHandler
# implemented by incrementing the unique field %u as per FileHandler API documentation.
java.util.logging.FileHandler.maxLocks = 100
java.util.logging.FileHandler.formatter = java.util.logging.XMLFormatter

# Limit the messages that are printed on the console to INFO and above.
java.util.logging.ConsoleHandler.level = INFO
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter

# Example to customize the SimpleFormatter output format
# to print one-line log message like this:
#     <level>: <log message> [<date/time>]
#
# java.util.logging.SimpleFormatter.format=%4$s: %5$s [%1$tc]%n

############################################################
# Facility-specific properties.
# Provides extra control for each logger.
############################################################

# For example, set the com.xyz.foo logger to only log SEVERE
# messages:
# com.xyz.foo.level = SEVERE

Wichtige Konfigurationsoptionen

Handlers: Bestimmen das Ziel der Logs (z. B. ConsoleHandler für den Bildschirm, FileHandler für Dateien).
Levels: Steuern die Granularität. Häufige Stufen sind SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST.
Formatter: Legen das Layout fest (z. B. SimpleFormatter für Text oder XMLFormatter).
FileHandler Patterns: %h steht für das Home-Verzeichnis des Nutzers, %t für den temporären Ordner.

Logging im Code verwenden

import static pi.Controller.logger;

import java.util.logging.Level;
import java.util.logging.Logger;

import pi.Controller;
import pi.Scene;

/**
 * Demonstriert das statische Attribut {@link Controller#logger} und allgemein
 * das Logging in Java.
 *
 * @since 0.45.0
 */
public class LoggingDemo extends Scene
{
    private static final Logger customLogger = Logger
        .getLogger(LoggingDemo.class.getName());

    public LoggingDemo()
    {
        logger.severe("Eine SEVERE-Nachricht!");
        logger.warning("Eine WARNING-Nachricht!");
        logger.info("Eine INFO-Nachricht!");
        logger.config("Eine CONFIG-Nachricht!");
        logger.fine("Eine FINE-Nachricht!");
        logger.finer("Eine FINER-Nachricht!");
        logger.finest("Eine FINEST-Nachricht!");

        logger.log(Level.SEVERE,
            "Eine SEVERE-Nachricht über die allgemeine log-Methode");

        customLogger
            .severe("Eine SEVERE-Nachricht des benutzerdefinierten Loggers!");
    }

    public static void main(String[] args)
    {
        Controller.instantMode(false);
        Controller.start(new LoggingDemo());
    }
}

Zum Java-Code: demos/subprojects/demos/src/main/java/demos/classes/class_controller/LoggingDemo.java