From dad5327c851254cd6007f39acf544552d6766072 Mon Sep 17 00:00:00 2001 From: Ben Forge <74168521+BenCheung0422@users.noreply.github.com> Date: Sat, 24 May 2025 02:41:02 +0800 Subject: [PATCH 1/2] Create EFP 6 --- efp/efp006/main.xml | 86 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 efp/efp006/main.xml diff --git a/efp/efp006/main.xml b/efp/efp006/main.xml new file mode 100644 index 0000000..825f769 --- /dev/null +++ b/efp/efp006/main.xml @@ -0,0 +1,86 @@ + + + + + + + + +
+ +

+ 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 LZMA2 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 before creating a new log file for the current session. + 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. +

    +     +
    +
    + + +
  • EFP 3
    • +
  • EFP 4
    • +     +     +
    + +     From a490a428883bc38183a4c7e66484cb6dfc2a638e Mon Sep 17 00:00:00 2001 From: Ben Forge <74168521+BenCheung0422@users.noreply.github.com> Date: Sun, 25 May 2025 06:52:20 +0800 Subject: [PATCH 2/2] EFP 6: complement log files and Engine part --- efp/efp006/main.xml | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/efp/efp006/main.xml b/efp/efp006/main.xml index 825f769..c554efd 100644 --- a/efp/efp006/main.xml +++ b/efp/efp006/main.xml @@ -38,10 +38,19 @@ the American National Standards Institute (ANSI) escape code option.

    - The file logs should be handled in a way that old logs are compressed in LZMA2 with + 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 before creating a new log file for the current session. + .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 @@ -72,6 +81,11 @@ 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) +