• Быстрый старт

• Тесты производительности

• ECS Интеграция (по желанию)

• Документация (Продвинутое использование)

• API

• Примеры (прочтите для запуска примеров на Unity 6+)

• Использование в System.Threading.Tasks

• English

Быстрый старт

https://github.com/Elfinik/burst-trace.git

openupm add com.elfinik.burst-trace

"com.elfinik.burst-trace": "https://github.com/Elfinik/burst-trace.git"

Добавьте пространство имен в начало скрипта:

using Elfinik.BurstTrace;

Для захвата стека вызовите метод:

traceHandle = TraceHandle.Capture();

Это вернет структуру TraceHandle. Вы можете передавать и хранить её где угодно. В инспекторе MonoBehaviour (GameObject / ScriptableObject) или в инспекторе Entity вы увидите цепочку вызова из этой переменной:

Каждый лог кликабельный: вы можете нажать мышкой на строчку, и откроется скрипт на нужной линии. Иногда для перехода по гиперссылке в Unity может потребоваться двойной или тройной клик. Вы также можете копировать логи (см. скриншот ниже).

Если переменная пустая, вы увидите Empty (Invalid) log Сейчас в переменной одна строчка. Если вы ходите записать путь из нескольких строк, просто вызовите функцию, передав туда предыдущее значение

traceHandle = TraceHandle.Capture(traceHandle);
//or
traceHandle = TraceHandle.Capture(prevTraceHandle);

Теперь вы увидите 2 строчки. Вы можете запоминать так сколько угодно строк: TraceHandle всегда будет занимать 4 байта. Но обратите внимание: при отображении и выводе показывается только до 64 строк! Это сделано для оптимизации и предотвращения бесконечного цикла. Если вы хотите вывести цепочку вызова в консоль, вызовите

Debug.Log(traceHandle.ToProjectLink());

Это выведет в консоль такой же текст, как в инспекторе. На него также можно нажать для открытия файла

Если по какой-то причине вам нужно вывести лог в консоль внутри Burst-кода, вызовите

Debug.Log(traceHandle.ToConsoleToken());

Эта функция возвращает FixedString128Bytes с гиперссылкой внутри. В консоль будет выведено CLICK TO PRINT LOG. При нажатии на гиперссылку будет выведен лог с полноценной цепочкой вызова.

Работа в сборке (Build)

BurstTracer работает как в редакторе, так и в сборках. В сборках вместо гиперссылок отображается полный путь к файлам. При необходимости вы можете отправлять эти данные в систему аналитики или логов.

Есть ли генераторы кода и dll?

Нет. Весь код полностью доступен и сам по себе не использует какие-либо генераторы (однако использует стандартные функции компилятора C# для получения пути вызова во время компиляции).

Ограничения

• Инициализация: Происходит после Awake и перед Start первой загруженной сцены.

• Лимит уникальных записей: 1 048 575.

  * Уникальной записью считается вызов функции в файле скрипта. Есть если вы будете многократно вызывать функцию в цикле, но в скрипте это будет одна и та же строчка, это считается одной уникальной записью.

• Лимит вложенных записей: +1 048 575.

  ** Уникальный вложенной лог: это именно уникальная цепочка логов. То есть при создании цепочки из 15 логов внутри цикла, будет создан 1 уникальный лог и 15 уникальных вложенных логов.

• Максимальное количество потоков: 1 основной + 2047 (в стандартном Unity ограничение на 128, так что это число с запасом для кастомных фреймворков).

• Вы можете вызывать запись из любого места (основной поток, Burst, многопоточные задания): это никак не будет влиять на производительность. Однако вы не можете вызывать функции безопасно, если используете кастомный фреймворк для управления потоками. Если вы не используете JobSystem, смотрите раздел 'Custom Multithread framework'.

• Сериализация: В данный момент сериализация TraceHandle между сессиями не поддерживается. При перезапуске приложения старые TraceHandle становятся невалидными.

Использование в System.Threading.Tasks

Если вы хотите использовать BurstTrace многопоточно вне Unity JobSystem (например C# Threading), следуйте отдельной инструкции: Использование вне Unity Jobs

Сравнение с Debug.Log и StackTrace:

BurstTrace: это крайне быстрый способ создания логов, которые могут храниться и работать где угодно. Но взамен он не может автоматически создать всю цепочку вызова.

Подводя итог:

• Если вам нужно получить полный вывод лога в консоль, и вам не нужно хранить его в истории, просто вызовите Debug.Log: это не так быстро, но он сразу захватывает весь StackTrace
• Если вам нужно хранить полный StackTrace внутри управляемого кода C#, вы можете использовать StackTrace. Он медленный, но сразу записывает и хранит весь StackTrace. Так как это ссылочный тип (class), частое создание экземпляров создает нагрузку на сборщик мусора (GC), и приводить к отложенным скачкам производительности.
• Если вам нужно сохранить цепочку или место вызова внутри кода Burst: вам подходит только BurstTracer.
• Если вы хотите сохранить цепочку или место вызова в сущностях (Unity ECS), вам подходит только BurstTracer.
• Если вам нужна максимальная производительность в обычном C# коде, и вы можете вызывать функцию на каждом нужно вам вызове для записи StackTrace, используйте BurstTracer. Он обеспечит колоссальный прирост производительности при записи тысяч логов.

Производительность:

Вызов внутри стандартных средств Unity (основной поток или JobSystem) полностью потокобезопасен. При вызове нет состояний гонки, нет вызова Interlock, весь код совместим с Burst.

Одна запись занимает примерно: 0.002 - 0.005ms (проверки безопасности Unity включены). И ~0.000 в сборке (Burst включен)

Вывод в консоль является очень быстрой, но всё еще отладочной функцией.

Тесты производительности

Вызов 500 событий логирования (результат в ms):

Вместо вызова BurstTrace лога 500, в тестах создается цепочка из 500 логов: то есть вместо использования кэшированных значений, каждый новый лог является новым, создавая цепочку.

* Результат сильно варьируется от теста к тесту: максимум примерно от 800 до 1400 ms

** Так как вызов лога довольно быстрый, само планирования задания оказывает существенное влияние на тесты. Поэтому последний тест запущен с количеством итераций, в 32 раза превышающем остальные.

Нагрузка в тестах Debug.Log также обусловлена выводом логов в консоль, что, очевидно, добавляет огромную нагрузку.

Память

Хотя сам указатель TraceHandle занимает всего 4 байта, саму строку нужно хранить в виде текста.

Одна уникальная запись потребляет в среднем от 1 до 20 КБ.

Если вы создаете лог из главного потока или только 1 раз, запись будет занимать 1 КБ Если вы создаете лог из многопоточного задания, и делаете это много раз, он может занимать до 20 КБ, или больше на устройствах с очень большим количеством потоков.

Одна уникальная запись вложенного лога (цепочки) также занимает примерно от 16 до 320 байт

По умолчанию выделяется 20МБ памяти, что должно хватить для записи 1024-х строк логов. Вы можете изменить это значение (например уменьшить для мобильных платформ) в ProjectSettings > BurstTrace

Модульные тесты

Вы можете увидеть и выполнить в проекте модульные тесты. Обратите внимание: иногда тест может бесконечно выполняться. Просто отмените его и запустите заново. Похоже, это баг, связанный с запуском JobSystem внутри модульных тестов. Обычно в этом случае вы видите в консоли Warning сообщение.

Некоторые тесты тяжелые и из-за них редактор может зависнуть на несколько секунд (или минут, если устройство очень слабое)

ECS Интеграция

	Автоматическая поддержка: Вы можете использовать этот пакет с ECS без дополнительных настроек. TraceHandle корректно отображается в инспекторе Entity.

Лицензия (MIT) / License (MIT)

This project is licensed under the MIT License.

You are free to use this library in personal and commercial projects.

⚠️ Restriction on Resale: While the MIT license permits commercial use, you are not allowed to resell this source code as a standalone asset (e.g., on the Unity Asset Store or similar platforms) without substantial modification or added value. The intent of this license is to allow developers to use the tool in their games/apps, not to enable asset flipping.

See the LICENSE file for the full text.

Credits

Core Implementation The core code is hand-written and based on my personal R&D over the last year. It utilizes internal APIs from Unity.Collections and Unity.Entities (for the Inspector integration).

AI Assistance The following components were generated with the assistance of Google Gemini (with manual review and refinement):

• Unit Tests
• Demo Scripts
• Documentation & Code Comments
• Logo design