fabrilis/docs/LOGGING.md
loki5512344 1042269d7e
Finish M4: cart, log facade, idle diagnostics and terrain LOD
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.
2026-11-17 14:32:52 +01:00

136 lines
8.1 KiB
Markdown
Raw Permalink 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), раздел «Логирование».
## Фасад `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, не паникуют).
- Метрики-лог не пишется, пока флаг не задан.