From d43055095c4100fd19cd8c79e7a6240d37e8ba04 Mon Sep 17 00:00:00 2001 From: Hugo Locurcio Date: Fri, 28 Mar 2025 19:38:03 +0100 Subject: [PATCH] Document file logging in Data paths --- .../introduction_to_the_buildsystem.rst | 2 + .../exporting_for_dedicated_servers.rst | 5 ++- tutorials/io/data_paths.rst | 42 +++++++++++++++++++ 3 files changed, 48 insertions(+), 1 deletion(-) diff --git a/contributing/development/compiling/introduction_to_the_buildsystem.rst b/contributing/development/compiling/introduction_to_the_buildsystem.rst index 557db6a1d06..ed41955fa44 100644 --- a/contributing/development/compiling/introduction_to_the_buildsystem.rst +++ b/contributing/development/compiling/introduction_to_the_buildsystem.rst @@ -197,6 +197,8 @@ binary name. you can enable at compile-time to better debug certain engine issues. See :ref:`doc_using_sanitizers` for more information. +.. _doc_introduction_to_the_buildsystem_debugging_symbols: + Debugging symbols ----------------- diff --git a/tutorials/export/exporting_for_dedicated_servers.rst b/tutorials/export/exporting_for_dedicated_servers.rst index 55f1699a618..d91d04d03e4 100644 --- a/tutorials/export/exporting_for_dedicated_servers.rst +++ b/tutorials/export/exporting_for_dedicated_servers.rst @@ -281,7 +281,10 @@ On Linux, to make your dedicated server restart after a crash or system reboot, you can `create a systemd service `__. This also lets you view server logs in a more convenient fashion, with automatic -log rotation provided by systemd. +log rotation provided by systemd. When making your project hostable as a systemd service, +you should also enable the ``application/run/flush_stdout_on_print`` +project setting. This way, journald (the systemd logging service) can collect +logs while the process is running. If you have experience with containers, you could also look into wrapping your dedicated server in a `Docker `__ container. This way, diff --git a/tutorials/io/data_paths.rst b/tutorials/io/data_paths.rst index 3f5dcc3ea67..51561468146 100644 --- a/tutorials/io/data_paths.rst +++ b/tutorials/io/data_paths.rst @@ -111,6 +111,48 @@ On HTML5 exports, ``user://`` will refer to a virtual filesystem stored on the device via IndexedDB. (Interaction with the main filesystem can still be performed through the :ref:`JavaScriptBridge ` singleton.) +File logging +------------ + +By default, Godot writes log files in ``user://logs/godot.log`` on desktop +platforms. You can change this location by modifying the +``debug/file_logging/log_path`` project setting. Logs are rotated to keep older +files available for inspection. Each session creates a new log file, with the +old file renamed to contain the date at which it was rotated. Up to 5 log files +are kept by default, which can be adjusted using the +``debug/file_logging/max_log_files`` project setting. + +File logging can also be disabled completely using the +``debug/file_logging/enable_file_logging`` project setting. + +When the project crashes, crash logs are written to the same file as the log +file. The crash log will only contain an usable backtrace if the binary that was +run contains debugging symbols, or if it can find a debug symbols file that +matches the binary. Official binaries don't provide debugging symbols, so this +requires a custom build to work. See +:ref:`Debugging symbols `. +for guidance on compiling binaries with debugging symbols enabled. + +.. note:: + + Log files for :ref:`print` + statements are updated when standard output is *flushed* by the engine. + Standard output is flushed on every print in debug builds only. In projects that + are exported in release mode, standard output is only flushed when the project exits + or crashes to improve performance, especially if the project is often printing + text to standard output. + + On the other hand, the standard error stream + (used by :ref:`printerr`, + :ref:`push_error` and + :ref:`push_warning`) is always + flushed on every print, even in projects exported in release mode. + + For some use cases like dedicated servers, it can be preferred to have release + builds always flush stdout on print, so that logging services like journald can + collect logs while the process is running. This can be done by enabling + ``application/run/flush_stdout_on_print`` in the Project Settings. + Converting paths to absolute paths or "local" paths ---------------------------------------------------