From 30b26426f473c6998919319a6f56a9b420720856 Mon Sep 17 00:00:00 2001 From: eliasehmann <41519164+eliasehmann@users.noreply.github.com> Date: Sat, 14 Nov 2026 17:29:12 +0100 Subject: [PATCH] Support `json` as a value of `LOG_CONSOLE_FORMAT` / `LOG_FILE_FORMAT` for JSON log lines (#4393) --- docs/configuration/misc-options.md | 24 +++++++++++++++ docs/variables.md | 6 ++-- files/log4j2-json-pattern.txt | 1 + scripts/start-finalExec-log4j | 29 +++++++++++++++++++ .../log4j-json/docker-compose.yml | 11 +++++++ tests/setuponlytests/log4j-json/verify.sh | 5 ++++ 6 files changed, 73 insertions(+), 3 deletions(-) create mode 100644 files/log4j2-json-pattern.txt create mode 100644 tests/setuponlytests/log4j-json/docker-compose.yml create mode 100644 tests/setuponlytests/log4j-json/verify.sh diff --git a/docs/configuration/misc-options.md b/docs/configuration/misc-options.md index 976f8557..9433e26f 100644 --- a/docs/configuration/misc-options.md +++ b/docs/configuration/misc-options.md @@ -130,6 +130,30 @@ For full control over how log messages are formatted, you can customize the Log4 - `LOG_TERMINAL_FORMAT` : Format for interactive terminal console (used with `docker attach`) Default: `[%d{HH:mm:ss} %level]: %msg%n` +### JSON log output + +Set a format variable to `json` to output one JSON object per line instead of text, which suits log pipelines that parse container output, such as Loki, Elasticsearch, or Datadog. For example, to get JSON in `docker logs` while `logs/latest.log` stays plain text: + +```yaml +environment: + GENERATE_LOG4J2_CONFIG: "true" + LOG_CONSOLE_FORMAT: json +``` + +`LOG_FILE_FORMAT` and `LOG_TERMINAL_FORMAT` accept `json` as well. Each line uses field names from the [Elastic Common Schema](https://www.elastic.co/guide/en/ecs/current/index.html), the same ones as Log4j's `EcsLayout.json` template: + +```json +{"@timestamp":"2026-11-12T13:50:43.459Z","ecs.version":"1.2.0","log.level":"INFO","message":"Done (3.214s)! For help, type \"help\"","process.thread.name":"Server thread","log.logger":"net.minecraft.server.dedicated.DedicatedServer"} +``` + +When a log event carries an exception, an `error.stack_trace` field holds the stack trace. Timestamps are in UTC. + +!!! note + + - JSON output requires Minecraft 1.18.1 or newer. For older versions the default text format is used and a warning is logged. + - Only the server's log output is JSON. Lines written by the image's startup scripts (prefixed with `[init]`) and output that bypasses Log4j, such as JVM warnings, remain plain text, so a log shipper should skip lines that don't parse as JSON. + - Minecraft server jars don't include Log4j's `log4j-layout-template-json` module, so the JSON is built with a pattern layout rather than `JsonTemplateLayout`, and custom event templates aren't supported. For a different JSON shape, set the format variable to your own pattern using `%enc{...}{JSON}` to escape values. + ### Example configurations Simple timestamp customization (most common use case): diff --git a/docs/variables.md b/docs/variables.md index 640f84a4..3e251b83 100644 --- a/docs/variables.md +++ b/docs/variables.md @@ -65,19 +65,19 @@ alternatively, you can mount: /etc/localtime:/etc/localtime:ro LOG_CONSOLE_FORMAT - Log4j2 pattern for console output (what you see in docker logs) + Log4j2 pattern for console output (what you see in docker logs), or json for JSON lines [%d{HH:mm:ss}] [%t/%level]: %msg%n ⬜️ LOG_FILE_FORMAT - Log4j2 pattern for file logs (written to logs/latest.log) + Log4j2 pattern for file logs (written to logs/latest.log), or json for JSON lines [%d{HH:mm:ss}] [%t/%level]: %msg%n ⬜️ LOG_TERMINAL_FORMAT - Log4j2 pattern for interactive terminal console (used with docker attach) + Log4j2 pattern for interactive terminal console (used with docker attach), or json for JSON lines [%d{HH:mm:ss} %level]: %msg%n ⬜️ diff --git a/files/log4j2-json-pattern.txt b/files/log4j2-json-pattern.txt new file mode 100644 index 00000000..180856ba --- /dev/null +++ b/files/log4j2-json-pattern.txt @@ -0,0 +1 @@ +{"@timestamp":"%d{yyyy-MM-dd'T'HH:mm:ss.SSS'Z'}{UTC}","ecs.version":"1.2.0","log.level":"%level","message":"%enc{%msg}{JSON}","process.thread.name":"%enc{%t}{JSON}","log.logger":"%enc{%c}{JSON}"%notEmpty{,"error.stack_trace":"%enc{%replace{%ex}{^\s+|\s+$}{}}{JSON}"}}%ex{none}%n diff --git a/scripts/start-finalExec-log4j b/scripts/start-finalExec-log4j index 75f9c529..17113804 100755 --- a/scripts/start-finalExec-log4j +++ b/scripts/start-finalExec-log4j @@ -67,6 +67,30 @@ elif ${useGeneratedLogs}; then ROLLING_LOG_FILE_PATTERN='logs/%d{yyyy-MM-dd}-%i.log.gz' fi + # A format of "json" selects one JSON object per line with ECS field names. + # Minecraft server jars don't bundle log4j-layout-template-json, and their launchers + # load Log4j in an isolated class loader, so the JSON is produced by PatternLayout + # with JSON-encoded fields. %enc{...}{JSON} is available in all Log4j versions + # bundled since Minecraft 1.18.1 (Log4j 2.17). + LOG_JSON_FORMAT=$(/">"} + LOG_JSON_FORMAT=${LOG_JSON_FORMAT//\"/"""} + + for logFormatVar in LOG_CONSOLE_FORMAT LOG_TERMINAL_FORMAT LOG_FILE_FORMAT; do + if [[ ${!logFormatVar:-} && ${!logFormatVar,,} == json ]]; then + if versionLessThan 1.18.1; then + logWarning "${logFormatVar}=json requires Minecraft 1.18.1 or newer, using the default format" + printf -v "$logFormatVar" '%s' '' + else + printf -v "$logFormatVar" '%s' "$LOG_JSON_FORMAT" + fi + fi + done + # Pattern format defaults (compatible with vanilla Minecraft) # Note: Can't use ${VAR:=default} syntax because } in the value breaks parsing if [ -z "${LOG_CONSOLE_FORMAT}" ]; then @@ -126,5 +150,10 @@ EOF # Apply the log4j2 configuration JVM_OPTS="-Dlog4j.configurationFile=log4j2.xml ${JVM_OPTS}" else + for logFormatVar in LOG_CONSOLE_FORMAT LOG_TERMINAL_FORMAT LOG_FILE_FORMAT; do + if [[ ${!logFormatVar:-} && ${!logFormatVar,,} == json ]]; then + logWarning "${logFormatVar}=json is ignored since the image is not generating the log4j2 configuration. Set GENERATE_LOG4J2_CONFIG=true to use it." + fi + done rm -f "${LOGFILE}" fi diff --git a/tests/setuponlytests/log4j-json/docker-compose.yml b/tests/setuponlytests/log4j-json/docker-compose.yml new file mode 100644 index 00000000..b9f12575 --- /dev/null +++ b/tests/setuponlytests/log4j-json/docker-compose.yml @@ -0,0 +1,11 @@ +services: + mc: + restart: "no" + image: ${IMAGE_TO_TEST:-itzg/minecraft-server} + environment: + EULA: "TRUE" + SETUP_ONLY: "TRUE" + GENERATE_LOG4J2_CONFIG: "true" + LOG_CONSOLE_FORMAT: json + volumes: + - ./data:/data diff --git a/tests/setuponlytests/log4j-json/verify.sh b/tests/setuponlytests/log4j-json/verify.sh new file mode 100644 index 00000000..a4171f67 --- /dev/null +++ b/tests/setuponlytests/log4j-json/verify.sh @@ -0,0 +1,5 @@ +mc-image-helper assert fileExists /data/log4j2.xml +# console appender uses the JSON pattern +grep -A1 '