Early AccessNur auf Einladung, und die SDKs sind noch nicht veröffentlicht.Einladung anfragen
Zum Inhalt springen
Docs

Android

Strukturierte Logs aus deiner Android-App, in Kotlin oder Java. Keine Abhängigkeiten außer der Kotlin-Standardbibliothek.

Smartphones und Tablets, in Kotlin oder Java

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-out

Lyrelog.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:

EventLevelWas es enthält
app_crashedcriticalerror_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).

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 recording

PENDING 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 launch

flush 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 wie 10.0.2.2 zu 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:

  1. 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 signingReport anzeigt.
  2. 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

OptionStandardBedeutung
apiKeyPflichtDer Ingest-Schlüssel des Projekts
endpointhttps://ingest.lyrelog.comDie Basis-URL; ein eingefügter Pfad /v1/... wird entfernt. Nur https, http nur für localhost und 10.0.2.2 im Emulator
consentConsent.GRANTEDPENDING, GRANTED oder DENIED
minimumLevelLevel.DEBUGEvents darunter erreichen nie die Festplatte
flushIntervalMillis15 sWie oft der Uploader läuft, solange eine Activity gestartet ist
maxBatchBytes512 KiBEin Batch schließt bei dem Limit, das zuerst erreicht wird (höchstens 4 MiB)
maxBatchEvents500Höchstens 2.000
maxDiskBytes20 MBObergrenze für die Warteschlange auf der Festplatte, älteste zuerst
maxEventAgeMillis7 TageÄltere Events in der Warteschlange werden verworfen
sessionTimeoutMillis30 minInaktive Zeit, nach der eine neue Session beginnt
environmenterkanntJeder gültige Name oder null
platformandroidJeder gültige Name oder null
appVersionder versionName der AppGesendet als resource.app_version
redactedKeysnull: DEFAULT_REDACTED_KEYSZu schwärzende Schlüsselnamen; deine Liste ersetzt die Standardwerte, eine leere Liste schaltet es ab
captureCrashestrueNicht abgefangene Exceptions aufzeichnen, beim nächsten Start gesendet
attachScreentrueEvents mit dem aktuellen Screen taggen
automaticScreensfalsescreen_viewed für jede Activity loggen, benannt nach ihrer Klasse
attesttrueDie App mit Key Attestation nachweisen, damit ihre Events verifiziert ankommen, sobald das Projekt ihr Package und Zertifikat kennt
mirrorToLogcatfalseJedes Event zusätzlich in logcat ausgeben (Tag Lyrelog)
storageDirectorynoBackupFilesDir/lyrelogWo die Warteschlange liegt

Zustellung und Limits

Blockiert nieLoggen 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 OfflineEine 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 sendetAlle 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.
BatchesBis 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.
Wiederholungen1 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.
MonatskontingentWenn 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 sichtbarEvents, die durch die Obergrenzen verloren gehen, werden zu einer Warnung lyrelog_events_dropped (Bereich lyrelog) mit der Anzahl.
Eigene ProblemeEin falscher Endpoint, ein 404, abgelehnte Zeilen oder ein Endpoint, der nicht antwortet, gehen einmal pro Start in logcat, Tag Lyrelog, auf Debug-Level.
KontextApp-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.
SecretsWerte 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.
LimitsLange 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 setUser auf.
  • App activity > App interactions: wenn du Screens (screen_viewed) oder Taps loggst.
  • Alles andere, was deine attrs oder payload enthalten (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.