PawSift 🐾 for Android Logcat

PawSift 🐾

PawSift é um servidor MCP (Model Context Protocol) de alta performance que conecta o Android Logcat a LLMs. Ele fornece uma interface eficiente em tokens e ciente de sessão para análise de logs em tempo real, usando um ingestor SQLite baseado em polling para filtrar a saída bruta e destacar apenas o que importa.

Recursos

• Processamento de Alto Rendimento: Parser manual de strings sem regex e deduplicação baseada em hash (usando hash/maphash) para processamento de logs em caminho crítico a 5.000+ logs/seg.
• Rastreamento de Sessão Sem Toque: Detecta automaticamente reinícios de aplicativos via ActivityManager e rotaciona sessões.
• Eficiência de Tokens: Pré-agrega erros, dobra logs repetitivos consecutivos e usa Mapeamento Hierárquico para agrupar mensagens idênticas sob subcabeçalhos.
• Consultas Cirúrgicas: Filtra logs por nível, tag e termos de busca com limites estritos de linhas para proteger a janela de contexto.
• Descoberta de Tags: Lista rapidamente todas as tags ativas na sessão atual.
• Janelas Contextuais: Busca logs ao redor de um evento específico para depuração precisa.
• Busca Global: Pesquisa todo o histórico de logs em todas as sessões com um único comando.
• Painel de Status: Uma ferramenta especializada de heartbeat para monitorar a saúde do watcher, IDs de sessão e backlog de logs.
• Política de Retenção Automática: Aplica limites máximos de logs (padrão: 10k logs, 3 sessões) com limpeza contínua durante o polling—evita crescimento ilimitado do banco de dados.
• Limpeza Configurável: Ajusta limites de retenção em tempo real via set_retention_policy() sem reiniciar.
• SQLite em Modo WAL: Write-Ahead Logging para acesso concorrente de leitura/escrita sem erros de database is locked.
• Consultas Otimizadas: Índices de banco de dados em tag, mensagem, timestamp e filtros compostos para buscas rápidas mesmo com grandes volumes de logs.
• Manutenção: Ferramentas integradas para limpar buffers de logs locais e do dispositivo.
• Baseado em Go: Distribuição rápida em binário único, sem dependências CGO.

Instalação

Binário pré-compilado (recomendado)

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/dolphprefect/pawsift-mcp/main/install.sh | sh

Windows (PowerShell)

irm https://raw.githubusercontent.com/dolphprefect/pawsift-mcp/main/install.ps1 | iex

Baixa o binário correto para seu sistema operacional e arquitetura, instala em ~/.local/bin/pawsift (ou %USERPROFILE%\.local\bin\pawsift.exe no Windows) e registra automaticamente o servidor nos arquivos de configuração do Gemini CLI e Claude Code (CLI).

Suporta: Linux amd64/arm64, macOS amd64/arm64, Windows amd64.

A partir do código-fonte

make deploy

Compila a partir do código-fonte e faz a mesma instalação + registro descritos acima.

Desinstalação

make uninstall

Ferramentas

Ferramenta	Descrição
pawsift_set_target_package	Configura o watcher para monitorar um aplicativo Android específico. Quando este pacote inicia, o ID da sessão é rotacionado automaticamente para isolar novos logs.
pawsift_get_status	Retorna o painel de status atual: pacote alvo, ID da sessão, atividade do watcher, dispositivo conectado e contagem atual de logs.
pawsift_get_error_summary	Retorna uma lista Markdown com contagem primeiro de logs únicos de ERROR e FATAL com seu [ID] mais recente. Use o ID para recuperação cirúrgica de contexto.
pawsift_get_tag_summary	Retorna uma lista Markdown com contagem primeiro de todas as tags de log únicas na sessão atual.
pawsift_query_logs	Recupera logs filtrados (por nível e/ou tag) usando Mapeamento Hierárquico. Suporta dobramento de mensagens idênticas consecutivas.
pawsift_get_log_context	Recupera linhas ao redor de um ID de log específico. Essencial para ver o que levou a uma falha ou evento.
pawsift_search_logs	Realiza uma busca global em todo o histórico de logs usando Mapeamento Hierárquico.
pawsift_clear_logs	Exclui permanentemente todos os logs do banco de dados e limpa o buffer logcat do dispositivo Android.
pawsift_set_retention_policy	Configura limites de retenção: máximo de logs totais, máximo de sessões a manter e intervalo de limpeza em segundos.

Eficiência de Tokens

Os logs Android são extremamente verbosos. Uma única inicialização de aplicativo pode produzir milhares de linhas, a maioria ruído repetitivo. Alimentar logcat bruto no contexto de um LLM é desperdício e frequentemente atinge limites. O PawSift resolve isso em dois níveis.

Dobramento

Quando fold=true (o padrão em pawsift_query_logs e pawsift_search_logs), mensagens de log idênticas consecutivas são colapsadas em uma única entrada anotada com contagem e intervalo de tempo:

- [1042-1089] **D** 09:14.201 - 09:14.812 Choreographer: Skipped 48 frames (48x)

Sem dobramento, esse mesmo trecho emitiria 48 linhas separadas. Um aplicativo ocupado com sondas WiFi repetidas, polling de sensores ou callbacks de animação pode comprimir 200+ linhas brutas em um punhado de entradas dobradas—uma redução de 10–50× em tokens para esses trechos.

Mapeamento Hierárquico

Além do dobramento, os resultados são estruturados usando Mapeamento Hierárquico: logs são agrupados primeiro por tag e PID (### Tag (PID)), depois por mensagem única (#### Message), com ocorrências individuais listadas abaixo. Isso significa que o LLM recebe um resumo estruturado em vez de um fluxo plano:

### MyApp (12345)
#### Failed to load resource
- [301] **E** 09:15.001
- [318] **E** 09:15.430

### NetworkManager (987)
#### Socket timeout
- [412] **W** 09:15.102

Mensagens repetidas da mesma fonte aparecem uma vez como cabeçalho com suas ocorrências listadas abaixo, em vez de duplicar o texto da mensagem em cada linha.

Acesso Cirúrgico Baseado em ID

Cada entrada de log carrega um [ID] estável. As ferramentas de resumo (pawsift_get_error_summary, pawsift_get_tag_summary) retornam apenas contagens e IDs—não o corpo completo do log. Uma vez que você tenha um ID de interesse, pawsift_get_log_context busca apenas a janela ao redor. Esse padrão de duas etapas (resumir → ampliar) evita carregar todo o histórico de logs no contexto.

Fluxo de Depuração

PawSift fornece uma camada de abstração inteligente sobre logs Android brutos, otimizada para depuração assistida por IA. Siga este fluxo para melhores resultados:

1. Configurar o Alvo

Antes de começar a testar, informe ao PawSift em qual aplicativo você está focando:

Usuário para LLM: "Defina o pacote alvo para com.your.app.package e observe os logs." Ação do LLM: Chama pawsift_set_target_package(package="com.your.app.package").

2. Verificar o Estado

Oriente-se antes de iniciar um mergulho profundo:

Ação do LLM: Chama pawsift_get_status(). Saída: Mostra se o watcher está ativo, o serial do dispositivo conectado e a contagem atual de logs.

3. Disparar o Problema

Execute seu aplicativo no dispositivo ou emulador. O PawSift detectará automaticamente o evento "Process Started" e iniciará uma nova sessão.

4. Identificar a Falha (A "Visão Panorâmica")

Se o aplicativo falhar ou se comportar inesperadamente, comece com um resumo de alto nível para economizar tokens:

Usuário para LLM: "O que aconteceu? Houve falhas?" Ação do LLM: Chama pawsift_get_error_summary(). Saída: Retorna assinaturas de erro únicas, contagens e seu [ID] mais recente.

5. Investigar os Logs (Acompanhamento Cirúrgico)

Não consulte todos os logs. Use o [ID] do resumo para ir direto ao contexto relevante:

Ação do LLM: Chama pawsift_get_log_context(log_id=1234, lines=20). Saída: Retorna 20 linhas antes e depois da falha, dando visibilidade sobre mudanças de estado, respostas de rede ou eventos de UI.

Dica Profissional: Supressão e Busca

• Se houver muito ruído do sistema (ex.: WifiHAL, AOC), diga ao LLM: "Ignore tags do sistema e foque nos logs do meu aplicativo."
• Use pawsift_search_logs(query="FATAL EXCEPTION") para encontrar eventos específicos em todo o histórico se o resumo da sessão atual for amplo demais.

Gerenciamento da Política de Retenção

O PawSift gerencia automaticamente o crescimento do banco de dados com uma política de retenção configurável. Por padrão:

• Máximo de 10.000 logs mantidos em todas as sessões
• Últimas 3 sessões retidas; as mais antigas são excluídas
• Limpeza a cada 30 segundos durante o polling para aplicar limites

Ajustando Limites em Tempo Real

Use pawsift_set_retention_policy() para ajustar limites sem reiniciar:

pawsift_set_retention_policy(max_logs=5000, max_sessions=2, cleanup_interval=15)

Casos de uso:

• Sessão de depuração longa: Reduza limites (5k logs, 2 sessões, limpeza a cada 15s) para manter o banco enxuto
• Reprodução rápida: Aumente limites (50k logs, 5 sessões, limpeza a cada 60s) se precisar de mais contexto histórico
• Restrições apertadas: Modo mínimo (1k logs, 1 sessão, limpeza a cada 10s) para ambientes com recursos limitados

Após cada ciclo de limpeza, o espaço em disco é recuperado via VACUUM.

Testes

O PawSift tem cobertura abrangente de testes, incluindo testes unitários, casos de borda de parsing, testes de estresse de concorrência e detecção de corrida de dados.

Executando Testes

make test        # Standard test suite
make test-race   # With Go race detector (recommended before releases)

Cobertura de Testes

Camada	Testes
Casos de Borda do Parser	13 subtestes: entrada vazia, linhas truncadas, dois-pontos ausentes, múltiplos dois-pontos, espaçamento variável, caracteres de nível inválidos, valores de estouro
Dedup por Hash	Rejeição de linhas idênticas, aceitação de diferença de um caractere, reset no limite de timestamp
fastAtoi	Limites: string vazia, zero, valores normais, estouro (retorna 0 com segurança)
Modo WAL	Verifica PRAGMA journal_mode=wal e PRAGMA synchronous=1 em bancos de dados baseados em arquivo
Carga Concorrente	10.000 linhas de log bombeadas através de processLine em uma goroutine com leitores de banco concorrentes—verificado sob o detector de corrida
Streaming	Cancelamento de contexto, lógica de retry, detecção de reinício de sessão
Fundamentos do Banco	Operações CRUD, limpeza, dobramento, aplicação da política de retenção
Handlers de Ferramentas	Teste de integração completo de todos os endpoints de ferramentas MCP
Render/Formatação	Renderização de entradas de log, indentação, saída de dobramento

19 funções de teste em 6 arquivos (21 funções de nível superior incluindo subtestes), todas passando limpas sob -race.

Detector de Corrida

Todos os testes são verificados com go test -race para garantir ausência de corridas de dados no pipeline de streaming, mapa de dedup e padrões de acesso concorrente ao banco.

Configuração para Clientes MCP

make deploy lida com isso automaticamente para Gemini CLI e Claude Code (CLI). Para configuração manual ou outros clientes, use o seguinte:

{
  "mcpServers": {
    "pawsift": {
      "command": "/home/YOUR_USER/.local/bin/pawsift"
    }
  }
}

Manutenção

• Localização do Binário: build/pawsift
• Banco de Dados: .pawsift/logcat.db (criado automaticamente, SQLite com modo WAL e índices para consultas rápidas)
• Taxa de Polling: 1 segundo (configurável em logcat.go)
• Buffer do Canal: 10.000 linhas (evita pressão reversa do scanner durante contenção de escrita no banco)
• Estratégia de Dedup: Hash uint64 via hash/maphash (zero-alocação, evita armazenar strings completas de log)
• Parser: Fatiamento manual de strings sem regex (processLine usa strings.IndexByte / strings.Cut)
• Padrões de Retenção: Máximo de 10.000 logs, máximo de 3 sessões, intervalo de limpeza de 30 segundos (configurável via set_retention_policy())
• Versão: Verifique via pawsift -version