Merge pull request #10812 from Calinou/data-paths-file-logging

Document file logging in Data paths

Author: mhilbrunner

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
 -----------------
 

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 <https://medium.com/@benmorel/creating-a-linux-service-with-systemd-611b5c8b91d6>`__.
 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 <https://www.docker.com/>`__ container. This way,

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 <class_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 <doc_introduction_to_the_buildsystem_debugging_symbols>`.
+for guidance on compiling binaries with debugging symbols enabled.
+
+.. note::
+
+    Log files for :ref:`print<class_@GlobalScope_method_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<class_@GlobalScope_method_printerr>`,
+    :ref:`push_error<class_@GlobalScope_method_push_error>` and
+    :ref:`push_warning<class_@GlobalScope_method_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
 ---------------------------------------------------