Профілювання

Defold містить інструменти профілювання, інтегровані з рушієм і процесом збирання. Вони допомагають виявляти проблеми з продуктивністю, пам’яттю та використанням ресурсів. Дані профілювання під час виконання можна переглядати за допомогою кількох засобів:

• Базовий профайлер і вбудований у гру візуальний профайлер доступні на всіх платформах.
• Профайлер Remotery та інтерактивний вебпрофайлер кадрів доступні на настільних і мобільних платформах.
• Налагоджувальні збірки macOS із Metal можуть зберігати траси GPU для інспектування в Xcode.
• Збірки HTML5 можуть передавати області профілювання (scopes) Defold до Web Performance API браузера.

Налаштування Profiler у маніфесті застосунку (App Manifest) визначає, чи включається код профайлера до збірки під час компонування. Типове значення — Debug Only, значення None виключає цей код, а Always включає його як до налагоджувальних збірок, так і до збірок випуску. Налаштування profiler у game.project керують поведінкою під час виконання, але не повертають виключений код профайлера до збірки. Зокрема, Track CPU керує збором вибірок використання CPU; воно задається окремо від вибору в App Manifest.

Візуальний профайлер середовища виконання

Збірки з підтримкою профайлера містять візуальний профайлер середовища виконання, який відображає поточну інформацію поверх запущеного застосунку:

function on_reload(self)
    -- Toggle the visual profiler on hot reload.
    profiler.enable_ui(true)
end

Візуальний профайлер надає низку функцій, за допомогою яких можна змінювати спосіб відображення його даних:

profiler.set_ui_mode()
profiler.set_ui_view_mode()
profiler.view_recorded_frame()

Докладніше про функції профайлера див. у довіднику API профайлера.

Вебпрофайлер

Під час роботи настільної або мобільної збірки з підтримкою профайлера інтерактивні профайлери кадрів і ресурсів доступні через браузер.

Профайлер кадрів Remotery

Профайлер кадрів дає змогу збирати вибірки даних під час роботи гри та докладно аналізувати окремі кадри. Щоб відкрити профайлер:

1. Запустіть гру на цільовому пристрої.
2. Виберіть пункт меню Debug ▸ Open Web Profiler.

Профайлер кадрів поділено на кілька розділів, кожен з яких показує запущену гру з іншого боку. Натисніть кнопку Pause у верхньому правому куті, щоб тимчасово зупинити оновлення подань профайлера.

INFO:ENGINE: Defold Engine 1.3.4 (80b1b73)
INFO:DLIB: Initialized Remotery (ws://127.0.0.1:17815/rmt)
INFO:ENGINE: Loading data from: build/default

Часова шкала вибірок (Sample Timeline)

Подання Sample Timeline показує кадри даних, зібраних у рушії, — по одній горизонтальній часовій шкалі для кожного потоку. Main — це головний потік, у якому виконується вся ігрова логіка та більшість коду рушія. Remotery — це потік самого профайлера, а Sound — потік змішування й відтворення звуку. Ви можете збільшувати й зменшувати масштаб (коліщатком миші) та вибирати окремі кадри, щоб переглянути докладні дані кадру в поданні Frame Data.

Дані кадру (Frame Data)

Подання Frame Data — це таблиця, у якій докладно наведено всі дані поточного вибраного кадру. Ви можете переглянути, скільки мілісекунд витрачено в кожній області профілювання рушія.

Глобальні властивості (Global Properties)

Подання Global Properties показує таблицю лічильників. З їхньою допомогою легко, наприклад, відстежувати кількість викликів малювання або кількість компонентів (components) певного типу.

Профайлер ресурсів

Профайлер ресурсів дає змогу інспектувати гру під час її роботи й докладно аналізувати використання ресурсів. Щоб відкрити профайлер:

1. Запустіть налагоджувальну збірку гри на цільовому пристрої.
2. Відкрийте адресу сервісу рушія у браузері: http://<address>:<port>/. Використовуйте адресу й порт, які запущений рушій повідомив у консолі.

Профайлер ресурсів поділено на 2 розділи: один показує ієрархію колекцій (collections), ігрових об’єктів (game objects) і компонентів, екземпляри яких наразі створено у вашій грі, а інший — усі завантажені ресурси.

Подання колекцій

Подання колекцій показує ієрархічний список усіх ігрових об’єктів і компонентів, екземпляри яких наразі створено у грі, та колекції, з яких вони походять. Цей інструмент дуже корисний, коли потрібно докладно розібратися, які екземпляри створено у грі в певний момент і звідки походять об’єкти.

Подання ресурсів

Подання ресурсів показує всі ресурси, наразі завантажені в пам’ять, їхній розмір і кількість посилань на кожен ресурс. Це корисно під час оптимізації використання пам’яті застосунком, коли потрібно зрозуміти, що саме завантажено в пам’ять у певний момент.

Час завантаження ресурсів

Також можна перевірити, скільки часу завантажуються окремі ресурси. Увімкніть Resource → Profile у game.project перед запуском гри. У текстовому поданні це налаштування має такий вигляд:

[resource]
profile = 1

За замовчуванням налаштування вимкнено. Перезапустіть гру після ввімкнення, щоб виміряти початкове завантаження. Кожне завершене або невдале завантаження записує до журналу повідомлення рівня INFO зі шляхом ресурсу, загальним часом і часом етапів preload, read, create, post-create, queue і wait. Звернення до кешу не створюють нових записів завантаження.

У профайлері ресурсів натисніть Capture, а потім Show load times, щоб показати стовпці часу. Capture оновлює подання збережених вимірювань; ця дія не вмикає профілювання й не вимірює попередні завантаження заднім числом.

Показ часу завантаження сортує таблицю за загальним часом, починаючи з найповільніших ресурсів. Натисніть заголовок стовпця часу, щоб сортувати за цим етапом; натисніть знову, щоб змінити порядок. Смуги у стовпці Load показують кожен загальний час відносно найповільнішого видимого ресурсу. Натисніть Hide load times, щоб знову приховати стовпці.

Час завантаження й зворотних викликів включає роботу з вкладеними залежностями. Не підсумовуйте загальний час усіх ресурсів для обчислення часу запуску, оскільки та сама робота може входити до вимірювань кількох ресурсів. Стовпці Preload, Read і Create також не охоплюють увесь час завантаження; додаткові етапи наведено в журналі.

Тире (—) означає, що завершене вимірювання недоступне, наприклад тому, що профілювання було вимкнено або початкове завантаження ще не завершилося. Виміряний нуль показується як 0.000. Вимірювання описують початкове завантаження: звернення до кешу й гарячі перезавантаження їх не змінюють, а вивантаження ресурсу видаляє його збережене вимірювання.

Захоплення трас GPU Metal

HTTP-сервіс рушія може захоплювати команди GPU Metal у документ .gputrace на macOS. Відкрийте завершену трасу в Xcode, щоб інспектувати захоплені кадри. Цю можливість вбудовано в налагоджувальний рушій.

Запуск і перевірка підтримки

Створіть налагоджувальний пакет macOS із включеним нативним графічним бекендом Metal. Якщо використовуєте маніфест застосунку, виберіть варіант Graphics (macOS), що включає Metal; див. графічні бекенди.

Запустіть виконуваний файл пакета з термінала з METAL_CAPTURE_ENABLED=1 і виберіть адаптер Metal. Замініть шлях пакета й назву виконуваного файлу в цьому прикладі:

METAL_CAPTURE_ENABLED=1 \
    "/absolute/path/MyGame.app/Contents/MacOS/MyGame" --graphics-adapter=metal

Змінну середовища потрібно задати під час запуску рушія. Якщо задати її лише в терміналі, з якого надсилаються запити HTTP, це не ввімкне захоплення у вже запущеному рушії.

У другому терміналі використовуйте порт сервісу рушія з журналу. Наступні приклади використовують curl і jq:

ENGINE_URL="http://127.0.0.1:<port>"
curl -fsS "$ENGINE_URL/openapi.json" | jq '.paths["/profiler/gputrace"]'
curl -sS -i "$ENGINE_URL/profiler/gputrace"

Маршрут реєструється лише на macOS. Запис null у документі OpenAPI означає, що цей рушій його не надає. Навіть за наявності маршруту підтримка захоплення залежить від графічного адаптера й середовища запуску. GET /profiler/gputrace повертає HTTP 501 з error.code: "gputrace_unsupported", якщо захоплення Metal недоступне. Перед продовженням перевірте, що рушій використовує Metal і запущений із METAL_CAPTURE_ENABLED=1. Підтримуваний запит повертає HTTP 200 зі станом захоплення.

Захоплення й інспектування кадрів

Виберіть доступний для запису абсолютний вихідний шлях із закінченням .gputrace, наявним батьківським каталогом і без траси за цим шляхом. Шлях розташований на комп’ютері, де працює рушій. Для локального рушія цей приклад створює новий тимчасовий каталог і запитує один кадр:

GPU_TRACE_DIR=$(mktemp -d /tmp/defold-gputrace.XXXXXX)
GPU_TRACE_PATH="$GPU_TRACE_DIR/frame.gputrace"
GPU_TRACE_REQUEST=$(jq -n --arg path "$GPU_TRACE_PATH" '{path: $path, frames: 1}')
curl -fsS -X POST \
    -H 'Content-Type: application/json' \
    --data "$GPU_TRACE_REQUEST" \
    "$ENGINE_URL/profiler/gputrace" | jq

frames необов’язкове, типово дорівнює 1 і приймає цілі числа від 1 до 10000. Захоплення починається перед наступним відрендереним кадром і закінчується після передавання запитаної кількості повних кадрів. Під час очікування гра має продовжувати рендеринг. Лише одне захоплення може очікувати або бути активним; інший запит запуску повертає HTTP 409 з error.code: "gputrace_active".

POST повертає HTTP 200 з ok: true і data.state: "pending", коли захоплення заплановано. Про завершення повідомляють подальші запити стану. Повторюйте запит, доки data.state не стане complete, canceled або failed:

curl -fsS "$ENGINE_URL/profiler/gputrace" | jq

GET описує поточне або останнє захоплення. Перевірте, що data.path відповідає запитаному шляху. Невдале захоплення також повертає HTTP 200 з ok: true; визначайте результат за data.state і data.error. Для автоматизованого клієнта опитуйте стан із затримкою й тайм-аутом.

Після досягнення стану complete відкрийте трасу в Xcode на Mac, де працює рушій:

open -a Xcode "$GPU_TRACE_PATH"

Кінцева точка HTTP повертає стан; траса зберігається за data.path на комп’ютері рушія. Для віддаленого рушія отримайте завершений документ із цього комп’ютера, перш ніж відкривати локально.

Скасування або зупинення захоплення

Щоб скасувати очікуване захоплення або достроково завершити активне:

curl -fsS -X DELETE "$ENGINE_URL/profiler/gputrace" | jq

Очікуване захоплення переходить у canceled. Для активного захоплення data.stop_requested стає true, і воно завершується після передавання поточного відрендереного кадру. Продовжуйте опитувати GET до кінцевого стану. DELETE залишає вже записану трасу на диску. Якщо очікуваного або активного захоплення немає, запит повертає HTTP 409 з error.code: "gputrace_inactive".

Часова шкала продуктивності браузера для HTML5

Для часової шкали в браузері HTML5 використовує Web Performance API замість Remotery. Щоб записати області профілювання Defold:

1. Переконайтеся, що вибраний у App Manifest режим профайлера включає його підтримку до варіанта збірки, який ви запускаєте.
2. Увімкніть Performance Timeline Enabled (profiler.performance_timeline_enabled) у game.project.
3. Запустіть збірку HTML5 і відкрийте інструменти розробника браузера.
4. Запишіть сеанс на панелі Performance браузера та інспектуйте області профілювання Defold на отриманій часовій шкалі.

Ця часова шкала браузера працює окремо як від вбудованого у гру візуального профайлера, так і від інтерактивного вебпрофайлера Remotery.

Звіти про збирання

Під час пакування гри можна створити звіт про збирання. Він дуже корисний для розуміння розміру всіх ресурсів, що входять до пакета гри. Просто встановіть прапорець Generate build report під час пакування гри.

Засіб збирання створить файл report.html поруч із пакетом гри. Відкрийте цей файл у веббраузері, щоб переглянути звіт:

Розділ Overview наочно показує загальний розподіл розміру проєкту за типами ресурсів.

Розділ Resources показує докладний список ресурсів, який можна сортувати за розміром, ступенем стиснення, шифруванням, типом і назвою каталогу. Використовуйте поле «search», щоб фільтрувати відображувані записи ресурсів.

Розділ Structure показує розміри відповідно до того, як ресурси впорядковано у файловій структурі проєкту. Записи позначено кольорами від зеленого (малий розмір) до синього (великий розмір) залежно від відносного розміру файлу та вмісту каталогу.

Зовнішні інструменти

Окрім вбудованих інструментів, існує широкий вибір якісних безкоштовних інструментів трасування й профілювання. Ось деякі з них:

ProFi (Lua)

Ми не постачаємо вбудованого профайлера Lua, але існують зовнішні бібліотеки, якими досить легко користуватися. Щоб з’ясувати, на що ваші скрипти витрачають час, самостійно додайте вимірювання часу у свій код або скористайтеся бібліотекою профілювання Lua, наприклад ProFi.

Зауважте, що профайлери, написані лише мовою Lua, створюють значні накладні витрати з кожним встановленим обробником перехоплення (hook). Тому до отриманих за допомогою такого інструмента профілів часу слід ставитися з певною обережністю. Водночас профілі кількості викликів достатньо точні.

Instruments (macOS та iOS)

Це аналізатор і візуалізатор продуктивності, що входить до складу Xcode. Він дає змогу трасувати та інспектувати поведінку одного чи кількох застосунків або процесів, досліджувати особливості пристрою (наприклад, Wi-Fi і Bluetooth) та багато іншого.

OpenGL profiler (macOS)

Частина пакета «Additional Tools for Xcode», який можна завантажити з сайту Apple (виберіть Xcode ▸ Open Developer Tool ▸ More Developer Tools... у меню Xcode).

Цей інструмент дає змогу інспектувати запущений застосунок Defold і бачити, як він використовує OpenGL. За його допомогою можна трасувати виклики функцій OpenGL, встановлювати точки зупинки на функціях OpenGL, досліджувати ресурси застосунку (текстури, програми, шейдери тощо), переглядати вміст буферів і перевіряти інші аспекти стану OpenGL.

Android Profiler (Android)

https://developer.android.com/studio/profile/android-profiler.html

Набір інструментів профілювання, який збирає в реальному часі дані про використання CPU, пам’яті та мережеву активність вашої гри. Ви можете трасувати методи під час виконання коду на основі вибірок, зберігати дампи купи, переглядати виділення пам’яті та інспектувати подробиці файлів, переданих мережею. Для використання цього інструмента потрібно встановити android:debuggable="true" у AndroidManifest.xml.

Примітка: починаючи з Android Studio 4.1, також можна запускати інструменти профілювання без запуску Android Studio.

Graphics API Debugger (Android)

https://github.com/google/gapid

Це набір інструментів, який дає змогу інспектувати, змінювати й повторно відтворювати виклики застосунку до графічного драйвера. Для використання цього інструмента потрібно встановити android:debuggable="true" у AndroidManifest.xml.