Console.app: o que é, funcionalidades e como ler logs no macOS

O que é Console.app

Console.app é uma interface gráfica para o sistema de registro unificado da Apple. Ele substituiu o antigo aplicativo Console (como parte do macOS) e fornece acesso a todos os logs do sistema e de aplicativos escritos através das APIs os_log, os_trace e syslog. O Console.app está localizado em /Applications/Utilities/ em qualquer Mac.

Ao contrário do Xcode, que mostra apenas logs do aplicativo iniciado a partir da IDE, o Console.app exibe logs de todos os processos do sistema simultaneamente. Isso permite diagnosticar problemas que ocorrem apenas quando o aplicativo é iniciado fora do Xcode ou em segundo plano. O Console.app também mostra logs do sistema — kernel, launchd, WindowServer — o que é útil para depurar problemas de baixo nível.

Console.app não requer instalação de ferramentas adicionais ou conexão com a internet. Todos os dados são armazenados localmente em um banco de dados .tracev3, e o aplicativo funciona completamente offline. Para visualizar logs de outro Mac ou dispositivo iOS, use o comando log collect e depois abra o .logarchive no Console.app.

Interface do Console.app

A interface do Console.app consiste em três áreas principais: a barra lateral com filtros, a tabela de mensagens e o painel de detalhes da mensagem selecionada. A barra lateral contém as seções Devices (fontes de log disponíveis), Reports (relatórios de falhas do sistema) e Saved Searches (consultas de pesquisa salvas).

A tabela de mensagens exibe uma lista de logs com colunas: Time (carimbo de data/hora), Category (categoria), Level (nível de criticidade — codificado por cores), Process (nome do processo), Message (texto da mensagem). Clicar em qualquer mensagem abre o painel de detalhes mostrando o subsistema, identificador de atividade, ID da thread e o texto completo formatado.

Console.app destaca as mensagens por cor: vermelho para Fault, amarelo para Error, azul para Debug, cinza para Info. Mensagens Default não são destacadas. Isso permite escanear visualmente o fluxo de logs e notar instantaneamente eventos críticos.

// Logs que aparecerão no Console.app
import OSLog

let logger = Logger(
    subsystem: "com.example.myapp",
    category: "network"
)

logger.error("Connection failed: timeout")
logger.debug("Retry attempt 3 of 5")

// Estas mensagens são visíveis no Console.app com o filtro "myapp"

Filtros e pesquisa no Console.app

A filtragem é a principal funcionalidade do Console.app, transformando um fluxo de milhares de mensagens por segundo em uma lista legível. O campo de pesquisa na parte superior suporta condições AND: várias palavras separadas por espaço mostram apenas mensagens contendo todas as palavras. Por exemplo, myapp error mostra todos os logs do aplicativo myapp com nível Error.

Filtro de subsistema na barra lateral permite selecionar um ou mais subsistemas. Esta é a maneira mais rápida de isolar os logs de um aplicativo específico das mensagens do sistema. Filtro de categoria fica disponível após selecionar um subsistema — mostra todas as categorias usadas pelo aplicativo selecionado. Filtro de nível restringe mensagens por nível de criticidade: é possível mostrar apenas erros ou apenas mensagens de depuração.

Expressões regulares na pesquisa

O campo de pesquisa do Console.app suporta regex através da construção REGEX:pattern. Exemplo: REGEX:error.*tim(e|out) encontra todas as mensagens contendo “error” e uma palavra começando com “tim” e terminando com “e” ou “out”. Regex funciona apenas no campo de pesquisa, não nos filtros de subsistema ou categoria.

Modos Live e Historical

Live é o modo em tempo real no qual o Console.app mostra novas mensagens à medida que aparecem no buffer circular do kernel. Este modo está ativo por padrão e é adequado para depurar um aplicativo em execução: você inicia o aplicativo e vê seus logs com um atraso de 1 a 5 segundos. O botão Live (ou ⌘L) ativa e desativa o fluxo.

Historical é o modo de visualização de arquivo. O Console.app armazena todas as mensagens dos últimos 7 a 14 dias (configurável no sistema) em um banco de dados .tracev3. O modo Historical abre este arquivo e permite pesquisar nele usando qualquer filtro, não apenas o fluxo atual. Isso é indispensável para analisar problemas que ocorreram durante a noite ou quando o aplicativo estava rodando sem estar conectado a um Mac.

A alternância entre modos é feita através do botão Live na barra de ferramentas. Quando o Live está desligado, o Console.app mostra dados históricos. Neste modo, você pode navegar pela linha do tempo usando o calendário ou os botões ← →. Os dados históricos estão disponíveis apenas para logs que foram salvos no disco — mensagens que foram sobrescritas no buffer circular não aparecem no arquivo.

Exportação e compartilhamento de logs

Console.app suporta exportação de logs filtrados em vários formatos. File → Export → Save permite escolher o formato: .logarchive (formato nativo da Apple, inclui todos os metadados), .txt (texto simples com colunas) e .json (dados estruturados com campos). Para anexar a um relatório de bug, use .logarchive — ele pode ser aberto em qualquer Mac no Console.app.

Exportação de um dispositivo iOS: via Xcode (Devices → Open Console) ou através do comando log collect --device --output ./archive.logarchive no terminal. Abra o .logarchive resultante no Console.app em um Mac — os logs vêm do dispositivo remoto, mas filtros e pesquisa funcionam da mesma forma que com logs locais.

// Exportação de logs de dispositivo iOS via terminal
// log collect --device --output ./ios_crash.logarchive
// log show --subsystem com.example.app --last 1h --output json

// Exemplo: exportar logs da última hora
// log show --predicate 'subsystem == "com.example.myapp"' \
//   --info --debug --last 1h --output json > logs.json

// Parse de logs exportados em Swift
let jsonData = try Data(contentsOf: URL(fileURLWithPath: "logs.json"))
let decoded = try JSONDecoder()
    .decode([LogEntry].self, from: jsonData)

Compartilhamento de logs

.logarchive é o formato ideal para enviar a um colega ou anexar a um ticket JIRA. O arquivo contém não apenas mensagens, mas também subsistema, categoria, carimbos de data/hora, IDs de thread e todos os metadados. O tamanho do arquivo é significativamente menor que logs brutos graças à compressão .tracev3. Antes de enviar, certifique-se de que os logs não contêm dados privados: use um filtro pelo subsistema do seu aplicativo para excluir logs do sistema que possam conter informações confidenciais de outros processos.

Exemplos práticos de depuração com Console.app

Diagnóstico de falhas sem Xcode: se um aplicativo falhar ao iniciar fora do Xcode, o Console.app mostrará uma mensagem Fault do processo. Encontre Reports → Crash Reports na barra lateral — relatórios completos de falhas com assinatura e pilha são exibidos lá. Use o filtro de subsistema para seu aplicativo e defina o nível como Error+Fault para ver todos os eventos críticos antes da falha.

Análise de desempenho via Console.app

O Console.app permite rastrear atrasos no aplicativo usando carimbos de data/hora. Se mais tempo do que o esperado passou entre duas mensagens relacionadas (por exemplo, “solicitação enviada” e “resposta recebida”), isso é um sinal de problema de desempenho. Um filtro no subsistema do seu aplicativo com o nível Default mostrará todos os eventos principais com precisão de milissegundos.

Encontrando vazamentos de memória: quando ocorre um vazamento de memória, o sistema envia um aviso de memória via os_log com a categoria memory e nível Error. No Console.app, filtre pela palavra memory e selecione seu subsistema. Se o aviso se repetir a cada 5 a 10 segundos, o aplicativo está consumindo memória ativamente. Você também pode ativar logs Debug para rastrear alocações.

Depuração de requisições de rede: se seu aplicativo usa os_log para eventos de rede, o Console.app mostrará todas as requisições e respostas com tempos. Um filtro category=network reduz o ruído. Se o tempo entre uma requisição e resposta exceder o esperado, procure mensagens com level=Error — elas indicarão timeouts ou erros de DNS.

// Estrutura para parse de logs JSON do Console.app
struct LogEntry: Codable {
    let timestamp: String
    let eventMessage: String
    let subsystem: String
    let category: String
    let messageType: UInt8

    var level: String {
        switch messageType {
        case 1: return "Fault"
        case 16: return "Error"
        case 17: return "Debug"
        default: return "Default"
        }
    }
}