fabrilis/docs/LOGGING.md
loki5512344 93075ab1fd
Some checks failed
ci / check (macos-latest) (push) Has been cancelled
ci / check (ubuntu-latest) (push) Has been cancelled
ci / check (windows-latest) (push) Has been cancelled
Add design persistence, world rendering, metrics overlay and logs
M3: STL/OBJ import with mesh validation, mass/COM/inertia, material database, RON scene with content-addressed blobs and v0->v1 migration. M4: deterministic heightmap terrain, trimesh colliders, wgpu renderer with instancing and depth, winit app with 1 kHz physics, fly camera, on-screen metrics overlay and per-frame CSV/dev logs. Docs: UI, logging, network and headless CLI plans.
2026-11-16 23:34:05 +01:00

93 lines
5.3 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.

# Логи и настройки
Диагностика не должна мешать симуляции: оверлей и логи — наблюдатели. Их включение
не меняет шаг, порядок подсистем и результат (DETERMINISM.md). Время смотрят только
`app` и логи; в симуляции по-прежнему `SimTime`.
Правила для кода — в [CODE_RULES.md](CODE_RULES.md), раздел «Логирование».
## Оверлей
Поверх кадра показывается панель (левый верхний угол выбран для M4d):
| Поле | Смысл |
|---|---|
| FPS | кадров в секунду за окно ~1 с |
| TPS | шагов физики в секунду, реально выполненных |
| frame ms | среднее и максимум времени кадра за окно |
| physics ms | среднее и максимум времени шага/пачки шагов физики |
| render ms | среднее время отрисовки |
| RTF | simulated / wall, как в заголовке окна |
| CPU | загрузка процесса, % одного ядра |
| load1 | средняя нагрузка системы за 1 мин |
| RSS | резидентная память процесса, МБ |
Под панелью — график времени кадра за последние ~180 кадров: линия кадра и линия
физики, авто-масштаб по максимуму, сетка и подписи 0 / max мс. Пики контактов
(переворот куба, удар) должны быть видны как узкие высокие всплески.
## Флаги запуска
| Флаг | Что делает |
|---|---|
| `--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, конфигурацию и хеш рельефа;
- созданные тела, коллайдеры, массы, стартовые позы;
- параметры камеры и изменения управления (без покадрового шума);
- раз в секунду — сводку метрик;
- каждый пик: номер кадра, время кадра, время физики, причина (`contact`/`resize`/`render`);
- ошибки wgpu/Rapier с контекстом.
Пик логируется отдельной строкой, поэтому «лаг в момент переворота» можно найти в
логе, а не только на графике.
## Настройки (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, не паникуют).
- Метрики-лог не пишется, пока флаг не задан.