Files
airdef/docs/measurements/issue-147-cpu-profile/README.md
T
chexit 1a82742744
build / mod (push) Failing after 28s
CPU timeline profile of the battle frame (#147 step 3.1, #126 D/E)
Measure-first profile naming the culprit with data; no worker implemented
(step 3.2 is out of scope). docs/measurements/issue-147-cpu-profile/: README +
report-server.json (default server-thread path) + report-inframe.json
(--in-frame control), M5/Metal 2560x1440 HD, same-recording battle with
overlapping raids + explosions + dense smoke, each run serialized under the
shared flock /tmp/airdef-bench.lock (earlier concurrent runs discarded).

Instrumentation: host per-tick tick_mods spans (ground/world/snapshot/wasm/
models/output/total, HORIZON_MOD_CPU_PROFILE=1, attributed by tick+frame),
mod Sim::step phase timing via an adapter-injected monotonic clock
(game.monotonic-nanos, API level 32; airdef-core stays SDK-free), raid_bench
--scheduler + per-frame span/frame correlation + mod phase delta.

Findings: on the default path the battle frame is GPU-bound (GPU avg 73.7ms ~
frame p95 88ms; 127/128 frames >33ms); the mod path is ~2.5ms/tick, per-frame
p99 7.7ms, 0 frames >25ms, host world answers <0.1ms, model prep ~0.05ms; the
872ms CPU spike is a render/GPU hitch (mod 2.15ms). In-frame is CPU-bound
(CPU p99 175ms); the mod path reaches >25ms in 27 frames, and step_drones
dominates Sim::step (52%, max 47ms/tick), A* only 15%. The schedulers' mod
peaks do not coincide; only the render-dominated catch-up spike is common.

Recommendation: a pure A* route worker and a world-snapshot worker are NOT
justified (A* leads only the tiny default-path mod; world answers never lead).
Default-path peaks are GPU -> steps 1-2 (GPU/geometry) apply, a CPU worker
would not help. If targeting in-frame CPU, the unit is the whole Sim::step
(Wasmtime on its own thread), not a route worker — still not implemented.

Harness fix (engine gitlink 48eff0fcb): control-socket chat/chat-log now reach
the client mod on the server-thread path (chat-box parity), enabling the
required default-path battle measurement; sim rules untouched.

Tests: airdef-core 326 passed/0 failed/8 ignored; airdef-mod 113+1+2+5 passed
incl. same_seed_same_result and combat_trace_is_deterministic;
tools/test_raid_bench.py 11 passed; horizon-mods suite + wasm ABI test ok.

Engine: d073783f5 (spans + clock) + 48eff0fcb (chat harness) on
agent/126-cpu-profile. Parent: 92c058f60 (profiler + driver) + this commit.

Co-Authored-By: Kimi Code <noreply@moonshot.ai>
2026-11-21 13:35:32 +03:00

258 lines
19 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Issue #147, шаг 3.1: CPU-профиль боевого кадра — кто виноват (#126 D/E)
> Основа: engine `3428a571b` + instrumentation-коммит `d073783f5` (ветка
> `agent/126-cpu-profile`), AirDef `c08b73729` + `92c058f60`. Замер — только
> инструментация: правила симуляции, частоты, лимиты и точность не менялись.
> Worker НЕ реализован (это шаг 3.2, вне scope): задача — измерить и назвать
> виновника по данным, затем рекомендовать первого worker'а.
## Что инструментировано
### Хост: спаны `tick_mods` (engine, `HORIZON_MOD_CPU_PROFILE=1`)
`crates/horizon-client/src/game/mods.rs`: один record на игровой тик, в порядке
исполнения на потоке кадра:
| span | что меряется |
|---|---|
| `ground` | ответы `mod_ground(x,z)` → `answer_ground` (цикл ground-запросов) |
| `world` | `answer_mod_world()` — rays/sections + упаковка (`mod_world.rs`) |
| `snapshot` | `mod_snapshot()` + `set_snapshot` + resolver/acoustics setup |
| `wasm` | `mods.tick(self.ticks)` — wall-time всего WASM-тика (включая `Sim::step`) |
| `models` | `refresh_mod_trees` + `update_mod_models` (подготовка моделей) |
| `output` | `show_mod_output` |
| `total` | весь `tick_mods` (включая `sync_mod_sources`) |
Каждый record несёт `tick` (номер игрового тика) и `frame` — индекс кадра в
сырых массивах `FrameStats` (`frame_ms`/`cpu_ms`/`gpu_ms`), чтобы спаны
соединялись с trace кадров. Гейтинг как у fuel-профиля (выключено по умолчанию,
`OnceLock` по env); запись ограничена `1<<16` тиков (~54 мин). `stats` отдаёт
`mod_cpu` (перцентили по span'ам), `stats raw` — `mod_cpu_ticks` (сырые records);
`stats reset`/`bench` очищают. Overhead выключенного профиля — несколько чтений
часов на тик (как у существующего frame-timing).
### Гость: фазы `Sim::step` (мод, `sim::profile`)
`airdef-mod/src/sim/profile.rs` + `Sim::step`: named-фазы `plan` (plan_step/A*),
`adapt`, `drones` (step_drones), `moves` (step_moves), `sight` (update_sight/радар),
`sams` (step_sams/пуск), `record`, плюс весь `step` и `other` (step минус named).
Счётчики фиксированного размера, per-thread, не читают randomness и не меняют
решений → упорядоченный combat trace идентичен.
Симуляция остаётся SDK-независимой (она же собирается как `airdef-core`):
адаптер ставит хостовые часы `game.monotonic-nanos` (новый WIT-import, API level
32) в `init`; нативные тесты используют `std::time::Instant`. `/airdef stats`
выводит фазы как `PROFILE key=value` chat-строки (мс, totals и per-step maxima),
сброс при открытии нового мира.
### Harness-фиксы control-сокета (не симуляция)
Чтобы замерять бой на пути по умолчанию (server-thread), control-сокет должен
вести себя как чат-бокс игрока. Два минимальных фикса `game/control.rs` (правила
сима, частоты, лимиты и combat-решения не тронуты; in-frame путь не изменился):
- `chat`: в remote-режиме шёл напрямую `send_chat` на сервер, минуя перехват
клиент-мод-команд (`handle_chat_input` → `mod_command`). Теперь как в чат-боксе:
клиент-мод-команда перехватывается первой, иначе строка уходит на сервер.
Без этого `/airdef deploy|wave|stats` не доходили до клиентского мода в
server-thread (первый прогон: отпечатки null, fuel тика 395K против 12.7M
in-frame — бой не состоялся).
- `chat-log`: в remote-режиме читал сырой буфер соединения `remote_chat`, где нет
строк клиентского мода (они идут в `ui.chat` через `add_mod_chat_line`; серверные
строки зеркалируются в `ui.chat` через `chat_line`). Теперь читает `ui.chat` —
чат, который видит игрок, включая feedback мода. `status.chat` (`remote_chat`)
не тронут.
### Драйвер: `tools/raid_bench.py`
- `--scheduler in-frame|server-thread` — два пути single-player, замеряются
РАЗДЕЛЬНО (требование issue). `in-frame`: окно само тикает мир;
`server-thread` (путь по умолчанию): интегрированный сервер на своём потоке,
окно — клиент (`tick_remote` → `tick_mods` синхронно перед prep кадра).
- `HORIZON_MOD_CPU_PROFILE=1` в env прогона.
- `mod_cpu_ticks` соединяются с trace кадров (`mod_cpu_frames`): per-frame total
мод-пути, его p50/p95/p99/max, счётчики кадров >25/33 мс, и что несут худшие 1%
CPU-кадров (avg mod total/wasm/world/models, сколько из них с мод-тиком) —
совпадают ли пики мод-пути с пиками кадров.
- Мод-фазы читаются на idle_warm и после боя; `mod_phases_battle_delta` =
cumulative-после-боя минус cumulative-idle (изолирует бой).
## Стенд и методика
- Apple M5 (10 ядер), macOS, Metal 4. 5600X/RTX 3060 — pending (как #126/#147).
- 2560×1440 offscreen (окно 1280×720 @2x), HD (`/airdef shader hd`),
`HORIZON_HD_SCALE=1`, `HORIZON_NO_AUDIO=1`, `HORIZON_SPIKES=0`,
`HORIZON_MOD_FUEL_PROFILE=1`, `HORIZON_MOD_CPU_PROFILE=1`.
- Мир `Polygon` (копия `run-home/saves/Polygon`), свежий `HORIZON_HOME` на прогон.
Камера `tp @s 40 76 40 135 25`, `time set 6000`, время/погода заморожены,
`weather clear`, creative, HUD скрыт — сцена #126/#147.
- Бой по фиксированным тикам (`BATTLE_SCHEDULE`: 14 батарей, волны shahed 40/160,
kh101 16/180, mix 24/140 — перекрывающиеся налёты + взрывы + плотный дым),
окно замера battle 10 с в середине боя (в потоке). Отпечаток — `airdef stats`
на тиках 400/800/1200/1400.
- Fuel — отдельный сигнал (не включает хост/GPU работу): `mod_fuel` по callback.
- **Сериализация замера**: каждый запуск клиента обёрнут в эксклюзивный
`flock -x` на общем `/tmp/airdef-bench.lock` (другой агент использует тот же
lock): `( flock -x 200; python3 tools/raid_bench.py … ) 200>/tmp/airdef-bench.lock`.
Только один клиент в системе за раз; перед стартом внутри lock ожидается
очистка `pgrep 'horizon-client --world'`. Ранние прогоны, шедшие конкурентно с
клиентом другого агента, признаны невалидными и отброшены; ниже — чистые
замеры под lock. `flock` доставлен через `brew install flock` (0.4.0).
```sh
python3 tools/raid_bench.py --scheduler server-thread --label m5-server --out run-home-bench/out/147-cpu-server
python3 tools/raid_bench.py --scheduler in-frame --label m5-inframe --out run-home-bench/out/147-cpu-inframe
```
## Результаты (M5/Metal, 2560×1440 HD, чистые замеры под flock)
Два раздельных прогона, каждый под эксклюзивным lock: `report-server.json`
(server-thread, путь по умолчанию) и `report-inframe.json` (`--in-frame`,
контроль). Бои реальные: server fp400 — 14 ПВО, 40 сбитых; in-frame fp400 —
14 ПВО, 37 дронов в воздухе, 20 сбитых. **Бои двух планировщиков расходятся по
таймингу событий** (стриминг/акустика; методика #147) — отпечатки разные,
поэтому totals фаз между ними не сравнимы как «один бой»; сравним вклад
мод-пути в пики кадров каждого планировщика.
### Боевой кадр: frame / CPU / GPU (окно battle 10 с)
| метрика, мс | server-thread | in-frame |
|---|---|---|
| кадров в окне | 128 | 103 |
| frame avg / p50 | 78.9 / 73.3 | 97.7 / 70.5 |
| frame p95 / p99 / max | 88.4 / 94.9 / 880.4 | 171.9 / 182.6 / 742.8 |
| **CPU** avg / p50 | 36.4 / 29.5 | 94.3 / 71.4 |
| **CPU p95 / p99** / max | **38.8 / 46.7** / 872.3 | **167.9 / 175.4** / 734.9 |
| **GPU** avg / p95 / p99 | 73.7 / 89.1 / 92.5 | 53.2 / 69.5 / 78.6 |
| кадров >25 мс | 128/128 | 103/103 |
| кадров >33 мс | 127/128 | 103/103 |
| фазы avg: render / tick / update / prepare | 27.0 / 5.95 / 0.3 / 3.1 | 38.2 / 37.4 / 11.6 / 7.1 |
| худший 1% CPU-кадр: render / tick | 449 / 6.8 | 351 / 79.6 |
- **server-thread: кадр GPU-bound.** GPU avg 73.7 мс ≈ frame p95 88 мс; CPU p99
всего 46.7 мс. Почти все кадры >33 мс из-за HD освещения/дыма на 1440p (~74–90 мс
GPU), не из-за CPU мода.
- **in-frame: кадр CPU-bound.** CPU avg 94.3 ≈ frame avg 97.7; GPU avg 53.2 меньше.
Tick-фаза 37.4 мс avg — это Minecraft-сим (мобы/блоки) на потоке кадра + мод;
render-encode 38.2 мс, update 11.6 мс.
- Одиночный catch-up спайк в обоих (server 872 / in-frame 735 мс) —
**render-доминированный** (render-фаза 449 / 351 мс), не мод.
### Мод-путь: спаны `tick_mods` на тик (окно battle, engine `mod_cpu`)
| span, мс | server avg / p95 / p99 / max | in-frame avg / p95 / p99 / max |
|---|---|---|
| ground (ответы земли) | 0.032 / 0.122 / 0.257 / 0.285 | 0.116 / 0.268 / 2.001 / 3.123 |
| world (rays/sections+упаковка) | 0.028 / 0.087 / 0.127 / 0.134 | 0.929 / 4.036 / 6.302 / 6.714 |
| snapshot | 0.031 / 0.042 / 0.052 / 0.072 | 0.114 / 0.107 / 4.070 / 4.222 |
| **wasm (весь WASM-тик)** | 2.322 / 3.200 / 3.491 / 3.630 | 7.930 / 16.869 / 21.422 / 30.226 |
| models (подготовка моделей) | 0.055 / 0.078 / 0.089 / 0.108 | 0.120 / 0.145 / 1.946 / 3.285 |
| output | 0.050 / 0.105 / 0.140 / 0.145 | 0.118 / 0.165 / 2.820 / 3.200 |
| **total мод-путь** | 2.537 / 3.484 / 3.802 / 4.096 | 9.378 / 19.686 / 25.480 / 34.463 |
| тиков в окне | 194 | 156 |
Host world answers (ground+world) и model prep — **ничтожны** на пути по
умолчанию (<0.1 мс/тик); in-frame world заметнее (avg 0.93, p99 6.3 мс), но всё
равно мал против wasm. Мод-путь почти целиком — wasm (`Sim::step` + презентация).
### Совпадение пиков мод-пути с пиками кадров (`mod_cpu_frames`)
| метрика | server-thread | in-frame |
|---|---|---|
| мод-total на кадр p50 / p95 / p99 / max, мс | 3.29 / 6.40 / 7.68 / 14.9 | 10.0 / 33.96 / 38.56 / 38.6 |
| кадров с мод-путём >25 мс | **0** | **27** |
| кадров с мод-путём >33 мс | **0** | **7** |
| худший CPU-кадр: cpu / мод-total / wasm / world, мс | 872 / 2.15 / 2.0 / 0.003 | 735 / 34.5 / 30.2 / 4.0 |
- **server-thread: мод-путь НИКОГДА не превышает 25 мс на кадр** (p99 7.7 мс).
Пик CPU-кадра (872 мс) несёт лишь 2.15 мс мода — спайк не модовый.
- **in-frame: мод-путь >25 мс в 27 кадрах, >33 мс в 7.** Мод — реальный вклад в
CPU-пики, но пик кадра (735 мс) всё равно render-доминированный (мод 34.5 мс).
- **Пики мод-пути двух планировщиков НЕ совпадают**: на пути по умолчанию мод
не создаёт пиков вовсе; in-frame создаёт (бой плотнее + поток кадра уже загружен
симом, wall-time растягивается). Совпадает только природа одиночного
catch-up спайка (render/GPU hitch) и всеобщность >33 мс кадров (HD на 1440p).
### `Sim::step` изнутри: фазы (мод `PROFILE`, delta за весь бой)
Totals за бой (idle→конец), мс; max — худший тик боя. Бои расходятся, поэтому
доли — характеристика каждого планировщика, не сравнение одного боя.
| фаза | server total / max / доля | in-frame total / max / доля |
|---|---|---|
| **drones (step_drones)** | 308.9 / 1.71 / 30% | **1418.8 / 47.05 / 52%** |
| **plan (plan_step, A*)** | **346.5 / 1.40 / 34%** | 397.7 / 31.83 / 15% |
| sight (update_sight, радар) | 173.3 / 1.00 / 17% | 412.0 / 26.81 / 15% |
| other (нетименованное) | 87.3 / 0.53 / 9% | 196.3 / 4.50 / 7% |
| record | 46.5 / 0.22 / 5% | 156.7 / 10.49 / 6% |
| sams (пуск) | 50.0 / 0.26 / 5% | 120.1 / 5.52 / 4% |
| moves | 3.0 / 0.02 / <1% | 12.1 / 3.67 / <1% |
| adapt | 1.4 / 0.06 / <1% | 2.4 / 0.10 / <1% |
| **step всего** | 1016.8 / 2.52 (1250 тиков) | 2716.1 / 47.18 (2091 тик) |
- **server-thread: A* plan_step — крупнейшая фаза** (34%), но весь `Sim::step`
~0.81 мс/тик (max 2.52) — мод мал.
- **in-frame: step_drones доминирует** (52%, max 47 мс/тик — плотный налёт),
A* лишь третий (15%). Host world answers и model prep не лидируют нигде.
### Fuel (отдельный сигнал, без хост/GPU работы)
`airdef:tick` max_used: server 11.15M, in-frame 20.69M при бюджете 300M,
failures 0. Fuel подтверждает: in-frame бой тяжелее по гостевой работе (больше
дронов/тиков), но это не хостовые world answers и не GPU.
## Виновник и рекомендация первого worker'а (шаг 3.2)
**Виновник пиков боевого кадра на пути по умолчанию (server-thread) — GPU.**
GPU avg 73.7 мс ≈ frame p95 88 мс; 127/128 кадров >33 мс из-за HD
освещения/дыма на 1440p. CPU мода — ~2.5 мс/тик, на кадр p99 7.7 мс, **0 кадров
>25 мс**; host world answers <0.1 мс, model prep ~0.05 мс. Одиночный CPU-спайк
(872 мс) — render/GPU hitch (449 мс render-фаза), мод в нём 2.15 мс.
**Рекомендация по данным (worker НЕ реализован):**
1. **Путь по умолчанию (server-thread): CPU-worker не поможет пикам кадров.**
Мод-путь уже ничтожен и вынесен с симом на серверный поток; пики — GPU.
Применяются **шаги 1–2 таблицы #147 (GPU/геометрия)**: HD дым/освещение,
instancing остальных групп моделей. Route-worker / world-worker здесь не
оправданы данными.
2. **Чистый A* route-worker НЕ оправдан.** A* лидирует лишь в крошечном моде
server-thread (34% от 2.5 мс/тик, на пики кадров не влияет); in-frame A* —
только 15% `Sim::step` (третий после step_drones 52% и sight 15%). Снятие A*
не адресует ни GPU-пики дефолта, ни крупнейшую фазу in-frame.
3. **Batch read-only chunk-snapshot world-worker НЕ оправдан.** Host world
answers не лидируют нигде: <0.1 мс/тик дефолт, avg 0.93 / p99 6.3 мс in-frame
— мало против wasm и GPU.
4. **Если целиться в CPU in-frame-пути — единица offload'а весь `Sim::step`
(Wasmtime на своём потоке), а не A*.** In-frame кадр CPU-bound, мод-путь
>25 мс в 27 кадрах, доминирует step_drones (52%, max 47 мс/тик), тесно
связанный с мутабельным состоянием сима и host world answers — это аргумент
за whole-sim offload (следующий шаг таблицы), **но не за pure route-worker**.
При этом и in-frame пики кадров (p99 175 мс) шире мод-пути (38 мс): Minecraft
сим + render-encode тоже велики, а худший спайк — render. Реалистичное
ожидание от whole-sim worker'а — снятие мод-вклада (~38 мс p99), не устранение
>33 мс кадров (их держит GPU/сим/encode).
**Итог:** данные не поддерживают ни pure A* route-worker, ни world-snapshot
worker как первый шаг. На дефолтном пути виновник — GPU (шаги 1–2); на
in-frame контроле CPU-вклад мода реален, но доминирует step_drones, и
оправданный (если делать) следующий шаг — Wasmtime на отдельном потоке целиком,
не route-worker. Реализация worker'а — вне scope 3.1, не делалась.
## Тесты
- `airdef-core` cargo test: 326 passed, 0 failed (8 ignored); timing-тест
`a_smart_raid_plans_and_flies_in_time` (<200 мс/тик) падает только под
параллельной компиляцией (491 мс тик при загрузке CPU), в изоляции — ok.
- `airdef-mod` cargo test: 113+1+2+5 passed, 0 failed, включая
`same_seed_same_result` и `adapter_reexports_core_and_combat_trace_is_deterministic`.
- `tools/test_raid_bench.py`: 11 passed (7 существующих + 4 новых helper'а).
- `horizon-mods` cargo test: 26 lib + sandbox/api_reference ok (exit 0);
api_reference/api_level: ok; WIT-import аддитивен (старые моды линкуются).
- wasm ABI-тест мода `python3 tools/airdef.py test-wasm`: `wasm_contract.toml`
ok (30 шагов, реальный хост, fuel-лимиты) — `game.monotonic-nanos` работает
end-to-end, failures 0.
- Harness-фикс `chat`/`chat-log` (control.rs) — только control-сокет; sim-тесты
его не касаются (нативные тесты не используют бинарник игры). Determinism
(`same_seed_same_result`, `combat_trace_is_deterministic`) перепроверен после
фикса — ok. Инструментация observation-only: combat trace идентичен.