58 lines
3.6 KiB
Markdown
58 lines
3.6 KiB
Markdown
---
|
|
id: DEC-0005
|
|
title: "Decisão - [PERF] Modelo de Telemetria Push-based"
|
|
status: closed
|
|
created: 2026-03-27
|
|
resolved: 2026-03-27
|
|
agenda: AGD-0007
|
|
tags: []
|
|
---
|
|
|
|
# Decisão - [PERF] Modelo de Telemetria Push-based
|
|
|
|
## Status
|
|
|
|
**Fechada (Closed)** - Consensus reached. Implementation approved.
|
|
|
|
## Contexto
|
|
|
|
O runtime atual (`VirtualMachineRuntime::tick()`) realiza a coleta de telemetria de asset banks (`gfx` e `audio`) em todos os *host ticks*. Essa coleta envolve a chamada de `bank_info()` no `AssetManager`, que executa uma varredura $O(n)$ sobre mapas de recursos e adquire múltiplos locks de leitura. Em hardwares limitados (handhelds), esse custo repetitivo no caminho quente degrada a performance desnecessariamente, mesmo quando o sistema está estável ou em pausa.
|
|
|
|
## Decisão
|
|
|
|
1. **Modelo de Contadores no Driver e Runtime:** O `AssetManager`, a `Heap` da VM e o `LogService` devem substituir a varredura/contagem total por **contadores atômicos** (`used_bytes`, `inflight_bytes`, `slots_occupied`, `logs_count`) para cada subsistema. Esses contadores serão atualizados incrementalmente ($O(1)$) em cada mutação (load, commit, alloc, free, log).
|
|
2. **Snapshot Obrigatório de Fim de Frame:** O runtime capturará o estado desses contadores (Banks, Heap e Logs) **apenas uma vez** por fechamento de frame lógico (`FrameSync` ou `EndOfRom`). Este snapshot será usado para alimentar a `telemetry_last` e o `certifier`.
|
|
3. **Coleta sob Demanda (Inspection Mode):** A coleta em cada *host tick* será reativada **somente** se o novo sinalizador `inspection_active: bool` do runtime for verdadeiro.
|
|
4. **Desacoplamento do Certifier:** A ativação do `certifier` não habilitará mais a telemetria detalhada em cada tick. O certifier será servido exclusivamente pelos snapshots de fim de frame lógico.
|
|
|
|
## Rationale
|
|
|
|
* **Performance:** Reduz o custo do tick do runtime de $O(n)$ com locks para $O(1)$ sem locks no modo normal.
|
|
* **Observabilidade:** Mantém dados precisos para o overlay (via modo inspeção) e dados válidos para o certifier (via snapshot de frame).
|
|
* **Modularidade:** Desacopla as necessidades de depuração (Overlay F1) das necessidades de validação normativa (Certifier).
|
|
|
|
## Invariantes / Contrato
|
|
|
|
* O `AssetManager` é a única fonte da verdade para o uso de memória de assets; o runtime não deve tentar calcular esses valores manualmente.
|
|
* Contadores atômicos garantem que o runtime possa ler estatísticas de bancos sem travar mutações em andamento (consistência eventual).
|
|
* A defasagem de até 1 frame lógico é aceitável para métricas de assets bank no modo de operação normal.
|
|
|
|
## Impactos
|
|
|
|
* **Drivers:** Necessidade de adicionar e gerenciar contadores no `AssetManager`.
|
|
* **Virtual Machine:** Adicionar contador atômico de `used_bytes` na `Heap`.
|
|
* **Log Service:** Adicionar contador incremental de logs emitidos no frame no `LogService`.
|
|
* **Runtime:** Modificação no `VirtualMachineRuntime` para incluir o campo `inspection_active` e lógica condicional no `tick()`.
|
|
* **Host:** O host (ex: desktop-winit) deve agora sinalizar quando o overlay de depuração está ativo via `inspection_active`.
|
|
|
|
## Referências
|
|
|
|
* Agenda [AGD-0007-perf-runtime-telemetry-hot-path.md](../agendas/AGD-0007-perf-runtime-telemetry-hot-path.md)
|
|
* Spec `10-debug-inspection-and-profiling.md`
|
|
|
|
## Propagação Necessária
|
|
|
|
* Atualizar o `VirtualMachineRuntime` para expor o campo `inspection_active`.
|
|
* Atualizar o `HostRunner` para sinalizar `inspection_active` quando o overlay F1 for alternado.
|
|
* Atualizar a struct `TelemetryFrame` para incluir campos de Heap Memory e Log count.
|