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.