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

8.1 KiB
Raw Blame History

Логи и настройки

Диагностика не должна мешать симуляции: оверлей и логи — наблюдатели. Их включение не меняет шаг, порядок подсистем и результат (DETERMINISM.md). Время смотрят только app и логи; в симуляции по-прежнему SimTime.

Правила для кода — в CODE_RULES.md, раздел «Логирование».

Фасад core::log

Библиотеки пишут через fabrilis_core::log, а не через println! и не через внешний log/tracing (D35):

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)

Заголовок один раз, строка на кадр, сброс на диск раз в секунду:

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 с контекстом.

Строка пика выглядит так:

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):

~/.config/fabrilis/settings.ron

Поля: overlay, metrics_log, log, level, dev. Пока достаточно флагов и переменных окружения; файл настроек добавим, когда появится UI настроек.

Проверка

  • Golden-хеш симуляции совпадает при включённом и выключенном оверлее/логе.
  • Парсеры /proc/self/stat, /proc/loadavg, /proc/self/status — чистые функции с тестами на битые строки (возвращают 0/None, не паникуют).
  • Метрики-лог не пишется, пока флаг не задан.