# Логи и настройки Диагностика не должна мешать симуляции: оверлей и логи — наблюдатели. Их включение не меняет шаг, порядок подсистем и результат (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, не паникуют). - Метрики-лог не пишется, пока флаг не задан.