Add the core::log facade with five levels and a sink; migrate the app dev log and enable trace in --dev. Replace the dropped cubes with a four-wheel cart on revolute joints driven by velocity motors, add WASD controls, a golden trajectory and a slope test. Instrument idle frame spikes and throttle the window title. Add chunked terrain LOD with skirts (2368 vs 8192 triangles) while physics keeps the full mesh. Pin Rust 1.100.0; edition stays 2024.
136 lines
8.1 KiB
Markdown
136 lines
8.1 KiB
Markdown
# Логи и настройки
|
||
|
||
Диагностика не должна мешать симуляции: оверлей и логи — наблюдатели. Их включение
|
||
не меняет шаг, порядок подсистем и результат (DETERMINISM.md). Время смотрят только
|
||
`app` и логи; в симуляции по-прежнему `SimTime`.
|
||
|
||
Правила для кода — в [CODE_RULES.md](CODE_RULES.md), раздел «Логирование».
|
||
|
||
## Фасад `core::log`
|
||
|
||
Библиотеки пишут через `fabrilis_core::log`, а не через `println!` и не через
|
||
внешний `log`/`tracing` (D35):
|
||
|
||
```rust
|
||
use fabrilis_core::log::{info, warn};
|
||
|
||
info!("world", "terrain seed={} size={}", seed, size);
|
||
warn!("physics", "solver degraded: iterations={}", iterations);
|
||
```
|
||
|
||
Первый аргумент макроса — target (подсистема), дальше обычный `format!`-шаблон.
|
||
Уровни: `error`, `warn`, `info`, `debug`, `trace`. Аргументы не вычисляются и не
|
||
форматируются, если уровень выключен или приёмник не установлен. `Record`
|
||
заимствует target и сообщение; аллокацию делает приёмник.
|
||
|
||
Приложение ставит приёмник один раз до стартового баннера:
|
||
`app` открывает dev-лог по `--log` (или `--dev`) и регистрирует `DevLogSink`.
|
||
`--dev` включает `trace`, обычный запуск — `info`. Без файла приёмника нет, и
|
||
фасад молчит, не создавая файлов.
|
||
|
||
## Оверлей
|
||
|
||
Поверх кадра показывается панель (левый верхний угол выбран для M4d):
|
||
|
||
| Поле | Смысл |
|
||
|---|---|
|
||
| FPS | кадров в секунду за окно ~1 с |
|
||
| TPS | шагов физики в секунду, реально выполненных |
|
||
| frame ms | среднее и максимум времени кадра за окно |
|
||
| physics ms | среднее и максимум времени шага/пачки шагов физики |
|
||
| render ms | среднее время отрисовки |
|
||
| RTF | simulated / wall, как в заголовке окна |
|
||
| CPU | загрузка процесса, % одного ядра |
|
||
| load1 | средняя нагрузка системы за 1 мин |
|
||
| RSS | резидентная память процесса, МБ |
|
||
|
||
Под панелью — график времени кадра за последние ~180 кадров: линия кадра и линия
|
||
физики, авто-масштаб по максимуму, сетка и подписи 0 / max мс. Пики контактов
|
||
(переворот куба, удар) должны быть видны как узкие высокие всплески.
|
||
|
||
Заголовок окна с `RTF` обновляется не чаще раза в секунду: на Wayland каждый
|
||
`set_title` — это запрос композитору, и слать его на каждом кадре незачем. Формат
|
||
заголовка не меняется, «...» остаётся до первого измерения RTF.
|
||
|
||
## Флаги запуска
|
||
|
||
| Флаг | Что делает |
|
||
|---|---|
|
||
| `--metrics-log <файл>` | писать метрики в CSV, по строке на кадр |
|
||
| `--log <файл>` | писать dev-лог в указанный файл |
|
||
| `--dev` | подробный режим: почти всё в dev-лог; включает метрики-лог, если путь не задан |
|
||
| `--append` | дописывать в конец вместо перезаписи |
|
||
|
||
По умолчанию логи выключены. Файлы **перезаписываются при старте**; `--append`
|
||
нужен только для накопления между запусками. Флаги командной строки важнее
|
||
переменных окружения.
|
||
|
||
Переменные окружения: `FABRILIS_METRICS_LOG`, `FABRILIS_LOG`, `FABRILIS_DEV=1`.
|
||
|
||
## Метрики-лог (CSV)
|
||
|
||
Заголовок один раз, строка на кадр, сброс на диск раз в секунду:
|
||
|
||
```text
|
||
unix_s,t_s,frame,fps,tps,frame_ms,frame_max_ms,physics_ms,physics_max_ms,render_ms,rtf,cpu_pct,load1,rss_mb,spike
|
||
```
|
||
|
||
- `unix_s` — wall-clock начала кадра, секунды;
|
||
- `t_s` — время симуляции, секунды;
|
||
- `spike` — `1`, если кадр превысил бюджет (например, 20 мс) или шаг физики был
|
||
дольше 1 мс;
|
||
- остальные поля — как в оверлее.
|
||
|
||
CSV открывается таблицей, pandas и gnuplot. Приватных данных, кроме путей и имени
|
||
GPU в dev-логе, нет.
|
||
|
||
## Dev-режим
|
||
|
||
`--dev` включает уровень `debug/trace` и пишет в текстовый лог:
|
||
|
||
- версии Rust/движка, ОС, адаптер GPU, драйвер, формат поверхности;
|
||
- параметры окна, масштаб, размер буфера;
|
||
- seed, конфигурацию и хеш рельефа;
|
||
- созданные тела, коллайдеры, массы, стартовые позы;
|
||
- параметры камеры и изменения управления (без покадрового шума);
|
||
- раз в секунду — сводку метрик;
|
||
- каждый пик: номер кадра, время кадра и физического шага, время фаз `render_ms`,
|
||
`overlay_ms`, `title_ms`, стоимость чтения `/proc` `metrics_us`, число шагов
|
||
(`steps`) и причину (`frame`/`physics`/`frame+physics`);
|
||
- ошибки wgpu/Rapier с контекстом.
|
||
|
||
Строка пика выглядит так:
|
||
|
||
```text
|
||
frame=4517 frame_ms=1873.22 physics_step_ms=0.124 render_ms=1.29 overlay_ms=0.05 title_ms=0.01 metrics_us=99 steps=50 trigger=frame
|
||
```
|
||
|
||
Поля позволяют сразу отделить виновника. `render_ms` включает блокирующий захват
|
||
surface, поэтому в ровном режиме он близок к одному интервалу vsync (~13 мс при
|
||
75 Гц). Если `frame_ms` заметно больше суммы фаз, а `render_ms` остаётся в норме,
|
||
кадр задержался вне приложения: оно ждало callback композитора (пропуск vsync,
|
||
внешняя нагрузка). Если растёт `physics_step_ms` — виновата симуляция, если
|
||
`overlay_ms` — сборка панели, `metrics_us` — чтение `/proc` (обычно ~0.1 мс, то
|
||
есть шум). Большой `render_ms` вместе с большим `frame_ms` — блокировка на
|
||
захвате поверхности или в драйвере GPU.
|
||
|
||
Пик логируется отдельной строкой, поэтому «лаг в момент переворота» можно найти в
|
||
логе, а не только на графике.
|
||
|
||
## Настройки (XDG, позже)
|
||
|
||
Постоянные личные настройки планируются отдельно от проекта (STORAGE.md):
|
||
|
||
```text
|
||
~/.config/fabrilis/settings.ron
|
||
```
|
||
|
||
Поля: `overlay`, `metrics_log`, `log`, `level`, `dev`. Пока достаточно флагов и
|
||
переменных окружения; файл настроек добавим, когда появится UI настроек.
|
||
|
||
## Проверка
|
||
|
||
- Golden-хеш симуляции совпадает при включённом и выключенном оверлее/логе.
|
||
- Парсеры `/proc/self/stat`, `/proc/loadavg`, `/proc/self/status` — чистые функции
|
||
с тестами на битые строки (возвращают 0/None, не паникуют).
|
||
- Метрики-лог не пишется, пока флаг не задан.
|