---
id: AGD-0023
ticket: perf-host-debug-overlay-isolation
title: Agenda - [PERF] Overlay Log Metric Must Show Last Frame
status: accepted
created: 2026-04-10
resolved: 2026-04-10
decision: DEC-0010
tags: [performance, host, telemetry, logs]
---

# Agenda - [PERF] Overlay Log Metric Must Show Last Frame

## Contexto

Após mover o overlay para a camada de Host, o campo visual `LOGS` passou a expor um contador transitório compartilhado com o `LogService`. Esse contador é incrementado durante o frame e zerado no fechamento do frame lógico. Na prática, quando o Host lê a telemetria para desenhar o overlay, o valor visual tende a aparecer como `0`, mesmo em cenários com alta emissão de logs.

## Problema

O campo `LOGS` no overlay não está representando a informação útil para inspeção visual. Um valor transitório intra-frame é adequado para coleta interna, mas não para HUD técnico renderizado assíncronamente pelo Host.

## Pontos Criticos

- **Fato:** O Host lê a telemetria fora do momento exato em que o contador transitório atinge seu pico.
- **Fato:** A certificação precisa continuar vendo a pressão de logs do frame completo.
- **Risco:** Manter a semântica atual torna o campo visual enganoso e inutilizável.
- **Tradeoff:** Precisamos preservar o contador transitório para coleta interna, mas expor ao overlay apenas um valor persistido do último frame fechado.

## Opcoes

- **Opção A (Recomendada):** Persistir `logs from last completed frame` no `AtomicTelemetry` e fazer o overlay ler apenas esse valor.
- **Opção B:** Manter contador ao vivo e tentar amostrar em outro ponto do loop.
- **Opção C:** Mostrar ambos os valores no overlay.

## Sugestao / Recomendacao

Seguir com a **Opção A**:

1. O contador transitório de logs continua existindo apenas para coleta interna durante o frame.
2. No fechamento do frame lógico, o runtime persiste em `AtomicTelemetry` o total de logs do frame recém-concluído.
3. O campo `LOGS` visível no overlay deve representar exclusivamente `logs from last completed frame`.
4. A certificação deve continuar operando sobre esse mesmo valor persistido do frame concluído.

## Perguntas em Aberto

- Nenhuma. Em 2026-04-10 foi decidido que o overlay deve mostrar apenas logs do último frame concluído.

## Criterio para Encerrar

- semântica visual de `LOGS` definida como `last completed frame`;
- certificação preservada;
- implementação alinhada no HAL, runtime, overlay e specs.
*(Critérios atingidos em 2026-04-10)*