TextNLPClassifierApp/docs/structured_extraction/05_Metricas_KPIs_Runtime.md

# Catálogo de métricas e KPIs — Runtime de consolidação de artigos

**Versão:** 1.0  
**Data:** 23 de agosto de 2026  
**Escopo:** runtime; self-healing excluído

**Regra mestre:** medir somente qualidade, operação, custo e riscos exigidos pelo runtime, sem criar telemetria sem consumidor ou finalidade definida.

## 1. Objetivo

Definir o que deve ser medido, como interpretar cada indicador, quais dimensões são permitidas e quais gates impedem o go-live ou uma promoção.

## 2. Princípios

- Invariantes críticas não são compensadas por média alta.
- Métricas de qualidade devem ser segmentadas por idioma, domínio, extrator, modelo e prompt.
- URLs, fingerprints e IDs de execução não devem virar labels de alta cardinalidade; pertencem a traces e logs.
- Custo e latência são instrumentados antes de receber limites numéricos.
- Limites são aprovados com baseline do staging, não inventados.
- O runtime emite sinais objetivos para futura análise de prompt, mas não executa self-healing.

## 3. KPIs do produto

| KPI | Definição | Meta ou gate |
| --- | --- | --- |
| Publicação fundamentada | Markdown sem texto, URL ou imagem inventada | 100% |
| Aprovação end-to-end textual | Artigos textuais que passam integralmente pela verdade de referência | ≥ 95% |
| Integridade operacional | Artigos sem perda, corrupção ou duplicação | 100% |
| Cobertura de telemetria | Trace enviado ou evento preservado | 100% |
| Custo por Markdown aprovado | Custo LLM total dividido por Markdown aprovado | Limite aprovado após staging |
| Latência end-to-end | Tempo recebido até persistência final | Limites p50/p95/p99 após staging |

## 4. Invariantes críticas

As seguintes métricas possuem meta zero e bloqueiam promoção quando maiores que zero:

| Métrica lógica | Evento contado |
| --- | --- |
| `ungrounded_text_total` | Texto publicado sem origem ou reparo autorizado |
| `ungrounded_url_total` | URL publicada sem origem |
| `ungrounded_image_total` | Imagem publicada sem origem |
| `unauthorized_rewrite_total` | Reparo que resultou em paráfrase ou alteração semântica |
| `critical_fact_change_total` | Nome, número, data, placar, citação ou fato alterado indevidamente |
| `duplicate_output_total` | Saída final duplicada para mesmo fingerprint e versões |
| `lost_article_total` | Entrada validada sem estado terminal rastreável |
| `secret_exposure_total` | Credencial identificada em log, trace ou saída |
| `powerful_runtime_model_call_total` | Chamada de modelo potente no runtime |
| `online_promptfoo_call_total` | Promptfoo acionado pelo runtime |
| `text_regex_usage_total` | Uso detectado de regex no pipeline textual/assertions |

## 5. Métricas de volume e resultado

| Métrica lógica | Definição |
| --- | --- |
| `article_received_total` | Execuções iniciadas |
| `article_validated_total` | Entradas que passaram validação |
| `article_duplicate_total` | Fingerprints já concluídos |
| `article_completed_text_total` | Markdown produzido |
| `article_rejected_ecp_total` | Rejeições esperadas pelo ECP |
| `article_failed_validation_total` | Falhas antes do processamento |
| `article_failed_processing_total` | Falhas após validação |

Taxas derivadas:

- conclusão textual por artigo validado;
- rejeição ECP por artigo validado;
- falha de validação por artigo recebido;
- falha de processamento por artigo validado;
- duplicidade por artigo recebido.

## 6. Métricas de entrada

| Métrica lógica | Dimensões de baixa cardinalidade |
| --- | --- |
| `input_validation_failure_total` | `reason`, `schema_version` |
| `selected_extractor_total` | `extractor` |
| `selected_extractor_unavailable_total` | `extractor` |
| `source_language_total` | `language` |
| `source_domain_group_total` | domínio controlado ou site cadastrado |
| `ecp_version_total` | `ecp_schema_version` |

Domínio bruto de URL não deve virar label sem controle de cardinalidade. URLs individuais permanecem em trace/log.

## 7. Métricas de higienização

| Métrica lógica | Definição |
| --- | --- |
| `hygiene_call_total` | Chamadas lógicas de higienização |
| `hygiene_schema_failure_total` | Respostas fora do schema |
| `hygiene_grounding_failure_total` | IDs ou conteúdo sem origem |
| `hygiene_fallback_total` | Uso de provider fallback |
| `hygiene_deterministic_fallback_total` | Uso do fallback conservador |
| `hygiene_terminal_failure_total` | Nenhum resultado seguro |
| `block_candidate_total` | Blocos disponibilizados |
| `block_kept_total` | Blocos selecionados |
| `block_removed_total` | Blocos removidos |
| `link_kept_total` | Links editoriais mantidos |
| `image_kept_total` | Imagens editoriais comuns mantidas |

Nos evals:

- precisão de blocos;
- recall de blocos;
- perda material de conteúdo;
- ruído residual;
- precisão de links;
- precisão de imagens;
- acurácia de metadados.

## 8. Métricas de reparos textuais

| Métrica lógica | Definição |
| --- | --- |
| `text_repair_proposed_total` | Reparos propostos pelo LLM |
| `text_repair_applied_total` | Reparos validados e aplicados |
| `text_repair_rejected_total` | Reparos descartados |
| `text_repair_category_total` | Reparos por categoria fechada |
| `text_repair_ambiguous_target_total` | Fragmento não localizado inequivocamente |
| `text_repair_sensitive_change_total` | Tentativa de alterar entidade sensível |

Dimensões permitidas:

- etapa ou campo;
- categoria;
- modelo;
- versão do prompt;
- idioma;
- motivo de rejeição.

Texto original e substituição ficam no trace controlado, não em labels.

Gates:

- reparo indevido publicado: zero;
- alteração crítica publicada: zero;
- reparos rejeitados são medidos, não necessariamente erro terminal;
- taxa de rejeição crescente sinaliza necessidade futura de revisão de prompt.

## 9. Métricas do ECP

| Métrica lógica | Definição |
| --- | --- |
| `ecp_classification_total` | Resultado por categoria |
| `ecp_classification_failure_total` | Falha sem categoria válida |
| `ecp_pass_total` | Direto ou contextual |
| `ecp_reject_total` | Tangencial ou não relacionado |
| `ecp_latency_seconds` | Duração do classificador |
| `ecp_fallback_tier_total` | Tier usado pelo classificador, quando exposto |

A meta de qualidade intrínseca do classificador é herdada do projeto ECP e não duplicada neste catálogo. O runtime valida apenas integração, contrato, gate e resultado end-to-end.

## 10. Métricas de enriquecimento

| Métrica lógica | Definição |
| --- | --- |
| `sentiment_total` | Distribuição positive/negative/neutral |
| `tag_count` | Quantidade de tags por artigo |
| `enrichment_schema_failure_total` | Resposta inválida |
| `enrichment_grounding_failure_total` | Evidência ou tag sem suporte |
| `enrichment_fallback_total` | Uso de fallback barato |
| `enrichment_terminal_failure_total` | Markdown bloqueado por falha final |

Nos evals, medir acurácia de sentimento relativo ao ECP e aceitação das tags conforme verdade de referência.

## 11. Métricas de LLM

Para cada generation:

- papel lógico;
- provider;
- modelo;
- versão e hash do prompt;
- versão do schema;
- tentativa;
- status;
- tokens de entrada;
- tokens de saída;
- tokens em cache, quando disponíveis;
- custo;
- latência;
- timeout;
- retry;
- fallback;
- resultado de validação.

Métricas agregadas:

| Métrica lógica | Dimensões |
| --- | --- |
| `llm_request_total` | `logical_call`, `provider`, `model`, `status` |
| `llm_input_tokens_total` | `logical_call`, `provider`, `model` |
| `llm_output_tokens_total` | `logical_call`, `provider`, `model` |
| `llm_cost_total` | `logical_call`, `provider`, `model` |
| `llm_latency_seconds` | `logical_call`, `provider`, `model` |
| `llm_retry_total` | `reason`, `provider`, `model` |
| `llm_fallback_total` | `logical_call`, `reason` |
| `llm_output_validation_failure_total` | `logical_call`, `reason`, `prompt_version` |

## 12. Sinais para futura revisão de prompt

O runtime não diagnostica causa-raiz nem inicia self-healing. Ele registra sinais objetivos que poderão alimentar alertas e análise futura:

| Sinal | Condição objetiva |
| --- | --- |
| `prompt_review_signal_total{reason=schema}` | Saída LLM fora do schema |
| `prompt_review_signal_total{reason=grounding}` | ID, texto ou URL sem origem |
| `prompt_review_signal_total{reason=repair}` | Reparo rejeitado |
| `prompt_review_signal_total{reason=fallback}` | Primário exigiu fallback |
| `prompt_review_signal_total{reason=terminal}` | Primário e fallback falharam |

Dimensões:

- chamada lógica;
- prompt version;
- provider/modelo;
- idioma;
- domínio controlado;
- motivo.

Não existe:

- acionamento automático;
- modelo otimizador;
- judge;
- prompt candidato;
- alerta ativo como requisito deste projeto.

## 13. Métricas de persistência e idempotência

| Métrica lógica | Definição |
| --- | --- |
| `state_transition_total` | Transições por origem/destino |
| `state_transition_failure_total` | Falhas de persistência |
| `sqlite_lock_wait_seconds` | Espera por lock |
| `sqlite_busy_failure_total` | Timeout de lock |
| `atomic_write_failure_total` | Falhas em temporário/rename/hash |
| `resume_total` | Execuções retomadas |
| `idempotent_hit_total` | Resultado já concluído reutilizado |
| `orphan_temp_file_total` | Temporários órfãos encontrados |

## 14. Métricas de observabilidade

| Métrica lógica | Meta |
| --- | ---: |
| `trace_created_total / article_validated_total` | 100% enviado ou pendente |
| `telemetry_send_failure_total` | Medir; não bloquear artigo |
| `telemetry_pending_total` | Deve retornar a zero após recuperação |
| `telemetry_flush_failure_total` | Medir e preservar pendência |
| `trace_content_disabled_total` | Informativa |
| `trace_redaction_failure_total` | 0 |

## 15. Métricas de capacidade

Medir no staging e produção:

- artigos por hora;
- execuções concorrentes;
- duração total p50/p95/p99;
- duração por estado p50/p95/p99;
- CPU;
- memória;
- crescimento do SQLite;
- uso de disco por saídas e temporários;
- espera por lock;
- falhas por saturação;
- tokens e custo por artigo recebido;
- tokens e custo por Markdown aprovado.

Gate já definido:

- sustentar 100 artigos por hora;
- zero perda;
- zero duplicação;
- zero corrupção.

## 16. Baseline e definição de SLOs

### 16.1 Staging

Executar corpus representativo no ambiente equivalente ao de produção, incluindo idiomas, domínios, extratores, estruturas editoriais, ECP, fallback observado e concorrência real.

### 16.2 Relatório obrigatório

- tamanho e composição do corpus;
- versões de código, prompt, modelo e ECP;
- throughput;
- latência p50/p95/p99 por etapa e total;
- custo p50/p95/p99 por artigo;
- custo por Markdown aprovado;
- taxa de fallback;
- utilização de recursos;
- falhas e outliers.

### 16.3 Aprovação

Antes do go-live, registrar no runbook:

- limite de custo por artigo;
- limite de custo por Markdown aprovado;
- SLO de latência end-to-end;
- timeouts por provider;
- limite operacional de fallback;
- limites de armazenamento.

Nenhum valor deve ser inserido sem evidência da baseline.

## 17. Logs estruturados

Campos mínimos:

- timestamp;
- severity;
- ambiente;
- `run_id`;
- fingerprint;
- estado;
- evento;
- código de erro;
- chamada lógica;
- provider/modelo;
- prompt version;
- duração;
- retry/fallback;
- trace ID;
- status final.

Campos proibidos:

- API keys;
- headers de autorização;
- secrets;
- ECP integral;
- HTML integral;
- artigo integral por padrão.

Conteúdo necessário para diagnóstico fica no trace conforme política, com possibilidade de desativação.

## 18. Dashboards mínimos

### 18.1 Saúde do runtime

- recebidos, concluídos, rejeitados e falhos;
- throughput;
- latência;
- custo;
- providers;
- fallback;
- persistência;
- telemetria pendente.

### 18.2 Qualidade

- schema e grounding;
- reparos aplicados/rejeitados;
- ECP;
- sentimento e tags;
- resultados por prompt/modelo/idioma/domínio.

### 18.3 Sinais de revisão futura

- `prompt_review_signal_total` por motivo;
- falhas após fallback;
- concentração por versão de prompt;
- custo potencial associado aos casos.

O dashboard existe; alertas específicos de self-healing ficam para o subprojeto futuro.

## 19. Cardinalidade

Podem ser labels:

- ambiente;
- estado;
- código de erro;
- chamada lógica;
- provider;
- modelo;
- prompt version;
- schema version;
- idioma controlado;
- extrator;
- categoria ECP;
- motivo categórico.

Não podem ser labels:

- URL;
- fingerprint;
- run ID;
- trace ID;
- título;
- autor;
- texto;
- tag editorial livre;
- nome livre de domínio não cadastrado.

## 20. Critério de aceite

O catálogo estará implementado quando:

- todas as invariantes críticas puderem ser medidas;
- KPIs puderem ser calculados por slice;
- Langfuse receber versões, custos, latência e scores;
- logs forem estruturados e sanitizados;
- telemetria pendente puder ser contada e reenviada;
- sinais de revisão de prompt existirem sem acionar self-healing;
- teste de staging produzir baseline completa;
- limites de custo e latência forem aprovados e incorporados ao runbook antes do go-live.