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.
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-outLyrelog.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énement | Niveau | Ce qu'il contient |
|---|---|---|
app_crashed | critical | error_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).
Consentement
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 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 launchflush 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_NETWORKpour joindre une adresse privée comme10.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 :
- 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. - 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
| Option | Par défaut | Signification |
|---|---|---|
apiKey | obligatoire | La clé d'ingestion du projet |
endpoint | https://ingest.lyrelog.com | L'URL de base ; un chemin /v1/... collé est retiré. https uniquement, http seulement pour localhost et le 10.0.2.2 de l'émulateur |
consent | Consent.GRANTED | PENDING, GRANTED ou DENIED |
minimumLevel | Level.DEBUG | Les événements en dessous n'atteignent jamais le disque |
flushIntervalMillis | 15 s | La fréquence d'exécution de l'uploader tant qu'une Activity est démarrée |
maxBatchBytes | 512 KiB | Un lot se ferme à la première limite atteinte (maintenu sous 4 MiB) |
maxBatchEvents | 500 | Au plus 2 000 |
maxDiskBytes | 20 MB | Plafond de la file sur disque, les plus anciens partent en premier |
maxEventAgeMillis | 7 jours | Les événements en file plus anciens sont abandonnés |
sessionTimeoutMillis | 30 min | Le temps d'inactivité qui ouvre une nouvelle session |
environment | détecté | N'importe quel nom valide, ou null |
platform | android | N'importe quel nom valide, ou null |
appVersion | le versionName de l'app | Envoyée comme resource.app_version |
redactedKeys | null : DEFAULT_REDACTED_KEYS | Les noms de clés à masquer ; votre liste remplace celle par défaut, une liste vide désactive le masquage |
captureCrashes | true | Enregistre les exceptions non interceptées, envoyées au lancement suivant |
attachScreen | true | Marque les événements avec l'écran en cours |
automaticScreens | false | Journalise screen_viewed pour chaque Activity, nommée d'après sa classe |
attest | true | Prouve 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 |
mirrorToLogcat | false | Affiche aussi chaque événement dans logcat (tag Lyrelog) |
storageDirectory | noBackupFilesDir/lyrelog | L'emplacement de la file |
Livraison et limites
| Ne bloque jamais | Journaliser 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-ligne | Une 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 envoie | Toutes 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. |
| Lots | Jusqu'à 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 tentatives | 1 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 mensuel | Quand 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 visibles | Les événements perdus à cause des plafonds deviennent un avertissement lyrelog_events_dropped (domaine lyrelog) avec leur nombre. |
| Ses propres problèmes | Un 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. |
| Contexte | Identifiant 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. |
| Secrets | Les 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. |
| Limites | Les 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
attrsou votrepayloadcontiennent 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.