mirror of
https://github.com/godotengine/godot-docs.git
synced 2026-01-01 21:48:57 +03:00
275 lines
13 KiB
ReStructuredText
275 lines
13 KiB
ReStructuredText
.. _doc_logging:
|
|
|
|
Logging
|
|
=======
|
|
|
|
Godot comes with several ways to organize and collect log messages.
|
|
|
|
Printing messages
|
|
-----------------
|
|
|
|
.. seealso::
|
|
|
|
See :ref:`doc_output_panel_printing_messages` for instructions on printing
|
|
messages. The printed output is generally identical to the logged output.
|
|
|
|
When running a project from the editor, the editor will display logged text
|
|
in the :ref:`doc_output_panel`.
|
|
|
|
Project settings
|
|
----------------
|
|
|
|
There are several project settings to control logging behavior in Godot:
|
|
|
|
- **Application > Run > Disable stdout:** Disables logging to standard output entirely.
|
|
This also affects what custom loggers receive. This can be controlled at runtime
|
|
by setting :ref:`Engine.print_to_stdout <class_Engine_property_print_to_stdout>`.
|
|
- **Application > Run > Disable stderr:** Disables logging to standard error entirely.
|
|
This also affects what custom loggers receive. This can be controlled at runtime
|
|
by setting :ref:`Engine.print_error_messages <class_Engine_property_print_error_messages>`.
|
|
- **Debug > Settings > stdout > Verbose stdout:** Enables verbose logging to standard output.
|
|
Prints from :ref:`print_verbose() <class_@GlobalScope_method_print_verbose>` are only
|
|
visible if verbose mode is enabled.
|
|
- **Debug > Settings > stdout > Print FPS:** Prints the frames per second every second,
|
|
as well as the V-Sync status on startup (as it can effectively cap the maximum framerate).
|
|
- **Debug > Settings > stdout > Print GPU Profile:** Prints a report of GPU utilization
|
|
every second, using the same data source as the :ref:`doc_debugger_panel_visual_profiler`.
|
|
|
|
Some of these project settings can also be overridden using
|
|
:ref:`command line arguments <doc_command_line_tutorial>` such as ``--quiet``,
|
|
``--verbose``, and ``--print-fps``.
|
|
|
|
The engine's own file logging is also configurable, as described in the section below.
|
|
|
|
Built-in 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 a 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.
|
|
|
|
Script backtraces
|
|
-----------------
|
|
|
|
Since Godot 4.5, when GDScript code encounters an error, it will log a backtrace that points
|
|
to the origin of the error, while also containing the call stack leading to it. This behavior
|
|
is always enabled when running in the editor, or when the project is exported in debug mode.
|
|
|
|
In projects exported in release mode, backtraces are disabled by default for performance reasons.
|
|
You can enable them by checking **Debug > Settings > GDScript > Always Track Call Stacks** in
|
|
the Project Settings. If you use a custom logging system that reports exceptions to a remote
|
|
service, it's recommended to enable this to make reported errors more actionable.
|
|
|
|
Crash backtraces
|
|
----------------
|
|
|
|
.. warning::
|
|
|
|
Crash backtraces are only useful if they were recorded in a build that
|
|
contains :ref:`debugging symbols <doc_introduction_to_the_buildsystem_debugging_symbols>`.
|
|
Official Godot binaries do not contain debugging symbols, so you must compile a
|
|
custom editor or export template binary to get useful crash backtraces.
|
|
|
|
When the project crashes, a crash backtrace is printed to the standard error stream. This is what
|
|
it can look like in a build with debug symbols:
|
|
|
|
.. code-block:: none
|
|
|
|
================================================================
|
|
handle_crash: Program crashed with signal 4
|
|
Engine version: Godot Engine v4.5.beta.custom_build (6c9aa4c7d3b9b91cd50714c40eeb234874df7075)
|
|
Dumping the backtrace. Please include this when reporting the bug to the project developer.
|
|
[1] /lib64/libc.so.6(+0x1a070) [0x7f6e5e277070] (??:0)
|
|
[2] godot() [0x4da3358] (/path/to/godot/core/core_bind.cpp:336 (discriminator 2))
|
|
[3] godot() [0xdf5f2f] (/path/to/godot/modules/gdscript/gdscript.h:591)
|
|
[4] godot() [0xbffd46] (/path/to/godot/modules/gdscript/gdscript.cpp:2065 (discriminator 1))
|
|
[5] godot() [0x30f2ea4] (/path/to/godot/core/variant/variant.h:870)
|
|
[6] godot() [0x550d4e1] (/path/to/godot/core/object/object.cpp:933)
|
|
[7] godot() [0x30d996a] (/path/to/godot/scene/main/node.cpp:318 (discriminator 1))
|
|
[8] godot() [0x3131a7f] (/path/to/godot/core/templates/hash_map.h:465)
|
|
[9] godot() [0x424589] (/path/to/godot/platform/linuxbsd/os_linuxbsd.cpp:970)
|
|
[10] /lib64/libc.so.6(+0x3575) [0x7f6e5e260575] (??:0)
|
|
[11] /lib64/libc.so.6(__libc_start_main+0x88) [0x7f6e5e260628] (??:0)
|
|
[12] godot() [0x464df5] (??:?)
|
|
-- END OF C++ BACKTRACE --
|
|
================================================================
|
|
GDScript backtrace (most recent call first):
|
|
[0] _ready (res://test.gd:5)
|
|
-- END OF GDSCRIPT BACKTRACE --
|
|
================================================================
|
|
|
|
On the other hand, without debug symbols, it will look like this instead:
|
|
|
|
.. code-block:: none
|
|
|
|
================================================================
|
|
handle_crash: Program crashed with signal 4
|
|
Engine version: Godot Engine v4.5.beta.custom_build (6c9aa4c7d3b9b91cd50714c40eeb234874df7075)
|
|
Dumping the backtrace. Please include this when reporting the bug to the project developer.
|
|
[1] /lib64/libc.so.6(+0x1a070) [0x7fdfaf666070] (??:0)
|
|
[2] godot() [0x4da3358] (??:0)
|
|
[3] godot() [0xdf5f2f] (??:0)
|
|
[4] godot() [0xbffd46] (??:0)
|
|
[5] godot() [0x30f2ea4] (??:0)
|
|
[6] godot() [0x550d4e1] (??:0)
|
|
[7] godot() [0x30d996a] (??:0)
|
|
[8] godot() [0x3131a7f] (??:0)
|
|
[9] godot() [0x424589] (??:0)
|
|
[10] /lib64/libc.so.6(+0x3575) [0x7fdfaf64f575] (??:0)
|
|
[11] /lib64/libc.so.6(__libc_start_main+0x88) [0x7fdfaf64f628] (??:0)
|
|
[12] godot() [0x464df5] (??:0)
|
|
-- END OF C++ BACKTRACE --
|
|
================================================================
|
|
GDScript backtrace (most recent call first):
|
|
[0] _ready (res://test.gd:5)
|
|
-- END OF GDSCRIPT BACKTRACE --
|
|
================================================================
|
|
|
|
This backtrace is also logged to the file for the current session, but it is **not**
|
|
visible in the editor Output panel. Since the engine's scripting system is not running
|
|
anymore when the engine is crashing, it is not possible to access it from scripting in
|
|
the same session. However, you can still read the crash backtrace on the next session
|
|
by loading log files and searching for the crash backtrace string
|
|
(``Program crashed with signal``) using :ref:`class_FileAccess`. This allows you to access
|
|
the backtrace information even after a crash, as long as the user restarts the project
|
|
and file logging is enabled:
|
|
|
|
.. code-block:: gdscript
|
|
|
|
# This script can be made an autoload, so that it runs when the project starts.
|
|
extends Node
|
|
|
|
func _ready() -> void:
|
|
var log_dir: String = String(ProjectSettings.get_setting("debug/file_logging/log_path")).get_base_dir()
|
|
# Get the last log file by alphabetical order.
|
|
# Since the timestamp is featured in the file name, it should always be the most recent
|
|
# log file that was rotated. The non-timestamped log file is for the current session,
|
|
# so we don't want to read that one.
|
|
var last_log_file: String = log_dir.path_join(DirAccess.get_files_at(log_dir)[-1])
|
|
var last_long_contents: String = FileAccess.get_file_as_string(last_log_file)
|
|
|
|
var crash_begin_idx: int = last_long_contents.find("Program crashed with signal")
|
|
if crash_begin_idx != -1:
|
|
print("The previous session has crashed with the following backtrace:\n")
|
|
print(last_long_contents.substr(crash_begin_idx))
|
|
|
|
You can customize the message that appears at the top of the backtrace using the
|
|
**Debug > Settings > Crash Handler > Message** project setting. This can be used
|
|
to point to a URL or email address that users can report issues to.
|
|
|
|
Creating custom loggers
|
|
-----------------------
|
|
|
|
Since Godot 4.5, it is possible to create custom loggers. This custom logging can
|
|
be used for many purposes:
|
|
|
|
- Show an in-game console with the same messages as printed by the engine,
|
|
without requiring other scripts to be modified.
|
|
- Report printed errors from the player's machine to a remote server.
|
|
This can make it easier for developers to fix bugs when the game is already released,
|
|
or during playtesting.
|
|
- Integrate a dedicated server export with monitoring platforms.
|
|
|
|
A custom logger can be registered by creating a class that inherits from :ref:`class_logger`,
|
|
then passing an instance of this class to :ref:`OS.add_logger <class_OS_method_add_logger>`,
|
|
in a script's :ref:`_init() <class_Object_private_method__init>` method. A good place to do this
|
|
is an :ref:`autoload <doc_singletons_autoload>`.
|
|
|
|
The class must define two methods: :ref:`_log_message() <class_Logger_private_method__log_message>`
|
|
and :ref:`_log_error() <class_Logger_private_method__log_error>`.
|
|
|
|
Here is a minimal working example of a custom logger, with the script added as an autoload:
|
|
|
|
.. code-block:: gdscript
|
|
|
|
extends Node
|
|
|
|
class CustomLogger extends Logger:
|
|
# Note that this method is not called for messages that use
|
|
# `push_error()` and `push_warning()`, even though these are printed to stderr.
|
|
func _log_message(message: String, error: bool) -> void:
|
|
# Do something with `message`.
|
|
# `error` is `true` for messages printed to the standard error stream (stderr) with `print_error()`.
|
|
# Note that this method will be called from threads other than the main thread, possibly at the same
|
|
# time, so you will need to have some kind of thread-safety as part of it, like a Mutex.
|
|
pass
|
|
|
|
func _log_error(
|
|
function: String,
|
|
file: String,
|
|
line: int,
|
|
code: String,
|
|
rationale: String,
|
|
editor_notify: bool,
|
|
error_type: int,
|
|
script_backtraces: Array[ScriptBacktrace]
|
|
) -> void:
|
|
# Do something with the error. The error text is in `rationale`.
|
|
# See the Logger class reference for details on other parameters.
|
|
# Note that this method will be called from threads other than the main thread, possibly at the same
|
|
# time, so you will need to have some kind of thread-safety as part of it, like a Mutex.
|
|
pass
|
|
|
|
# Use `_init()` to initialize the logger as early as possible, which ensures that messages
|
|
# printed early are taken into account. However, even when using `_init()`, the engine's own
|
|
# initialization messages are not accessible.
|
|
func _init() -> void:
|
|
OS.add_logger(CustomLogger.new())
|
|
|
|
Note that to avoid infinite recursion, you cannot effectively use
|
|
:ref:`print() <class_@GlobalScope_method_print>` and its related methods in
|
|
``_log_message()``. You also can't effectively use
|
|
:ref:`push_error() <class_@GlobalScope_method_push_error>`
|
|
or :ref:`push_warning() <class_@GlobalScope_method_push_warning>` in
|
|
``_log_error()``. Attempting to do so will print a message to the same stream
|
|
as the original message. This message is not available in the custom logger,
|
|
which is what prevents infinite recursion from occurring:
|
|
|
|
.. code-block:: none
|
|
|
|
While attempting to print a message, another message was printed:
|
|
...
|
|
|
|
While attempting to print an error, another error was printed:
|
|
...
|
|
|
|
.. seealso::
|
|
|
|
You can find an example of an in-game console built with a custom logger in the
|
|
`Custom Logging demo project <https://github.com/godotengine/godot-demo-projects/tree/master/misc/custom_logging>`__.
|