Logs

Logs und Log Insights

Die App Logs Tab öffnet sich Log-Insights standardmäßig. Nutze Insights, um Kategorien, Versionen und Geräte für Zeiträume von 1, 3, 7 oder 30 Tagen zu priorisieren. Wechsle zum Logs Subtab, wenn du die unten beschriebenen zugrunde liegenden Device-Events, Filter und Timestamps benötigst.

Application Logs verstehen

Der Unterreiter Raw Logs bietet eine detaillierte Historie der Update-Events und Diagnoseinformationen für deine App. Er ist hilfreich, um Belege auf Geräteebene für ein Insight zu bestätigen, Update-Pfade zu troubleshooten und zu verstehen, wie Geräte mit Capgo interagieren. Öffne eine App, wähle Logs, und wähle dann den Logs subtab.

Raw Logs Tab

Die Raw Logs-Oberfläche enthält:

1. Logs-Unterreiter — die Navigationssteuerung für einzelne Log-Zeilen.
2. Reload-Button — aktualisiert die Log-Liste mit den neuesten Daten.
3. Zeitraum- und Aktionsfilter — grenzt den Event-Stream nach Zeit und Aktion ein.

Jede Zeile zeigt:

• Zeitstempel (UTC)
• Geräte-ID
• Aktion code (was passiert ist)
• Versionsname (Bundle oder builtin)

Klicke auf eine Zeile, um zur Detailseite des Geräts mit der vollständigen Historie zu gelangen.

Nach Zeitraum filtern

Du kannst die Logs über den Date Picker nach einem bestimmten Zeitraum filtern:

Zeitraum-Filter

1. Schnellauswahl - Wähle gängige Zeiträume: Letzte 1h, 3h, 6h oder 12h
2. Startzeit - Lege eine benutzerdefinierte Startzeit fest
3. Endzeit - Lege eine benutzerdefinierte Endzeit fest
4. Kalender - Bestimme Daten über die Kalenderansicht

Klicke auf „Select“, um den Zeitraum anzuwenden, oder auf „Cancel“, um den Picker zu schließen.

Nach Aktionstyp filtern

Mit dem Actions-Dropdown kannst du Logs nach bestimmten Ereignistypen filtern:

Actions-Filter

Folgende Aktionsfilter stehen zur Verfügung:

• Device-Heartbeat - Regelmäßige Health Checks der Geräte
• Löschung der Version angefordert - Wenn eine Bundle-Version gelöscht wird
• Auf Standardversion zurücksetzen - Wenn ein Gerät zum Builtin-Bundle zurückkehrt
• Version erfolgreich installiert - Erfolgreiche Bundle-Installation
• Neue Version an Gerät gesendet - Wenn Capgo ein Update an ein Gerät sendet
• Versionsinstallation fehlgeschlagen - Wenn die Bundle-Installation fehlschlägt

Nutze das Suchfeld oben, um schnell bestimmte Aktionstypen zu finden. Du kannst mehrere Aktionen auswählen, um Logs anzuzeigen, die zu einem der ausgewählten Typen passen.

Log-Snippet (Beispieldaten)

Zeit (UTC)	Geräte-ID	Aktion	Version	Was sie aussagt
2025-01-14 10:00:01	A1B2C3	get	2.4.1	Gerät hat Capgo gefragt, ob ein Update verfügbar ist
2025-01-14 10:00:03	A1B2C3	download_manifest_start	2.4.1	Delta-Download gestartet; SDK lädt jetzt die geänderten Delta-Dateien herunter
2025-01-14 10:00:07	A1B2C3	download_40	2.4.1	Bundle-Download zu 40 % abgeschlossen
2025-01-14 10:00:12	A1B2C3	download_zip_complete	2.4.1	Zip-Download abgeschlossen
2025-01-14 10:00:13	A1B2C3	set	2.4.1	Bundle installiert und als Nächstes auszuführen markiert
2025-01-14 10:05:00	B9C8D7	disableAutoUpdateToMajor	1.9.0	Channel-Policy hat einen Sprung auf 2.x blockiert
2025-01-14 10:05:05	B9C8D7	rateLimited	builtin	Gerät hat das Request-Limit erreicht; SDK pausiert bis zum Neustart

Beispiel-Log-Szenarien

Um die Logs besser interpretieren zu können, findest du hier Beispielsequenzen, die typische Update-Vorgänge auf echten Geräten zeigen:

Erfolgreicher Update-Flow

So sieht ein reibungsloser Update-Prozess in deinen Logs aus:

Zeitpunkt	Geräte-ID	Aktion	Version	What it means
10:00:01	a1b2c3d4	get	1.2.0	Gerät auf Updates geprüft, Version 1.2.0 erhalten
10:00:02	a1b2c3d4	download_10	1.2.0	Download gestartet, 10 % abgeschlossen
10:00:03	a1b2c3d4	download_50	1.2.0	Download bei 50 %
10:00:05	a1b2c3d4	download_complete	1.2.0	Download erfolgreich abgeschlossen
10:00:06	a1b2c3d4	set	1.2.0	Bundle installiert und aktiviert

Gerät bereits auf dem neuesten Stand

Wenn ein Gerät prüft, aber bereits die neueste Version hat:

Zeitpunkt	Geräte-ID	Aktion	Version	What it means
14:30:00	e5f6g7h8	noNew	1.2.0	Gerät ist bereits auf dem neuesten Stand, kein Update nötig

Fehlgeschlagenes Update mit Rollback

Wenn ein Update fehlschlägt und das Gerät ein Rollback durchführt:

Zeitpunkt	Geräte-ID	Aktion	Version	What it means
11:15:00	i9j0k1l2	get	1.3.0	Gerät hat Update-Infos erhalten
11:15:02	i9j0k1l2	download_complete	1.3.0	Download abgeschlossen
11:15:03	i9j0k1l2	set	1.3.0	Bundle wurde gesetzt
11:15:10	i9j0k1l2	update_fail	1.3.0	App ist abgestürzt oder notifyAppReady() wurde nicht aufgerufen – Rollback ausgelöst
11:15:11	i9j0k1l2	reset	integriert	Gerät wurde auf die Built-in-Version zurückgesetzt

Erforderliche Aktion: Prüfe, ob deine App aufruft notifyAppReady() nach erfolgreicher Initialisierung. Siehe die Plugin-Dokumentation für Details.

Download-Fehler

Wenn Netzwerkprobleme den Download verhindern:

Zeitpunkt	Geräte-ID	Aktion	Version	What it means
09:45:00	m3n4o5p6	get	1.2.0	Gerät hat Update-Infos erhalten
09:45:01	m3n4o5p6	download_30	1.2.0	Download gestartet, aber...
09:45:15	m3n4o5p6	download_fail	1.2.0	Download fehlgeschlagen (Timeout, Verbindungsabbruch, etc.)

Erforderliche Aktion: Das Gerät versucht es beim nächsten App-Start automatisch erneut. Kein Handeln erforderlich, außer dies tritt häufig auf.

Plan-Limit erreicht

Wenn Ihr Account das Geräte-Limit erreicht:

Zeitpunkt	Geräte-ID	Aktion	Version	What it means
16:00:00	q7r8s9t0	needPlanUpgrade	-	Dieses Gerät erhält keine Updates, bis Sie upgraden oder der Abrechnungszyklus zurückgesetzt wird

Erforderliche Aktion: Plan upgraden oder auf den nächsten Abrechnungszyklus warten.

Channel-Konfiguration blockiert Updates

Wenn die Channel-Einstellungen ein Update verhindern:

Zeitpunkt	Geräte-ID	Aktion	Version	What it means
12:00:00	u1v2w3x4	disableAutoUpdateToMajor	2.0.0	Gerät auf v1.x kann nicht automatisch auf v2.x updaten (Major-Version-Sprung blockiert)
12:05:00	y5z6a7b8	disableEmulator	1.2.0	Emulator erkannt; Channel blockiert Emulatoren
12:10:00	c9d0e1f2	disableDevBuild	1.2.0	Dev-Build erkannt; Channel blockiert Dev-Builds

Erforderliche Aktion: Dies sind beabsichtigte Schutzmaßnahmen. Um diese Updates zu erlauben, ändere deine Channel-Einstellungen.

Log-Codes (Capgo Backend-Enum)

Diese Codes stammen aus dem stats_action Enum, das vom Dashboard API genutzt wird (capgo/src/types/supabase.types.ts). Wenn ein neuer code in der UI auftaucht, wurde er vom SDK oder vom Backend emittiert und gegen diese Liste validiert.

Happy Path & Lifecycle

Code(s)	Bedeutung
get	Device hat Capgo nach dem Bundle für seinen Channel gefragt
download_manifest_start, download_manifest_complete	Delta-Download gestartet / beendet (für Bundles, die mit Delta-Dateien hochgeladen wurden)
download_zip_start, download_zip_complete	Zip-Archiv-Download gestartet / beendet
download_10 … download_90	Meilensteine des Downloads
download_0	0%-Marker für das erste Download-Event
download_complete	Gesamtes Bundle heruntergeladen
set	Bundle für den nächsten Start bereitgestellt
reset	Gerät auf das Builtin-Bundle zurückgesetzt
delete	Bundle aus dem lokalen Speicher entfernt
uninstall	App-Deinstallation erkannt
app_moved_to_foreground, app_moved_to_background	App-Lifecycle-Events aufgezeichnet durch SDK
ping	Health/Heartbeat-Check vom Gerät
setChannel, getChannel	Channel via SDK Call überschrieben oder abgerufen

Neuer Policy-Block / Throttle Quick Fix

Code	Ursachen hierfür	Nächste Schritte
invalidIp	Capgo hat Traffic erkannt, der wie Bot-Traffic aussieht (Google/Cloud-Infrastruktur IP).	Bei echten Nutzern ignorieren; Versuche von echten Geräten und normalen Netzwerken wiederholen oder später prüfen.
needPlanUpgrade	Die Organisation hat das Plan-/Gerätelimit erreicht.	Upgrade im Dashboard oder beim nächsten Abrechnungszyklus.
semver_error	Die Native app version in der Config fehlt oder ist kein gültiges SemVer (x.y.z).	Setzen Sie plugins.CapacitorUpdater.version zu gültigem SemVer, dann im SemVer Tester verifizieren und die App neu bauen.
disablePlatformIos	iOS ist in der Channel-Policy deaktiviert.	Falls dies ein Versehen war, aktiviere iOS in diesem Channel und veröffentliche das Routing neu. Wenn du iOS in diesem Track absichtlich blockierst, lass es deaktiviert und verschiebe iOS-Builds in einen separaten Channel.
disablePlatformAndroid	Android ist in der Channel-Policy deaktiviert.	Falls dies ein Versehen war, aktiviere Android in diesem Channel und veröffentliche das Routing neu. Wenn du Android in diesem Track absichtlich blockierst, lass es deaktiviert und verschiebe Android-Builds in einen separaten Channel.
disableAutoUpdate	Der Auto-Update-Modus des Channels blockiert diesen Update-Typ.	Ändere die Channel-Auto-Update-Policy (major/minor/patch/metadata/none), um deinen Rollout zu ermöglichen.
disableAutoUpdateUnderNative	Der Channel blockiert Updates, die älter als die Native-Baseline des Geräts sind.	Pushe eine Version, die auf oder über der Native-Baseline liegt, oder deaktiviere diesen Under-Native-Schutz.
disableAutoUpdateMetadata	Channel erfordert min_update_version Metadata; die App ist veraltet.	Setzen Sie min_update_version für das Ziel-Bundle oder Release aus einer neueren Native-Version.
disableAutoUpdateToMajor	Der Channel blockiert Major-Version-Sprünge.	Halten Sie Major-Versionen in derselben Channel-Strategie oder erlauben Sie Major-Sprünge für diesen Track.
disableAutoUpdateToMinor	Der Channel blockiert Minor-Version-Sprünge.	Halten Sie Minor-Versionen in derselben Channel-Strategie oder erlauben Sie Minor-Sprünge für diesen Track.
disableAutoUpdateToPatch	Der Channel blockiert Patch-Level-Sprünge für diesen Flow.	Passen Sie Ihren Release-Rhythmus an oder erlauben Sie Patch-Sprünge in der Channel-Policy für diesen Track.
disableEmulator	Emulator-Updates sind für diesen Channel nicht erlaubt.	Falls dies versehentlich geschah: Aktivieren Sie Emulator-Updates in einem Test-Channel zur Validierung. Falls beabsichtigt: Lassen Sie diesen Channel für Emulatoren gesperrt und nutzen Sie einen anderen Channel für Emulator-Builds.
disableDevBuild	Dev-Builds sind für diesen Channel blockiert.	Falls dies versehentlich geschah: Erlauben Sie Dev-Updates oder verschieben Sie das Gerät in einen Dev-fähigen Channel. Falls beabsichtigt: Lassen Sie diesen Channel auf Release-Builds beschränkt.
disableProdBuild	Ein Device-Build im Production-Modus namens /updates, während Ihr Channel ihn blockiert hat.	Falls dies ein Versehen war, erlaube Production-Updates für diesen Channel und veröffentliche ihn erneut. Falls dies beabsichtigt war, behalte die Einschränkung bei und sende Production-Builds in den richtigen Channel/Build.
cannotGetBundle	Capgo konnte keine gültige Download-URL für das ausgewählte Bundle erstellen.	Lade das Bundle erneut hoch (mit --delta falls du Delta-Files nutzen möchtest) und prüfe die R2/Public-Bundle-Einstellungen.
cannotUpdateViaPrivateChannel	Die App hat versucht, selbstständig in einen privaten Channel zu wechseln, der kein Self-Assignment erlaubt.	Aktivieren allow_device_self_set auf dem Channel oder wechsle zu einem öffentlichen/erlaubten Channel.
channelMisconfigured	Der Auto-Update-Rule für den Channel fehlen erforderliche Daten (version_number ohne min_update_version).	Ergänze die fehlende Konfiguration für diese Rule oder wechsle zu einem einfacheren Auto-Update-Modus.
missingBundle	Das Bundle enthält keinen downloadbaren Payload (fehlende external_url/r2_path und keine Delta-Files).	Version neu bauen/hochladen und prüfen, ob das Bundle echten Dateiinhalt hat.
NoChannelOrOverride	Kein Channel für dieses Gerät gefunden (kein Cloud-Default + kein Config-Fallback + kein Override).	Setze einen Channel-Default im Dashboard oder behalte einen Test bei defaultChannel in diesem Build.
rateLimited	Zu viele Update/Channel-Aufrufe in kurzer Zeit (oft Render-Loop) setChannel/getChannel).	Aufrufe nicht im Render tätigen. Nur bei User-Aktion aufrufen. Nutze defaultChannel in capacitor.config.
keyMismatch	Die App- und Bundle-Encryption-Key-IDs unterscheiden sich (device_key_id vs. bundle_key_id).	Vergleiche in der Console die Device- und Bundle-Key-IDs. Falls sie abweichen, mit demselben Key und passender CLI/Plugin-Version veröffentlichen; Key-Encoding kann zwischen Versionen variieren.
disableDevice	Ein echtes Phone/Tablet wurde blockiert, da dieser Channel für echte Geräte gesperrt ist.	Falls versehentlich: Aktiviere Real-Device-Updates in diesem Channel. Falls gewollt: Blockierung beibehalten und echte Geräte auf einen anderen Channel routen.
disablePlatformElectron	Electron ist in diesem Channel gesperrt.	Falls dies ein Versehen war, aktiviere Electron in diesem Channel und veröffentliche das Routing neu. Falls beabsichtigt, lass es gesperrt und leite Electron-Nutzer auf einen eigenen Channel um.
customIdBlocked	A custom device ID was sent, but this app does not accept custom IDs.	Deaktiviere das Senden benutzerdefinierter IDs oder aktiviere sie nur, wenn dein Workflow dies erfordert.
blocked_by_server_url	Die App hat server.url konfiguriert, sodass Capacitor eine Remote-URL statt lokaler Dateien bereitstellt.	Entferne/lösche server.url für Production-Builds, um die Update-Payloads lokal zu halten.
backend_refusal	Der Updater ist v4, was vom Backend nicht mehr akzeptiert wird.	Upgrade von plugin/CLI auf v5+ (bevorzugt v8), mit Capacitor v5+, dann Bundle-Metadaten neu bauen und erneut veröffentlichen.
Konfigurations- oder Policy-Blockaden

Code(s)	Warum das Update blockiert wurde
disableAutoUpdate, disableAutoUpdateToMajor, disableAutoUpdateToMinor, disableAutoUpdateToPatch, disableAutoUpdateMetadata, disableAutoUpdateUnderNative	Channel-Strategie verbietet dies Semver-Sprung
disablePlatformIos, disablePlatformAndroid	Plattform ist für diesen Channel deaktiviert
disableDevBuild, disableEmulator	Dev-Builds oder Emulatoren nicht erlaubt
disableProdBuild, disableDevice, disablePlatformElectron	Production-Builds, echte Geräte oder Electron sind für diesen Channel blockiert.
customIdBlocked	Custom Device IDs werden für diese App nicht akzeptiert.
cannotUpdateViaPrivateChannel, NoChannelOrOverride, channelMisconfigured	Channel-Auswahl oder Override fehlgeschlagen
missingBundle, cannotGetBundle	Der Channel zeigt auf ein Bundle, das Capgo nicht bereitstellen kann
needPlanUpgrade	Limit des Plans oder der Geräte erreicht

Download-, Integritäts- oder Installationsfehler

Code(s)	Bedeutung
download_fail	Bundle-Download fehlgeschlagen (Netzwerk- oder Response-Fehler)
download_manifest_file_fail, download_manifest_checksum_fail, download_manifest_brotli_fail	Delta-Datei konnte nicht abgerufen oder validiert werden
checksum_fail, checksum_required	Integritätsprüfung fehlgeschlagen oder Checksumme fehlt
unzip_fail, directory_path_fail, canonical_path_fail, windows_path_fail	Dateisystem- oder Unzip-Validierung fehlgeschlagen
decrypt_fail	Decryption failed (encrypted bundle)
update_fail	Bundle installiert, aber App wurde nicht aufgerufen notifyAppReady(); Rollback ausgelöst
download_zip_* ohne nachfolgende set	Download abgeschlossen, aber Installation nicht beendet

Runtime-/Plattform-Events

Code(s)	Bedeutung
app_crash, app_crash_native	Crash-Events aus dem JavaScript- oder Native-Runtime-Layer. Metadaten enthalten oft Stack-Traces, die Quelle und die aktive Version.
app_anr	Android meldete „Application Not Responding“.
app_killed_low_memory, app_killed_excessive_resource_usage	Beendigung des App-Prozesses aufgrund von Speicher- oder Ressourcenlimits.
app_initialization_failure, app_memory_warning	Der Startup wurde unterbrochen oder es wurde vor der normalen Runtime hoher Speicherverbrauch festgestellt.
webview_javascript_error, webview_unhandled_rejection, webview_resource_error, webview_security_policy_violation, webview_unclean_restart, webview_render_process_gone, webview_content_process_terminated	WebView-Lifecycle und JS/Rendering-Fehler. Installiere Sentry sowohl im JS- als auch im Native-Layer, um Stack-Traces, Session-/Device-Kontext und URL/State für schnellere Fixes zu erfassen.
os_version_changed, native_app_version_changed	OS oder native App-Version hat sich geändert; dies hilft, Plattform-Rollout-Effekte von Web-Bundle-Verhalten zu unterscheiden.

➡️ Brauchst du mehr code Hilfe? Siehe Vollständige Code Log-Referenz und Debugging-Guide.

Mehr Details zu einem Log

Wenn du auf einen bestimmten Log-Eintrag klickst, gelangst du normalerweise zu den Geräte-Seite. Dort siehst du die gesamte Historie dieses Geräts, was bei der Diagnose gerätespezifischer Probleme oder beim Nachvollziehen des Update-Verlaufs sehr hilfreich sein kann.

Weiter mit den Logs

Wenn du es nutzt Logs um Dashboard- und API-Operationen zu planen, verbinde es mit API Übersicht für Details zur Implementierung im API Overview, Einführung für die Implementierungsdetails in der Einleitung, API Schlüssel für die Implementierungsdetails in API Keys, Geräte für die Implementierungsdetails in Devices und Bundles für die Implementierungsdetails in Bundles.