diff --git a/efp/efp006/main.xml b/efp/efp006/main.xml new file mode 100644 index 0000000..c554efd --- /dev/null +++ b/efp/efp006/main.xml @@ -0,0 +1,100 @@ + + + + + + + + +
+ +

+ Logging would become one of the core utilities of the TerraModulus game application, that all + other parts would rely on. This proposal discusses all the practices and the structure of the logging + framework for the game application. +

+ +
+
+ +

+ The surface utility would be provided by + kotlin-logging with its underlying + SLF4J 2 interface. The logging provider would be Log4j 2 with SLF4J bridge. However, all these + interfaces should be hidden in the common module of the application, but exposing + the configured custom public interface defined in the application for other modules or dependents + for usage. +

+

+ There would only be two appenders for the logging framework. Both are formatted using simple + patterns, but structural logging is yet not applied until it becomes essential to be fed into + the Launcher for log ingestion. The log message should contain full timestamp in the local + timestamp, thread ID, log level, full logger name and the message, represented as + %d{DEFAULT_NANOS} [%T] [%p] %c: %m%n. There is no standard about how exceptions + should be logged, so exception logging relies on the library's default behavior. + Please note that logging to console should enable highlighting but disable to non-console + standard output for the Launcher to ingest; this is controlled by + the American National Standards Institute (ANSI) escape code option. +

+

+ The file logs should be handled in a way that old logs are compressed in LZMA with + configuration tuned efficiently for text. Therefore, when all logs are logged in a directory + of logs from the root of data directory, all existing logs with extensions of + .log should be compressed in 7z before creating a new log file for + the current session. + Log files are named with a full datetime string form in the order of: year, month, date, + hour, minute, second and millisecond, with all values hyphenated. + Since when the log file is created, there should only be single file with the extension of + .log, and thus it should be safe to use the human identifiable filename + without relying on file creation time metadata. + For the compressed archives, it is possible to have duplication when users have unstable + time settings, so the filename would contain only hyphenated date determined by the filename with + an increment number starting at 1; the resultant postfix would be .log.7z. + This may be done by defining a custom plugin to be used for configuration. Please note that + having more than one instance of the game application running over the same data directory + is illegal, so only one instance should hold the new log file, and this should be initialized + only when instance duplication checking is completed. +

+

+ All logs from all log levels should be outputted to both the file appender and the console + appender. This allows the Launcher to act as a supervisor to ingest and filter logs to + display to users from the standard output. However, verbosity should not be too high by + default, to prevent unreadable logs to users. Logging should be done in a separate thread + or asynchronously to reduce performance impact to other threads; this may be done by using + AsyncRoot. +

+ +
+
+ +

+ Logging should always be enabled regardless of target, but certain elements may not trace + or debug information when they are too verbose. That is, if they contain too much + information for debugging, mixing other information at the same time, they may be used either: +

+ +
  • Only in development debugs, enabled by uncommenting in source code; or
    • +
  • By inserting an argument option in launcher arguments for tracing specific parts.
    • +     +

    + When some logs are controlled by launcher arguments, inlined helper functions could be + used to simplify the logging code. +

    +

    + In production, the Engine should not log anything, but the Kotlin layer over it. There + might be unexpected errors from the Engine, such errors should be well handled without + having to emit errors, but typically the return values. (see EFP 5 - Debugging) +

    +     +
    +
    + + +
  • EFP 3
    • +
  • EFP 4
    • +     +     +
    + +