51 lines
2.6 KiB
Markdown
51 lines
2.6 KiB
Markdown
---
|
|
id: DEC-0010
|
|
ticket: perf-host-debug-overlay-isolation
|
|
title: Decision - [PERF] Overlay Log Metric Uses Last Completed Frame
|
|
status: accepted
|
|
created: 2026-04-10
|
|
updated: 2026-04-10
|
|
agenda: AGD-0023
|
|
tags: [performance, host, telemetry, logs]
|
|
---
|
|
|
|
# Decision - [PERF] Overlay Log Metric Uses Last Completed Frame
|
|
|
|
## Status
|
|
**Accepted**
|
|
|
|
## Contexto
|
|
O campo `LOGS` do overlay técnico do desktop host estava lendo um contador transitório incrementado durante o frame e zerado no fechamento do frame lógico. Como o Host compõe o overlay de forma assíncrona em relação ao loop interno da máquina, esse valor visual tende a aparecer como `0` mesmo sob stress com alta emissão de logs.
|
|
|
|
## Decisao
|
|
1. O valor visual `LOGS` exposto ao overlay MUST represent the number of logs emitted during the last completed logical frame.
|
|
2. O contador transitório intra-frame MAY continue to exist for internal collection and frame-end aggregation, but it MUST NOT be exposed diretamente como métrica visual do overlay.
|
|
3. O `AtomicTelemetry::snapshot()` MUST expose the persisted last-frame value for `logs_count`.
|
|
4. A certificação MUST evaluate log pressure against the persisted last completed frame value, not against a host-timing-dependent transient value.
|
|
|
|
## Rationale
|
|
- O overlay precisa de um valor estável e observável pelo Host.
|
|
- O frame fechado é a unidade correta para comparação com outras métricas como ciclos e syscalls.
|
|
- A mesma semântica serve tanto para overlay quanto para certificação, evitando ambiguidade.
|
|
|
|
## Invariantes / Contrato
|
|
- `logs_count` em `TelemetryFrame` significa `logs from last completed logical frame`.
|
|
- O reset do contador transitório não pode apagar o valor persistido exposto ao Host.
|
|
- O overlay não deve depender de timing fino entre renderização do Host e fechamento do frame lógico.
|
|
|
|
## Impactos
|
|
- **HAL:** `AtomicTelemetry` precisa persistir o valor de logs do frame concluído.
|
|
- **Runtime:** no fechamento do frame, o valor de logs do frame deve ser copiado antes do reset do contador transitório.
|
|
- **Host overlay:** nenhuma mudança conceitual adicional além de passar a receber um valor útil e estável.
|
|
- **Specs:** capítulo de debug deve deixar explícita a semântica de `logs_count`.
|
|
|
|
## Referencias
|
|
- `AGD-0023`: [PERF] Overlay Log Metric Must Show Last Frame.
|
|
- `DEC-0008`: Full Migration to Atomic Telemetry.
|
|
- `DEC-0009`: Host Overlay Tooling Boundary.
|
|
|
|
## Propagacao Necessaria
|
|
1. Atualizar `PLN-0008` para incluir a semântica last-frame de `LOGS`.
|
|
2. Ajustar HAL e runtime para persistir `logs_count` ao final do frame.
|
|
3. Atualizar a especificação de debug.
|