Skip to content

metrics.md

Latest commit

 

History

History
241 lines (179 loc) · 5.9 KB

metrics.md

File metadata and controls

241 lines (179 loc) · 5.9 KB

Metrics — Entender Economia de Tokens

Last Updated: 2026-04-13

O que é rastreado

Cada execução de ctx exec <cmd> registra:

Campo Descrição
command Comando executado (ex: git status)
timestamp Quando (ISO 8601 UTC)
project_path Diretório de trabalho (ex: /home/user/repo)
exit_code Código de saída (0 = sucesso)
tokens_before Tokens na saída bruta (~1 token = 4 chars)
tokens_after Tokens na saída filtrada
reduction_percent Redução: (before - after) / before * 100
elapsed_ms Tempo de execução em ms
filter_applied Nome do filtro usado (ex: git-status)

Visualizar Métricas

Relatório agregado

ctx exec report

Output:

┌─────────────────────────────────────────────────┐
│ ctx exec — Relatório de Economia                │
├─────────────────────────────────────────────────┤
│ Período: últimos 7 dias                          │
│ Execuções: 1,247                                 │
│ Tokens economizados: 892,641 (71% médio)        │
│ Tempo total: 14h 23m                            │
└─────────────────────────────────────────────────┘

Top 10 Comandos
────────────────────────────────────────────────────
git status      | 342 exec | 89% redução médio
pytest          | 289 exec | 78% redução médio
ls -la          | 156 exec | 65% redução médio
cargo test      | 98 exec  | 84% redução médio
npm test        | 87 exec  | 91% redução médio

Relatório por período

ctx exec report --days 30      # Últimos 30 dias
ctx exec report --since 2026-04-01  # Desde data específica
ctx exec report --project /path/to/repo  # Apenas este projeto

Formato JSON

ctx exec report --format json

Output:

{
  "summary": {
    "period_days": 7,
    "executions": 1247,
    "tokens_before": 12543210,
    "tokens_after": 3651409,
    "total_reduction_percent": 71,
    "elapsed_total_ms": 51780000
  },
  "by_command": [
    {
      "command": "git status",
      "executions": 342,
      "tokens_before": 3421000,
      "tokens_after": 376310,
      "reduction_percent": 89
    }
  ]
}

Consultas Customizadas

Histórico completo em CSV

ctx exec query --format csv --output metrics.csv

Útil para análise em planilha.

Filtrar por comando

ctx exec report --filter "^git"

Apenas comando que batem regex ^git.

Filtrar por projeto

ctx exec report --filter-project /home/user/context-engine

Apenas execuções dentro daquele diretório.

Interpretar Redução

Percentual de Redução

  • 60-70%: Bom (remover headers, linhas verbosas)
  • 70-85%: Excelente (tabelas, repetição, timestamps)
  • 85-95%: Ótimo (logs comprimidos, testes, git diffs)
  • >95%: Excepcional (output gigante reduzido drasticamente)

Exemplo: pytest

Bruto:

===== test session starts =====
platform linux -- Python 3.10.0, pytest-7.0.0, py-1.11.0
rootdir: /home/user/project
collected 250 items

test/auth.py::test_login PASSED                           [0%]
test/auth.py::test_logout PASSED                          [1%]
... (1000 linhas)
===== FAILURES =====
...
===== short test summary =====
FAILED test/profile.py::test_avatar
===== 1 failed, 249 passed in 12.34s =====

Tokens bruto: ~4,000

Filtrado:

===== test session starts =====
test/auth.py::test_login PASSED
... (50 linhas)
===== short test summary =====
FAILED test/profile.py::test_avatar
===== 1 failed, 249 passed =====

Tokens filtrado: ~250

Redução: (4000-250)/4000 = 93.75%

Gestão de Dados

Limpeza automática

Registros mais antigos que metrics_retention_days (padrão: 90) são removidos automaticamente durante leitura.

[exec.metrics]
metrics_retention_days = 90

Limpeza manual

# Remover registros >30 dias
ctx exec prune --older-than 30

# Remover registros específicos
ctx exec prune --project /home/user/old-repo

Backup

# Exportar antes de limpar
ctx exec query --format json > metrics-backup.json

Insights Úteis

Qual comando consome mais tokens?

ctx exec report --order tokens_before --limit 5

Qual filtro é mais eficiente?

ctx exec report --group-by filter --order reduction_percent

Histórico de um projeto

ctx exec report --project . --days 30

Output:

┌────────────────────────────────────────┐
│ context-engine — últimos 30 dias       │
├────────────────────────────────────────┤
│ Execuções: 234                         │
│ Economia total: 156,789 tokens         │
│ Redução média: 76%                     │
│ Top comando: git status (184 exec)     │
└────────────────────────────────────────┘

Dica de Performance

Menos execuções = menos overhead de contexto:

  • Agrupe comandos quando possível
  • Reutilize ctx exec report em vez de re-rodar
  • Use --filter para buscar métricas específicas em vez de gerar relatório completo

Veja: