Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Лісозаготівля

Godot пропонує кілька способів упорядкування та збору повідомлень журналів.

Друк повідомлень

Дивись також

Див. Друк повідомлень для отримання інструкцій щодо друку повідомлень. Вивід, що друкується, загалом ідентичний виводу, що записується в журнал.

Під час запуску проєкту з редактора, редактор відображатиме записаний текст у Вихідна панель.

Параметри проекту

Існує кілька налаштувань проекту для керування поведінкою логування в Godot:

  • Програма > Виконати > Вимкнути стандартний вивід: Повністю вимикає ведення журналу у стандартний вивід. Це також впливає на те, що отримують користувацькі реєстратори. Цим можна керувати під час виконання, встановивши Engine.print_to_stdout.

  • Програма > Виконати > Вимкнути stderr: Повністю вимикає ведення журналу стандартних помилок. Це також впливає на те, що отримують користувацькі реєстратори. Цим можна керувати під час виконання, встановивши Engine.print_error_messages.

  • Debug > Settings > stdout > Verbose stdout: Увімкнення детального журналу в стандартному виводі. Виводи з print_verbose() відображаються лише в разі увімкнення детального режиму.

  • Налагодження > Налаштування > stdout > Друк FPS: Друкує кількість кадрів за секунду щосекунди, а також стан вертикальної синхронізації під час запуску (оскільки це може ефективно обмежити максимальну частоту кадрів).

  • Налагодження > Налаштування > stdout > Друк профілю графічного процесора: Друкує звіт про використання графічного процесора щосекунди, використовуючи те саме джерело даних, що й Візуальний профайлер.

Деякі з цих налаштувань проєкту також можна змінити за допомогою command line arguments, таких як --quiet, --verbose та --print-fps.

Власне ведення журналу файлів двигуна також налаштовується, як описано в розділі нижче.

Вбудоване ведення журналу файлів

За замовчуванням Godot записує файли журналів у user://logs/godot.log на настільних платформах. Ви можете змінити це розташування, змінивши налаштування проекту debug/file_logging/log_path. Журнали ротуються, щоб старі файли були доступні для перевірки. Кожен сеанс створює новий файл журналу, а старий файл перейменовується, щоб містити дату ротації. За замовчуванням зберігається до 5 файлів журналів, що можна налаштувати за допомогою налаштування проекту debug/file_logging/max_log_files.

Реєстрацію файлів також можна повністю вимкнути за допомогою налаштування проекту debug/file_logging/enable_file_logging.

Коли проект аварійно завершується, журнали аварій записуються в той самий файл, що й файл журналу. Журнал аварій міститиме корисний трасування лише в тому випадку, якщо запущений бінарний файл містить символи налагодження або якщо можна знайти файл символів налагодження, що відповідає бінарному файлу. Офіційні бінарні файли не містять символів налагодження, тому для роботи потрібно створити спеціальну збірку. Дивіться Debugging symbols для отримання вказівок щодо компіляції бінарних файлів з увімкненими символами налагодження.

Примітка

Файли журналу для операторів print() оновлюються, коли движок очищає стандартний вивід. Стандартний вивід очищується при кожному виведенні тільки в збігах для налагодження. У проектах, що експортуються в режимі випуску, стандартний вивід очищується тільки при виході з проекту або його аварійному завершенні для підвищення продуктивності, особливо якщо проект часто виводить текст у стандартний вивід.

З іншого боку, стандартний потік помилок (який використовується printerr(), push_error(), і push_warning()) завжди зчищається при кожному друку, навіть у проектах, експортованих у режимі випуску.

Для деяких випадків використання, таких як виділені сервери, може бути бажано, щоб релізні збірки завжди скидали stdout під час друку, щоб служби логування, такі як journald, могли збирати журнали під час виконання процесу. Це можна зробити, увімкнувши application/run/flush_stdout_on_print у налаштуваннях проекту.

Зворотні трасування скриптів

Починаючи з Godot 4.5, коли код GDScript зустрічає помилку, він реєструє зворотний трасування, яке вказує на джерело помилки, а також містить стек викликів, що призвели до неї. Ця функція завжди ввімкнена під час роботи в редакторі або коли проект експортується в режимі налагодження.

У проектах, експортованих у режимі випуску, відстеження зворотного проходження за замовчуванням вимкнено з міркувань продуктивності. Ви можете увімкнути його, встановивши прапорець Debug > Settings > GDScript > Always Track Call Stacks (Налагодження > Налаштування > GDScript > Завжди відстежувати стеки викликів) у налаштуваннях проекту. Якщо ви використовуєте власну систему журналювання, яка повідомляє про винятки віддаленому сервісу, рекомендується увімкнути цю опцію, щоб повідомлення про помилки були більш корисними.

Зворотні трасування аварій

Попередження

Відстеження аварійних ситуацій корисні лише в тому випадку, якщо вони були записані в збірці, що містить debugging symbols. Офіційні бінарні файли Godot не містять символів налагодження, тому для отримання корисних відстежень аварійних ситуацій необхідно скомпілювати власний редактор або експортний шаблон бінарного файлу.

Коли проєкт аварійно завершує роботу, у стандартний потік помилок виводиться трасування аварійного завершення. Ось як це може виглядати у збірці з символами налагодження:

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

З іншого боку, без символів налагодження це виглядатиме так:

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

Цей трасування також записується у файл поточної сесії, але не відображається у панелі виводу редактора. Оскільки система скриптів движка більше не працює під час збою движка, неможливо отримати до неї доступ із скриптів у тій самій сесії. Однак ви все одно можете прочитати трасування збою в наступній сесії, завантаживши файли журналу та знайшовши рядок трасування збою (Program crashed with signal) за допомогою FileAccess. Це дозволяє отримати доступ до інформації про трасування навіть після збою, якщо користувач перезапустить проект і ввімкне журнал файлів:

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

Ви можете налаштувати повідомлення, яке з'являється у верхній частині трасування, за допомогою налаштування проекту Debug > Settings > Crash Handler > Message. Це можна використовувати для вказання URL-адреси або адреси електронної пошти, на яку користувачі можуть надсилати повідомлення про проблеми.

Створення користувацьких логгерів

Починаючи з Godot 4.5, можна створювати власні логери. Ці власні логери можна використовувати для багатьох цілей:

  • Відображати ігрову консоль з тими ж повідомленнями, що й рушій, без необхідності модифікації інших скриптів.

  • Повідомляйте про помилки друку з машини гравця на віддалений сервер. Це може полегшити розробникам виправлення помилок, коли гра вже випущена, або під час ігрового тестування.

  • Інтегруйте експорт виділеного сервера з платформами моніторингу.

Настроюваний логер можна зареєструвати, створивши клас, який успадковує від Logger, а потім передавши екземпляр цього класу до OS.add_logger у методі _init() скрипта. Хорошим місцем для цього є autoload.

Клас повинен визначити два методи: _log_message() і _log_error().

Ось мінімальний робочий приклад користувацького логера зі скриптом, доданим як автозавантаження:

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

Зверніть увагу, що для уникнення нескінченної рекурсії ви не можете ефективно використовувати print() та пов'язані з ним методи в _log_message(). Ви також не можете ефективно використовувати push_error() або push_warning() в _log_error(). Спроба зробити це призведе до виведення повідомлення в той самий потік, що й оригінальне повідомлення. Це повідомлення недоступне в користувацькому логері, що запобігає виникненню нескінченної рекурсії:

While attempting to print a message, another message was printed:
...

While attempting to print an error, another error was printed:
...

Дивись також

Ви можете знайти приклад ігрової консолі, зібраної з використанням власного логера, у Custom Logging demo project.