Accès anticipéSur invitation, et les SDK ne sont pas encore publiés.Demander une invitation
Aller au contenu
Docs

Android

Des logs structurés depuis votre app Android, en Kotlin ou en Java. Aucune dépendance en dehors de la bibliothèque standard Kotlin.

Téléphones et tablettes, en Kotlin ou Java

Le SDK Android nécessite Android 7.0 (API 24) ou plus récent. Il est écrit en Kotlin, n'a aucune dépendance en dehors de la bibliothèque standard Kotlin (ni OkHttp, ni coroutines, ni AndroidX), et chaque fonction peut aussi être appelée depuis Java.

Préversion interne : ce package n'est pas encore publié. D'ici là, Gradle ne peut pas récupérer com.lyrelog:lyrelog-android : il n'est pas sur Maven Central, et le dépôt est privé et n'a encore aucune release.

Installation

Depuis Maven Central, dans le build.gradle.kts du module de votre app :

dependencies {
    implementation("com.lyrelog:lyrelog-android:0.1.0")
}

La bibliothèque ajoute la permission INTERNET au manifeste de votre app.

Démarrage

Démarrez une seule fois, le plus tôt possible, dans le onCreate de votre Application. Un second appel pendant qu'il tourne est ignoré. Les événements journalisés avant start sont ignorés eux aussi, mais setUser et setConsent appelés avant start sont conservés et appliqués au démarrage.

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
        ))
    }
}

Déclarez la classe dans le manifeste (<application android:name=".MyApp" ...>) si votre app n'a pas encore d'Application.

Les événements partent vers https://ingest.lyrelog.com. Ne passez endpoint que pour les envoyer ailleurs. C'est l'URL de base (un chemin .../v1/events:batch collé est retiré) et elle doit être en https ; le http simple ne fonctionne que pour localhost, 127.0.0.1 ou ::1, et sur l'émulateur pour 10.0.2.2 (voir En développement et dans les tests). Avec tout autre endpoint, rien n'est envoyé et les événements restent sur l'appareil.

Journaliser des événements

Une fonction par niveau : trace, debug, info, notice, warning, error, critical, ou log(level, message, ...) avec un 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))

Les attributs sont une Map<String, Any?> : chaînes, nombres, booléens, null, listes (leurs éléments envoyés comme chaînes) et maps imbriquées jusqu'à 4 niveaux. Le payload est n'importe quelle map, liste ou valeur, pour le détail que vous ne lisez qu'en ouvrant un événement.

Un logger par domaine

Un logger appose sa category sur chaque événement, comme un tag de log Android. Il a tous les niveaux, plus log et captureError. Il est peu coûteux à créer et à conserver, et journalise dans le SDK en cours d'exécution au moment de l'appel.

val sync = Lyrelog.logger("sync")
sync.warning("sync_conflict", mapOf("records" to 2))

Utilisateurs

Lyrelog.setUser(playerId)   // attached to every following event
Lyrelog.setUser(null)       // on sign-out

Lyrelog.sessionId donne l'id de la session en cours, par exemple pour l'afficher dans un écran d'assistance.

L'id utilisateur n'est pas conservé d'un lancement à l'autre : appelez de nouveau setUser à chaque lancement, dès que vous savez de qui il s'agit.

Écrans

Indiquez où se trouve la personne. Lyrelog journalise screen_viewed (domaine navigation) avec l'écran précédent et les secondes passées dessus, et marque chaque événement suivant d'un attribut screen.

override fun onResume() {
    super.onResume()
    Lyrelog.screen("Settings")
}

Avec Compose, appelez cette fonction depuis un LaunchedEffect quand une destination s'affiche. L'événement porte screen, previous_screen et seconds_on_previous. Rappeler screen avec le même nom ne journalise rien. screen accepte des attrs supplémentaires pour l'événement screen_viewed. Désactivez le marquage avec attachScreen = false.

automaticScreens = true le fait pour chaque Activity qui passe au premier plan, nommée d'après sa classe (SettingsActivity). C'est désactivé par défaut : les apps Compose et à fragments ont de nombreux écrans dans une seule Activity, et un nom que vous choisissez se lit mieux dans le tableau de bord.

Les erreurs que vous interceptez

try {
    store.purchase(product)
} catch (e: IOException) {
    Lyrelog.captureError(e, category = "store")
}

Cela envoie l'événement exception qu'envoient tous les SDK : niveau error, les attributs error_type (le nom de la classe) et error_message, et un payload avec la description, jusqu'à 60 frames, les causes (jusqu'à 8, 20 frames chacune) et les exceptions supprimées. attrs ajoute les vôtres ; level change le niveau. Chaque logger a aussi captureError.

Les frames sont telles que la VM les rapporte. Quand l'app est minifiée avec R8, lancez retrace avec le fichier de mapping du build pour retrouver les noms d'origine.

Plantages

Une exception non interceptée est écrite sur disque sur-le-champ, sur le thread qui meurt, avec tout événement encore en route vers le disque. Elle est ensuite transmise au handler qui était en place avant (la boîte de dialogue de plantage du système, ou un autre outil de rapport de plantage qui en avait installé un avant). Rien n'est envoyé à ce moment-là : le processus est sur le point de se terminer.

Le lancement suivant l'envoie, daté du moment où il s'est produit et dans la session qu'il a interrompue, dans le domaine diagnostics, comme les rapports de plantage du SDK Swift, si bien que les plantages des deux plateformes se retrouvent côte à côte dans le tableau de bord :

ÉvénementNiveauCe qu'il contient
app_crashedcriticalerror_type, error_message, handled: false, mechanism: uncaught_exception, et un payload avec le thread, les frames, les causes et les exceptions supprimées

C'est activé par défaut ; désactivez-le avec captureCrashes = false. Les plantages natifs et les ANR ne sont pas remontés.

Environnements et plateforme

Au démarrage, le SDK choisit l'environnement : development quand l'app est débogable (android:debuggable, tout build de debug), production sinon.

Vos propres builds de debug envoient development, alors que le tableau de bord s'ouvre sur production : choisissez development dans la barre du haut pour les voir.

La plateforme est android. Vous pouvez remplacer l'un ou l'autre dans la configuration :

Configuration(
    apiKey = key,
    environment = if (BuildConfig.FLAVOR == "beta") "beta" else null,   // null = detected
    platform = null,
)

N'importe quel nom convient : lettres minuscules, chiffres, - et _, jusqu'à 32 caractères. Tout autre texte est transformé en nom valide (Staging EU devient 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 garde les événements sur l'appareil sans les envoyer. Rien n'est envoyé tant que le consentement n'est pas accordé, y compris ce qu'un lancement précédent a laissé. Démarrer avec Consent.DENIED supprime tout ce qui reste en file depuis un lancement précédent ainsi que l'id d'installation, et n'enregistre rien. Un setConsent appelé avant start l'emporte sur Configuration.consent.

Le consentement n'est pas conservé d'un lancement à l'autre : stockez vous-même le choix de la personne et passez-le à start à chaque fois.

Une app complète

Démarrez avec le consentement stocké, définissez la personne quand elle se connecte et marquez les écrans :

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)
}

Vider la file et arrêter

Le passage en arrière-plan envoie déjà (quand la dernière Activity s'arrête ; une rotation ne compte pas) : vous en aurez donc rarement besoin.

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 et stop sont bloquantes : ne les appelez donc jamais sur le thread principal. flush renvoie true quand elle a terminé à temps, et respecte un Retry-After demandé par le serveur : elle n'envoie pas plus tôt. Après stop, start peut être rappelée.

En développement et dans les tests

N'appelez pas Lyrelog.start dans les tests unitaires : tout ce qui est journalisé avant start est ignoré, et le reste de votre code s'exécute sans changement. mirrorToLogcat = true affiche aussi chaque événement dans logcat (tag Lyrelog) pendant que vous travaillez.

Les builds de debug envoient l'environnement development. Pour envoyer depuis l'émulateur vers un endpoint qui tourne sur votre ordinateur, utilisez http://10.0.2.2 et son port comme endpoint (10.0.2.2 est votre ordinateur, vu depuis l'émulateur), dans le build de debug uniquement :

  • Autorisez le http simple vers 10.0.2.2. Android le bloque sauf si l'app l'autorise : ajoutez au build de debug une network security config qui permet le trafic en clair pour cette seule adresse.
  • Sur Android 17, une app qui cible l'API 37 a aussi besoin de ACCESS_LOCAL_NETWORK pour joindre une adresse privée comme 10.0.2.2 ; sans elle, la connexion expire simplement. Déclarez la permission dans le manifeste de debug (src/debug/AndroidManifest.xml) et accordez-la : adb shell pm grant <your.app> android.permission.ACCESS_LOCAL_NETWORK.

Cela ne sert qu'au développement local. L'ingestion hébergée est une adresse https publique et n'a besoin ni de l'un ni de l'autre.

Événements vérifiés

Un événement vérifié est un événement qui n'a pas pu être envoyé par quelqu'un ayant extrait la clé d'ingestion publique d'une app ou d'une page web. Ce que cela prouve, et ce que cela ne prouve pas, est expliqué dans Événements vérifiés.

Les événements d'une app Android sont vérifiés avec Key Attestation : le matériel sécurisé du téléphone prouve qu'ils viennent de votre propre app, signée avec votre certificat, sur un vrai appareil qui n'a été ni rooté ni déverrouillé. Lyrelog le vérifie sur ses propres serveurs ; aucun compte Google, aucun Play Integrity ni aucun projet Google Cloud n'entre en jeu.

C'est activé par défaut (attest dans Configuration) ; configurez-le dans le projet :

  1. Dans Project settings, sous Verified events from your Android apps, ajoutez votre package et l'empreinte SHA-256 de chaque certificat qui signe des builds envoyant des événements : la clé de signature d'app de Play (Play Console, Test and release, App integrity) et, pour les builds que vous signez vous-même, celle qu'affiche ./gradlew signingReport.
  2. Côté app, c'est tout. Pour le désactiver :
Lyrelog.start(this, Configuration(apiKey = "lyr_ing_...", attest = false))

Une fois par installation, le SDK crée une clé dans le matériel sécurisé du téléphone (StrongBox ou l'environnement d'exécution de confiance) et la fait attester par l'appareil ; à partir de là, ses lots portent un token et arrivent vérifiés (verified_by vaut key_attestation). Le token dure 24 heures et est renouvelé en arrière-plan avant son expiration. L'envoi ne l'attend jamais : tant que l'app n'a pas de token, et chaque fois que quelque chose échoue, les événements sont envoyés non vérifiés.

  • Les émulateurs ne sont jamais vérifiés, et le SDK n'essaie pas sur eux.
  • Tant que le projet n'a pas d'app Android configurée, ou quand la clé est refusée ou que l'appareil ne peut pas attester, le SDK désactive l'attestation pour ce lancement et le signale une fois dans logcat.
  • Un appareil que le serveur refuse (un téléphone rooté, un bootloader déverrouillé, un certificat que le projet ne liste pas) réessaie un jour plus tard.
  • Refuser le consentement supprime la clé attestée et son enregistrement (noBackupFilesDir/lyrelog/attest.json).

Tant que ce n'est pas configuré, les événements arrivent non vérifiés et comptent dans le quota journalier d'une adresse. Avant de faire accepter au projet uniquement les événements vérifiés pour android, vérifiez dans l'explorer que les événements de vos vrais utilisateurs arrivent vérifiés : les événements des anciennes versions, des émulateurs et des appareils refusés seraient retenus avec un 425.

Les événements que vos propres serveurs envoient avec une clé serveur, lyr_srv_..., sont vérifiés. Ne mettez jamais une clé serveur dans une app : tout ce qui est livré dans un APK peut être lu.

Pour vérifier, ouvrez l'explorer : un événement ouvert l'indique sous Context, sur sa ligne Sender : Verified, Key Attestation ou Not verified, public key.

Voir Événements vérifiés pour savoir qui vérifie quoi et pour le quota journalier.

Depuis Java

Chaque fonction de Lyrelog est statique depuis Java, avec des surcharges pour les arguments facultatifs :

Lyrelog.start(this, new Configuration("lyr_ing_..."));
Lyrelog.info("checkout_done");
Lyrelog.captureError(e, "store");

Configuration et les fonctions d'un logger ont aussi des surcharges, si bien que les derniers arguments peuvent être omis (logger.warning("sync_conflict"), logger.warning("sync_conflict", attrs)).

Configuration

OptionPar défautSignification
apiKeyobligatoireLa clé d'ingestion du projet
endpointhttps://ingest.lyrelog.comL'URL de base ; un chemin /v1/... collé est retiré. https uniquement, http seulement pour localhost et le 10.0.2.2 de l'émulateur
consentConsent.GRANTEDPENDING, GRANTED ou DENIED
minimumLevelLevel.DEBUGLes événements en dessous n'atteignent jamais le disque
flushIntervalMillis15 sLa fréquence d'exécution de l'uploader tant qu'une Activity est démarrée
maxBatchBytes512 KiBUn lot se ferme à la première limite atteinte (maintenu sous 4 MiB)
maxBatchEvents500Au plus 2 000
maxDiskBytes20 MBPlafond de la file sur disque, les plus anciens partent en premier
maxEventAgeMillis7 joursLes événements en file plus anciens sont abandonnés
sessionTimeoutMillis30 minLe temps d'inactivité qui ouvre une nouvelle session
environmentdétectéN'importe quel nom valide, ou null
platformandroidN'importe quel nom valide, ou null
appVersionle versionName de l'appEnvoyée comme resource.app_version
redactedKeysnull : DEFAULT_REDACTED_KEYSLes noms de clés à masquer ; votre liste remplace celle par défaut, une liste vide désactive le masquage
captureCrashestrueEnregistre les exceptions non interceptées, envoyées au lancement suivant
attachScreentrueMarque les événements avec l'écran en cours
automaticScreensfalseJournalise screen_viewed pour chaque Activity, nommée d'après sa classe
attesttrueProuve l'app avec Key Attestation pour que ses événements arrivent vérifiés, une fois que le projet liste son package et son certificat
mirrorToLogcatfalseAffiche aussi chaque événement dans logcat (tag Lyrelog)
storageDirectorynoBackupFilesDir/lyrelogL'emplacement de la file

Livraison et limites

Ne bloque jamaisJournaliser copie l'événement et rend la main ; un unique writer en arrière-plan l'écrit sur disque et n'attend jamais le réseau.
Résiste aux arrêts forcés et au hors-ligneUne file dans noBackupFilesDir/lyrelog, plafonnée à 20 MB et 7 jours. Ce qui a atteint le disque survit à un plantage, à un arrêt forcé ou à des jours hors ligne ; les événements encore en route vers le writer (quelques millisecondes) sont écrits par le handler de plantage, ou perdus si le processus est tué net. Le dossier n'est jamais inclus dans une sauvegarde, donc un téléphone restauré ne renvoie pas les événements d'un autre appareil.
Quand il envoieToutes les 15 s tant qu'une Activity est démarrée, et une fois quand l'app passe en arrière-plan. En arrière-plan, rien ne tourne sur minuteur : ce qui reste part au lancement suivant ou la prochaine fois que l'app revient au premier plan.
LotsJusqu'à 500 événements ou 512 KiB par requête, compressés en gzip. Un événement de plus de 1 MiB une fois encodé est abandonné et compté.
Nouvelles tentatives1 s, doublé jusqu'à 5 min, avec full jitter, en respectant Retry-After. Tout autre 4xx abandonne le lot, un 3xx (une redirection, jamais suivie) l'abandonne aussi, et une clé révoquée (401, 403) arrête les envois jusqu'au lancement suivant et conserve les événements. Un lot que le serveur continue de refuser alors que d'autres passent est remis en fin de file, puis abandonné.
Quota mensuelQuand une organisation Free a épuisé les événements de son mois, le serveur répond 429. Les événements restent dans la file sur disque et partent dès que le serveur les accepte de nouveau, dans les limites de 20 MB et de 7 jours. Le SDK journalise un avertissement dans logcat, et n'en journalise un autre qu'après qu'un lot a été accepté entre-temps.
Les pertes sont visiblesLes événements perdus à cause des plafonds deviennent un avertissement lyrelog_events_dropped (domaine lyrelog) avec leur nombre.
Ses propres problèmesUn endpoint incorrect, un 404, des lignes rejetées ou un endpoint qui ne répond pas sont signalés une fois par lancement dans logcat, tag Lyrelog, au niveau debug.
ContexteIdentifiant de l'app (le nom du package), version name, version code, android, la version d'Android, l'appareil (Google Pixel 9), locale, environnement, plateforme android, id de session (nouveau après 30 min d'inactivité) et id d'installation.
SecretsLes valeurs sous des clés dont le nom est ou se termine par authorization, cookie, password, token, secret, apikey et le reste de la liste commune deviennent "[redacted]", à toute profondeur, avant toute troncature.
LimitesLes chaînes longues sont coupées sur une limite de caractère, les attributs en trop comptés dans lyrelog_dropped_attrs, les payloads de plus de 64 KiB résumés en {"lyrelog_truncated": true, "bytes": N, "preview": "..."}.

Modifiez la liste avec redactedKeys : votre liste remplace celle par défaut, et une liste vide désactive le masquage. Pour la compléter :

Lyrelog.start(this, Configuration(
    apiKey = "lyr_ing_...",
    redactedKeys = Configuration.DEFAULT_REDACTED_KEYS + "pin",
))

Sécurité des données sur Play

Pour le formulaire de sécurité des données de la Play Console, déclarez ce que votre app envoie via Lyrelog :

  • App info and performance : Crash logs, Diagnostics (App functionality, et Analytics si vous les utilisez ainsi). Collectées, non partagées.
  • Device or other IDs : l'id d'installation, un UUID aléatoire qui n'est pas l'identifiant publicitaire, n'est pas sauvegardé et est supprimé en cas de refus. Non lié à la personne, sauf si vous appelez aussi setUser.
  • App activity > App interactions : si vous journalisez les écrans (screen_viewed) ou les appuis.
  • Tout ce que vos attrs ou votre payload contiennent d'autre (e-mails, achats...), dans sa propre catégorie.

Les données sont chiffrées en transit (https). Le serveur ajoute le pays de l'adresse d'envoi ; l'adresse elle-même n'est pas conservée.