Android
Strukturierte Logs aus deiner Android-App, in Kotlin oder Java. Keine Abhängigkeiten außer der Kotlin-Standardbibliothek.
Das Android-SDK braucht Android 7.0 (API 24) oder neuer. Es ist in Kotlin geschrieben, hat keine Abhängigkeiten außer der Kotlin-Standardbibliothek (kein OkHttp, keine Coroutines, kein AndroidX), und jede Funktion lässt sich auch aus Java aufrufen.
Interne Vorschau: Dieses Paket ist noch nicht veröffentlicht. Bis dahin kann Gradle
com.lyrelog:lyrelog-android nicht laden: Es liegt nicht auf Maven Central, und das Repository
ist privat und hat noch kein Release.
Installation
Von Maven Central, in der build.gradle.kts deines App-Moduls:
dependencies {
implementation("com.lyrelog:lyrelog-android:0.1.0")
}Die Bibliothek fügt dem Manifest deiner App die Berechtigung INTERNET hinzu.
Starten
Starte einmal, so früh wie möglich, im onCreate deiner Application. Ein zweiter Aufruf,
während es läuft, wird ignoriert. Events, die vor start geloggt werden, werden ebenfalls
ignoriert, aber setUser und setConsent, vor start aufgerufen, bleiben erhalten und werden
angewendet, sobald es läuft.
import android.app.Application
import com.lyrelog.Configuration
import com.lyrelog.Lyrelog
class MyApp : Application() {
override fun onCreate() {
super.onCreate()
Lyrelog.start(this, Configuration(
apiKey = "lyr_ing_...", // ingest-only: it can append events, never read them
))
}
}Trage die Klasse im Manifest ein (<application android:name=".MyApp" ...>), falls deine App noch
keine Application hat.
Events gehen an https://ingest.lyrelog.com. Übergib endpoint nur, um sie woanders hinzuschicken.
Das ist die Basis-URL (ein eingefügter Pfad .../v1/events:batch wird entfernt) und muss https
sein; unverschlüsseltes http geht nur für localhost, 127.0.0.1 oder ::1 und im Emulator für
10.0.2.2 (siehe In Entwicklung und Tests). Mit jedem anderen
Endpoint wird nichts gesendet, und die Events bleiben auf dem Gerät.
Events loggen
Eine Funktion pro Level: trace, debug, info, notice, warning, error, critical, oder
log(level, message, ...) mit einem Level.
Lyrelog.info("checkout_done", attrs = mapOf("items" to 3, "latency_ms" to ms))
Lyrelog.error("payment_declined", category = "checkout",
attrs = mapOf("code" to 51), payload = mapOf("response" to raw))Attribute sind eine Map<String, Any?>: Strings, Zahlen, Booleans, null, Listen (ihre Elemente
werden als Strings gesendet) und verschachtelte Maps bis 4 Ebenen. Die Payload ist eine beliebige
Map, Liste oder ein Wert, für die Details, die du nur liest, wenn du ein einzelnes Event öffnest.
Logger für jeden Bereich
Ein Logger versieht jedes Event mit seiner category, wie ein Android-Log-Tag. Er hat jedes Level,
dazu log und captureError. Er ist günstig zu erzeugen und aufzubewahren und loggt in das SDK,
das gerade läuft, wenn er aufgerufen wird.
val sync = Lyrelog.logger("sync")
sync.warning("sync_conflict", mapOf("records" to 2))Nutzer
Lyrelog.setUser(playerId) // attached to every following event
Lyrelog.setUser(null) // on sign-outLyrelog.sessionId liefert die ID der aktuellen Session, zum Beispiel zum Anzeigen in einem
Support-Screen.
Die Nutzer-ID wird zwischen Starts nicht gespeichert: Rufe setUser bei jedem Start erneut auf,
sobald du weißt, wer die Person ist.
Screens
Sag, wo die Person gerade ist. Lyrelog loggt screen_viewed (Bereich navigation) mit dem
vorherigen Screen und den darauf verbrachten Sekunden und versieht jedes folgende Event mit einem
Attribut screen.
override fun onResume() {
super.onResume()
Lyrelog.screen("Settings")
}In Compose rufst du es aus einem LaunchedEffect auf, wenn ein Ziel angezeigt wird. Das Event
trägt screen, previous_screen und seconds_on_previous. Ein erneuter Aufruf von screen mit
demselben Namen loggt nichts. screen nimmt zusätzliche attrs für das Event screen_viewed.
Schalte das Taggen mit attachScreen = false ab.
automaticScreens = true erledigt das für jede Activity, die in den Vordergrund kommt, benannt
nach ihrer Klasse (SettingsActivity). Standardmäßig ist es aus: Apps mit Compose und Fragments
haben viele Screens in einer Activity, und ein selbst gewählter Name liest sich im Dashboard
besser.
Abgefangene Fehler
try {
store.purchase(product)
} catch (e: IOException) {
Lyrelog.captureError(e, category = "store")
}Es sendet das Event exception, das jedes SDK sendet: Level error, die Attribute error_type
(der Klassenname) und error_message und eine Payload mit der Beschreibung, bis zu 60 Frames, den
Ursachen (bis zu 8, je 20 Frames) und unterdrückten Exceptions. attrs fügt eigene hinzu; level
ändert das Level. Jeder Logger hat ebenfalls captureError.
Die Frames sind so, wie die VM sie meldet. Wenn die App mit R8 minifiziert ist, führe retrace
mit der Mapping-Datei des Builds aus, um die ursprünglichen Namen zu bekommen.
Abstürze
Eine nicht abgefangene Exception wird sofort auf die Festplatte geschrieben, auf dem sterbenden Thread, zusammen mit jedem Event, das noch auf dem Weg zur Festplatte ist. Danach wird sie an den Handler übergeben, der vorher da war (den Absturzdialog des Systems oder einen anderen Crash Reporter, der sich zuerst installiert hat). In diesem Moment wird nichts gesendet: Der Prozess ist gleich zu Ende.
Der nächste Start sendet sie, mit dem Zeitstempel des Absturzes und in der Session, die
sie beendet hat, im Bereich diagnostics, wie die Absturzberichte des Swift-SDKs, sodass die
Abstürze beider Plattformen im Dashboard beieinanderliegen:
| Event | Level | Was es enthält |
|---|---|---|
app_crashed | critical | error_type, error_message, handled: false, mechanism: uncaught_exception und eine Payload mit dem Thread, den Frames, den Ursachen und unterdrückten Exceptions |
Standardmäßig an; schalte es mit captureCrashes = false ab. Native Abstürze und ANRs werden
nicht gemeldet.
Umgebungen und Plattform
Beim Start wählt das SDK die Umgebung: development, wenn die App debuggable ist
(android:debuggable, jeder Debug-Build), sonst production.
Deine eigenen Debug-Builds senden development, während das Dashboard mit production öffnet:
Wähle development in der oberen Leiste, um sie zu sehen.
Die Plattform ist android. Beides lässt sich in der Konfiguration überschreiben:
Configuration(
apiKey = key,
environment = if (BuildConfig.FLAVOR == "beta") "beta" else null, // null = detected
platform = null,
)Jeder Name geht: Kleinbuchstaben, Ziffern, - und _, bis zu 32 Zeichen. Anderer Text wird in
einen gültigen Namen umgewandelt (Staging EU wird zu staging-eu).
Einwilligung
Lyrelog.start(this, Configuration(apiKey = key, consent = Consent.PENDING))
// later, when the person chooses:
Lyrelog.setConsent(Consent.GRANTED) // sends, including what was kept while pending
Lyrelog.setConsent(Consent.DENIED) // deletes everything and stops recordingPENDING behält Events auf dem Gerät, ohne sie zu senden. Ohne erteilte Einwilligung wird nichts
hochgeladen, auch nicht, was ein früherer Start hinterlassen hat. Ein Start mit Consent.DENIED
löscht die Installations-ID und alles, was von einem früheren Start noch in der Warteschlange
liegt, und zeichnet nichts auf. Ein setConsent vor start hat Vorrang vor Configuration.consent.
Die Einwilligung wird zwischen Starts nicht gespeichert: Speichere die Entscheidung der Person
selbst und übergib sie jedes Mal an start.
Eine vollständige App
Starte mit der gespeicherten Einwilligung, setze die Person beim Anmelden und tagge Screens:
import android.app.Application
import com.lyrelog.Configuration
import com.lyrelog.Consent
import com.lyrelog.Lyrelog
class MyApp : Application() {
override fun onCreate() {
super.onCreate()
val prefs = getSharedPreferences("settings", MODE_PRIVATE)
val consent = when (prefs.getString("diagnostics", null)) {
"granted" -> Consent.GRANTED
"denied" -> Consent.DENIED
else -> Consent.PENDING
}
Lyrelog.start(this, Configuration(apiKey = "lyr_ing_...", consent = consent))
}
}
class HomeActivity : AppCompatActivity() {
override fun onResume() {
super.onResume()
Lyrelog.screen("Home")
}
private fun signedIn(account: Account) {
Lyrelog.setUser(account.id)
Lyrelog.info("signed_in", category = "auth")
}
}
fun choose(context: Context, allowed: Boolean) {
context.getSharedPreferences("settings", Context.MODE_PRIVATE).edit()
.putString("diagnostics", if (allowed) "granted" else "denied").apply()
Lyrelog.setConsent(if (allowed) Consent.GRANTED else Consent.DENIED)
}Flush und Stopp
Der Wechsel in den Hintergrund sendet bereits (wenn die letzte Activity stoppt; eine Drehung zählt nicht), du brauchst es also selten.
Lyrelog.flushInBackground() // send now, without waiting
Lyrelog.flush() // write everything to disk and send, waiting up to 5 seconds
Lyrelog.stop() // send what's queued (up to 2 seconds), then stop
Lyrelog.stopNow() // stop at once; what was logged goes with the next launchflush und stop blockieren, also rufe sie nie auf dem Main Thread auf. flush gibt true
zurück, wenn es rechtzeitig fertig wurde, und respektiert ein Retry-After, das der Server
verlangt hat: Es sendet nicht früher. Nach stop kann start erneut aufgerufen werden.
In Entwicklung und Tests
Rufe Lyrelog.start in Unit-Tests nicht auf: Alles, was vor start geloggt wird, wird ignoriert,
also läuft der Rest deines Codes unverändert. mirrorToLogcat = true gibt jedes Event während der
Arbeit zusätzlich in logcat aus (Tag Lyrelog).
Debug-Builds senden die Umgebung development. Um aus dem Emulator an einen Endpoint auf deinem
Rechner zu senden, nutze http://10.0.2.2 mit dessen Port als Endpoint (10.0.2.2 ist dein
Rechner aus Sicht des Emulators), nur im Debug-Build:
- Erlaube unverschlüsseltes http zu
10.0.2.2. Android blockiert es, sofern die App es nicht erlaubt: Füge dem Debug-Build eine Network Security Config hinzu, die Cleartext für genau diese Adresse zulässt. - Unter Android 17 braucht eine App mit Target API 37 außerdem
ACCESS_LOCAL_NETWORK, um eine private Adresse wie10.0.2.2zu erreichen; ohne sie läuft die Verbindung einfach in ein Timeout. Deklariere die Berechtigung im Debug-Manifest (src/debug/AndroidManifest.xml) und erteile sie:adb shell pm grant <your.app> android.permission.ACCESS_LOCAL_NETWORK.
Das ist nur für die lokale Entwicklung. Der gehostete Ingest ist eine öffentliche https-Adresse
und braucht nichts davon.
Verifizierte Events
Ein verifiziertes Event ist eines, das nicht von jemandem gesendet worden sein kann, der den öffentlichen Ingest-Schlüssel aus einer App oder einer Webseite kopiert hat. Was das beweist und was nicht, steht unter Verifizierte Events.
Die Events einer Android-App werden mit Key Attestation verifiziert: Die sichere Hardware des Telefons beweist, dass sie von deiner eigenen App kommen, signiert mit deinem Zertifikat, auf einem echten Gerät, das weder gerootet noch entsperrt wurde. Lyrelog prüft das auf seinen eigenen Servern; kein Google-Konto, kein Play Integrity und kein Google-Cloud-Projekt sind beteiligt.
Es ist standardmäßig an (attest in Configuration); richte es im Projekt ein:
- Füge in den Projekteinstellungen
unter Verified events from your Android apps dein Package und den SHA-256-Fingerabdruck
jedes Zertifikats hinzu, das Builds signiert, die Events senden: den App-Signaturschlüssel von
Play (Play Console, Test and release, App integrity) und, für Builds, die du selbst
signierst, den, den
./gradlew signingReportanzeigt. - In der App ist das alles. Zum Abschalten:
Lyrelog.start(this, Configuration(apiKey = "lyr_ing_...", attest = false))Einmal pro Installation erzeugt das SDK einen Schlüssel in der sicheren Hardware des Telefons
(StrongBox oder die Trusted Execution Environment) und lässt ihn vom Gerät attestieren; ab dann
tragen seine Batches ein Token und kommen verifiziert an (verified_by ist key_attestation).
Das Token gilt 24 Stunden und wird vor Ablauf im Hintergrund erneuert. Das Senden wartet nie
auf die Attestierung: Bis die App ein Token hat, und sobald etwas fehlschlägt, werden Events unverifiziert
gesendet.
- Emulatoren verifizieren nie, und das SDK versucht es dort gar nicht.
- Solange im Projekt keine Android-App eingerichtet ist, oder wenn der Schlüssel abgelehnt wird oder das Gerät nicht attestieren kann, schaltet das SDK die Attestierung für diesen Start ab und meldet das einmal in logcat.
- Ein Gerät, das der Server ablehnt (ein gerootetes Telefon, ein entsperrter Bootloader, ein Zertifikat, das das Projekt nicht kennt), versucht es einen Tag später erneut.
- Eine verweigerte Einwilligung löscht den attestierten Schlüssel und seinen Eintrag
(
noBackupFilesDir/lyrelog/attest.json).
Solange es nicht eingerichtet ist, kommen Events unverifiziert an und zählen zum
Tagesanteil einer Adresse. Bevor du das
Projekt nur noch verifizierte Events von android annehmen lässt, prüfe im Explorer, dass die
Events deiner echten Nutzer verifiziert ankommen: Events von älteren Versionen, Emulatoren und
abgelehnten Geräten würden mit einem 425 zurückgehalten.
Events, die deine eigenen Server mit einem Server-Schlüssel, lyr_srv_..., senden, sind
verifiziert. Packe nie einen Server-Schlüssel in eine App: Alles, was in einer APK ausgeliefert
wird, lässt sich auslesen.
Zum Prüfen öffne den Explorer: Ein geöffnetes Event zeigt die Verifizierung unter Context in seiner Zeile Sender: Verified, Key Attestation oder Not verified, public key.
Unter Verifizierte Events steht, wer was verifiziert, und alles zum Tagesanteil.
Aus Java
Jede Funktion auf Lyrelog ist aus Java statisch, mit Überladungen für die optionalen Argumente:
Lyrelog.start(this, new Configuration("lyr_ing_..."));
Lyrelog.info("checkout_done");
Lyrelog.captureError(e, "store");Configuration und die Funktionen eines Loggers haben ebenfalls Überladungen, sodass sich
nachfolgende Argumente weglassen lassen (logger.warning("sync_conflict"),
logger.warning("sync_conflict", attrs)).
Konfiguration
| Option | Standard | Bedeutung |
|---|---|---|
apiKey | Pflicht | Der Ingest-Schlüssel des Projekts |
endpoint | https://ingest.lyrelog.com | Die Basis-URL; ein eingefügter Pfad /v1/... wird entfernt. Nur https, http nur für localhost und 10.0.2.2 im Emulator |
consent | Consent.GRANTED | PENDING, GRANTED oder DENIED |
minimumLevel | Level.DEBUG | Events darunter erreichen nie die Festplatte |
flushIntervalMillis | 15 s | Wie oft der Uploader läuft, solange eine Activity gestartet ist |
maxBatchBytes | 512 KiB | Ein Batch schließt bei dem Limit, das zuerst erreicht wird (höchstens 4 MiB) |
maxBatchEvents | 500 | Höchstens 2.000 |
maxDiskBytes | 20 MB | Obergrenze für die Warteschlange auf der Festplatte, älteste zuerst |
maxEventAgeMillis | 7 Tage | Ältere Events in der Warteschlange werden verworfen |
sessionTimeoutMillis | 30 min | Inaktive Zeit, nach der eine neue Session beginnt |
environment | erkannt | Jeder gültige Name oder null |
platform | android | Jeder gültige Name oder null |
appVersion | der versionName der App | Gesendet als resource.app_version |
redactedKeys | null: DEFAULT_REDACTED_KEYS | Zu schwärzende Schlüsselnamen; deine Liste ersetzt die Standardwerte, eine leere Liste schaltet es ab |
captureCrashes | true | Nicht abgefangene Exceptions aufzeichnen, beim nächsten Start gesendet |
attachScreen | true | Events mit dem aktuellen Screen taggen |
automaticScreens | false | screen_viewed für jede Activity loggen, benannt nach ihrer Klasse |
attest | true | Die App mit Key Attestation nachweisen, damit ihre Events verifiziert ankommen, sobald das Projekt ihr Package und Zertifikat kennt |
mirrorToLogcat | false | Jedes Event zusätzlich in logcat ausgeben (Tag Lyrelog) |
storageDirectory | noBackupFilesDir/lyrelog | Wo die Warteschlange liegt |
Zustellung und Limits
| Blockiert nie | Loggen kopiert das Event und kehrt zurück; ein einzelner Writer im Hintergrund schreibt es auf die Festplatte und wartet nie auf das Netzwerk. |
| Übersteht Beenden und Offline | Eine Warteschlange in noBackupFilesDir/lyrelog, begrenzt auf 20 MB und 7 Tage. Was die Festplatte erreicht hat, übersteht einen Absturz, ein Beenden oder Tage ohne Netz; Events, die noch auf dem Weg zum Writer sind (Millisekunden), schreibt der Crash Handler, oder sie gehen verloren, wenn der Prozess hart beendet wird. Der Ordner landet nie in einem Backup, sodass ein wiederhergestelltes Telefon nicht die Events eines anderen Geräts erneut sendet. |
| Wann es sendet | Alle 15 s, solange eine Activity gestartet ist, und einmal, wenn die App in den Hintergrund geht. Im Hintergrund läuft kein Timer: Der Rest geht beim nächsten Start raus oder wenn die App das nächste Mal in den Vordergrund kommt. |
| Batches | Bis zu 500 Events oder 512 KiB pro Request, mit gzip. Ein Event, das kodiert größer als 1 MiB ist, wird verworfen und gezählt. |
| Wiederholungen | 1 s, verdoppelt bis 5 min, mit Full Jitter, unter Beachtung von Retry-After. Jeder andere 4xx-Status verwirft den Batch, ein 3xx (eine Weiterleitung, nie verfolgt) verwirft ihn, und ein widerrufener Schlüssel (401, 403) stoppt das Senden bis zum nächsten Start und behält die Events. Ein Batch, an dem der Server immer wieder scheitert, während andere durchgehen, wandert nach hinten und wird dann verworfen. |
| Monatskontingent | Wenn eine Free-Organisation die Events ihres Monats verbraucht hat, antwortet der Server mit 429. Die Events bleiben in der Warteschlange auf der Festplatte und gehen raus, sobald der Server sie wieder annimmt, innerhalb der Obergrenzen von 20 MB und 7 Tagen. Das SDK loggt eine Warnung in logcat, und erneut erst, nachdem zwischendurch ein Batch angenommen wurde. |
| Verluste sind sichtbar | Events, die durch die Obergrenzen verloren gehen, werden zu einer Warnung lyrelog_events_dropped (Bereich lyrelog) mit der Anzahl. |
| Eigene Probleme | Ein falscher Endpoint, ein 404, abgelehnte Zeilen oder ein Endpoint, der nicht antwortet, gehen einmal pro Start in logcat, Tag Lyrelog, auf Debug-Level. |
| Kontext | App-ID (der Package-Name), Version Name, Version Code, android, die Android-Version, das Gerät (Google Pixel 9), Locale, Umgebung, Plattform android, Session-ID (neu nach 30 min Inaktivität) und Installations-ID. |
| Secrets | Werte unter Schlüsseln, deren Name authorization, cookie, password, token, secret, apikey oder ein anderer Eintrag der gemeinsamen Liste ist oder darauf endet, werden zu "[redacted]", auf jeder Ebene, bevor etwas gekürzt wird. |
| Limits | Lange Strings werden an einer Zeichengrenze gekürzt, überzählige Attribute in lyrelog_dropped_attrs gezählt, Payloads über 64 KiB zusammengefasst als {"lyrelog_truncated": true, "bytes": N, "preview": "..."}. |
Ändere die Liste mit redactedKeys: Deine Liste ersetzt die Standardwerte, und eine leere Liste
schaltet das Schwärzen ab. Um etwas hinzuzufügen:
Lyrelog.start(this, Configuration(
apiKey = "lyr_ing_...",
redactedKeys = Configuration.DEFAULT_REDACTED_KEYS + "pin",
))Datensicherheit bei Play
Gib im Formular zur Datensicherheit in der Play Console an, was deine App über Lyrelog sendet:
- App info and performance: Crash logs, Diagnostics (App functionality, und Analytics, wenn du es so nutzt). Erhoben, nicht weitergegeben.
- Device or other IDs: die Installations-ID, eine zufällige UUID, die nicht die Werbe-ID ist,
nicht gesichert wird und bei einer Verweigerung gelöscht wird. Nicht mit der Person verknüpft,
es sei denn, du rufst auch
setUserauf. - App activity > App interactions: wenn du Screens (
screen_viewed) oder Taps loggst. - Alles andere, was deine
attrsoderpayloadenthalten (E-Mails, Käufe...), unter der jeweils passenden Kategorie.
Die Daten werden bei der Übertragung verschlüsselt (https). Der Server ergänzt das Land der
sendenden Adresse; die Adresse selbst wird nicht gespeichert.