Console.app: co to jest, funkcje i jak czytać logi w macOS

Co to jest Console.app

Console.app to graficzny interfejs do unified logging system Apple. Zastąpiła stare narzędzie Console (jako część macOS) i zapewnia dostęp do wszystkich logów systemu i aplikacji zapisanych przez API os_log, os_trace i syslog. Console.app jest dostępna w /Applications/Utilities/ na każdym Macu.

W przeciwieństwie do Xcode, który pokazuje logi tylko dla uruchomionej z IDE aplikacji, Console.app wyświetla logi wszystkich procesów w systemie jednocześnie. Pozwala to diagnozować problemy, które występują tylko przy uruchomieniu aplikacji poza Xcode lub w tle. Console.app pokazuje również logi systemowe — kernel, launchd, WindowServer, co jest przydatne do debugowania niskopoziomowych problemów.

Console.app nie wymaga instalacji dodatkowych narzędzi ani połączenia z internetem. Wszystkie dane są przechowywane lokalnie w bazie danych .tracev3, a aplikacja działa całkowicie offline. Do przeglądania logów z innego Maca lub urządzenia iOS używa się polecenia log collect, a następnie otwiera .logarchive w Console.app.

Interfejs Console.app

Interfejs Console.app składa się z trzech głównych obszarów: panel boczny z filtrami, tabela komunikatów oraz panel szczegółów wybranego komunikatu. Panel boczny zawiera sekcje Devices (dostępne źródła logów), Reports (raporty systemowe o awariach) i Saved Searches (zapisane zapytania wyszukiwania).

Tabela komunikatów wyświetla listę logów z kolumnami: Time (znacznik czasu), Category (kategoria), Level (poziom krytyczności — oznakowanie kolorami), Process (nazwa procesu), Message (treść komunikatu). Kliknięcie dowolnego komunikatu otwiera panel szczegółów, w którym pokazane są subsystem, activity identifier, thread ID oraz pełny tekst z formatowaniem.

Console.app podświetla komunikaty kolorami: czerwony dla Fault, żółty dla Error, niebieski dla Debug, szary dla Info. Komunikaty Default nie są podświetlane. Pozwala to wizualnie skanować strumień logów i natychmiast dostrzegać krytyczne zdarzenia.

// Logi, które pojawią się w 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")

// Te komunikaty są widoczne w Console.app z filtrem "myapp"

Filtry i wyszukiwanie w Console.app

Filtracja to główna funkcja Console.app, zamieniająca strumień tysięcy komunikatów na sekundę w czytelną listę. Pole wyszukiwania w górnej części obsługuje warunki AND: kilka słów oddzielonych spacją wyświetla tylko komunikaty zawierające wszystkie słowa. Na przykład myapp error pokaże wszystkie logi aplikacji myapp z poziomem Error.

Filtr subsystem w panelu bocznym pozwala wybrać jeden lub więcej subsystem. To najszybszy sposób na wyizolowanie logów konkretnej aplikacji z komunikatów systemowych. Filtr Category jest dostępny po wybraniu subsystem — pokazuje wszystkie kategorie używane przez wybraną aplikację. Filtr Level ogranicza komunikaty według poziomu krytyczności: można pokazać tylko błędy lub tylko komunikaty debugowania.

Wyrażenia regularne w wyszukiwaniu

Pole wyszukiwania Console.app obsługuje regex przez konstrukcję REGEX:pattern. Przykład: REGEX:error.*tim(e|out) znajdzie wszystkie komunikaty zawierające „error" i słowo zaczynające się od „tim" i kończące na „e" lub „out". Regex działa tylko w polu wyszukiwania, nie w filtrach subsystem ani category.

Tryby Live i Historical

Live to tryb czasu rzeczywistego, w którym Console.app pokazuje nowe komunikaty w miarę ich pojawiania się w buforze cyklicznym jądra. Ten tryb jest domyślnie aktywny i nadaje się do debugowania działającej aplikacji: uruchamiasz aplikację i widzisz jej logi z opóźnieniem 1–5 sekund. Przycisk Live (lub ⌘L) włącza i wyłącza strumień.

Historical to tryb przeglądania archiwum. Console.app przechowuje wszystkie komunikaty z ostatnich 7–14 dni (konfigurowalne w systemie) w bazie .tracev3. Tryb Historical otwiera to archiwum i umożliwia wyszukiwanie według dowolnych filtrów, nie tylko bieżącego strumienia. Jest niezastąpiony do analizy problemów, które wystąpiły w nocy lub gdy aplikacja działała bez podłączenia do Maca.

Przełączanie między trybami odbywa się przez przycisk Live na pasku narzędzi. Gdy Live jest wyłączony, Console.app pokazuje dane historyczne. W tym trybie można poruszać się po osi czasu za pomocą kalendarza lub przycisków ← →. Dane Historical są dostępne tylko dla logów, które zostały zapisane na dysk — komunikaty nadpisane w buforze cyklicznym nie trafiają do archiwum.

Eksport i udostępnianie logów

Console.app obsługuje eksport przefiltrowanych logów w kilku formatach. File → Export → Save wybiera format: .logarchive (natywny format Apple, zawiera wszystkie metadane), .txt (zwykły tekst z kolumnami) i .json (dane strukturalne z polami). Do dołączenia do zgłoszenia błędu używaj .logarchive — można go otworzyć na każdym Macu w Console.app.

Eksport z urządzenia iOS: przez Xcode (Devices → Open Console) lub przez polecenie log collect --device --output ./archive.logarchive w terminalu. Otrzymany .logarchive otwórz w Console.app na Macu — logi pochodzą z zdalnego urządzenia, ale filtry i wyszukiwanie działają tak samo jak z lokalnymi logami.

// Eksport logów urządzenia iOS przez terminal
// log collect --device --output ./ios_crash.logarchive
// log show --subsystem com.example.app --last 1h --output json

// Przykład: wyeksportowanie logów z ostatniej godziny
// log show --predicate 'subsystem == "com.example.myapp"' \
//   --info --debug --last 1h --output json > logs.json

// Parsowanie wyeksportowanych logów w Swift
let jsonData = try Data(contentsOf: URL(fileURLWithPath: "logs.json"))
let decoded = try JSONDecoder()
    .decode([LogEntry].self, from: jsonData)

Współdzielenie logów

.logarchive to optymalny format do wysłania koledze lub dołączenia do zgłoszenia JIRA. Plik zawiera nie tylko komunikaty, ale także subsystem, category, timestamps, thread IDs i wszystkie metadane. Rozmiar archiwum jest znacznie mniejszy niż surowych logów dzięki kompresji .tracev3. Przed wysłaniem upewnij się, że logi nie zawierają prywatnych danych: użyj filtru subsystem swojej aplikacji, aby wykluczyć logi systemowe, które mogą zawierać poufne informacje innych procesów.

Praktyczne przykłady debugowania przez Console.app

Diagnostyka crasha bez Xcode: jeśli aplikacja uległa awarii przy uruchomieniu poza Xcode, Console.app pokaże komunikat Fault od procesu. Znajdź w panelu bocznym Reports → Crash Reports — tam wyświetlane są pełne raporty o awariach z sygnaturą i stosem. Użyj filtru subsystem dla swojej aplikacji i ustaw poziom Error+Fault, aby zobaczyć wszystkie krytyczne zdarzenia przed crashem.

Analiza wydajności przez Console.app

Console.app umożliwia śledzenie opóźnień w aplikacji na podstawie znaczników czasu. Jeśli między dwoma powiązanymi komunikatami (np. „żądanie wysłane" i „odpowiedź odebrana") minęło więcej czasu niż oczekiwano — to sygnał problemu z wydajnością. Filtr po subsystem swojej aplikacji z poziomem Default pokaże wszystkie kluczowe zdarzenia z dokładnością do milisekundy.

Wyszukiwanie wycieku pamięci: przy wycieku pamięci system wysyła memory warning przez os_log z kategorią memory i poziomem Error. W Console.app odfiltruj po słowie memory i wybierz swój subsystem. Jeśli ostrzeżenie powtarza się co 5–10 sekund — aplikacja aktywnie zużywa pamięć. Dodatkowo można włączyć logi Debug do śledzenia alokacji.

Debugowanie żądań sieciowych: jeśli twoja aplikacja używa os_log do zdarzeń sieciowych, Console.app pokaże wszystkie żądania i odpowiedzi z czasem. Filtr category=network zmniejszy szumy. Jeśli czas między żądaniem a odpowiedzią przekracza oczekiwany, szukaj komunikatów z level=Error — wskażą one na timeouty lub błędy DNS.

// Struktura do parsowania logów JSON 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"
        }
    }
}