SDK
Le même modèle dans chaque langage. Choisissez le vôtre, ou envoyez vos événements en HTTP.
Les SDK Lyrelog partagent un même modèle (niveaux, domaines, attributs, utilisateurs) et emploient les mêmes noms quand le langage le permet, avec sa propre casse. Le tableau montre ce qui diffère.
Apps
Web et serveurs
Tout le reste
Apps
| Swift | Android | React Native | Flutter | |
|---|---|---|---|---|
| Démarrer | Lyrelog.start(Configuration(...)) | Lyrelog.start(context, Configuration(...)) | Lyrelog.init({...}) | Lyrelog.start(LyrelogConfiguration(...)) |
| Journaliser | Lyrelog.info("checkout_done", attrs:) | Lyrelog.info("checkout_done", attrs = ...) | Lyrelog.info("checkout_done", { attrs }) | Lyrelog.info('checkout_done', attrs: {...}) |
| Logger par domaine | Lyrelog.Logger(category: "checkout") | Lyrelog.logger("checkout") | Lyrelog.logger("checkout") | Lyrelog.logger('checkout') |
| Utilisateur | Lyrelog.setUser("u_123") | Lyrelog.setUser("u_123") | Lyrelog.setUser("u_123") | Lyrelog.setUser('u_123') |
| Écran | Lyrelog.screen("Settings") | Lyrelog.screen("Settings") | trackNavigation(ref), ou Lyrelog.screen("Settings") | LyrelogNavigatorObserver(), ou Lyrelog.screen('Settings') |
| Requêtes | session.loggedData(for:) | |||
| Capturer une erreur | Lyrelog.captureError(error) | Lyrelog.captureError(e) | Lyrelog.captureException(error) | Lyrelog.captureError(e, stackTrace: s) |
| Erreurs non interceptées et plantages | Plantages et blocages MetricKit, automatique | Exceptions non interceptées, automatique, envoyées au lancement suivant | Erreurs JavaScript fatales et erreurs de rendu comme plantages, rejets et autres erreurs, plus les plantages natifs ; automatique | Erreurs Dart (FlutterError, PlatformDispatcher), plus les plantages natifs ; automatique |
| Vider la file | await Lyrelog.flush() | Lyrelog.flush() (hors du thread principal) | await Lyrelog.flush() | await Lyrelog.flush() |
| Arrêter | await Lyrelog.stop() | Lyrelog.stop() | await Lyrelog.close() | await Lyrelog.stop() |
Web et serveurs
| JavaScript | Python | Go | JVM | |
|---|---|---|---|---|
| Démarrer | Lyrelog.init({...}) | lyrelog.init(...) | lyrelog.New(lyrelog.Config{...}) | Lyrelog.start(Configuration(...)) |
| Journaliser | client.info("checkout_done", { attrs }) | lyrelog.info("checkout_done", attrs=) | client.Info("checkout_done", lyrelog.Attrs{}) | Lyrelog.info("checkout_done", attrs = ...) |
| Logger par domaine | client.logger("checkout") | lyrelog.logger("checkout") | client.Logger("checkout") | Lyrelog.logger("checkout") |
| Utilisateur | client.setUser("u_123") | lyrelog.set_user("u_123") | client.SetUser("u_123") | Lyrelog.setUser("u_123"), ou Lyrelog.userScope(id) pour un thread |
| Écran | client.screen("Settings") | |||
| Capturer une erreur | client.captureException(err) | lyrelog.capture_exception(exc) | client.CaptureError(err) | Lyrelog.captureError(e) |
| Erreurs non interceptées et plantages | window et Node, automatique | votre propre sys.excepthook | votre propre recover | captureUncaught = true (désactivé par défaut) |
| Vider la file | await client.flush() | lyrelog.flush() | client.Flush(ctx) | Lyrelog.flush() |
| Arrêter | await client.close() | lyrelog.shutdown() | client.Close() | Lyrelog.close() (un shutdown hook s'en charge à la sortie) |
| Logging standard | lyrelog.LoggingHandler() | lyrelog.NewSlogHandler(client, nil) | LyrelogAppender pour Logback |
Les SDK d'app peuvent aussi copier chaque événement dans le log de la plateforme, pour le voir
dans Xcode et logcat : mirrorToOSLog en Swift, mirrorToLogcat sur Android, mirrorToNativeLog
en React Native et mirrorToConsole en Flutter.
Préversion interne
Aucun SDK n'est encore publié, donc toutes les commandes d'installation de ces pages échouent pour l'instant :
pnpm add, flutter pub add et uv add ne trouvent aucun paquet, Gradle et Maven ne trouvent rien sur
Maven Central, et Swift Package Manager et go get n'ont pas accès aux dépôts privés. Chaque page montre la ligne telle qu'elle sera une fois les SDK publiés.
Ce que chaque SDK fait pour vous
Les SDK React Native et Flutter envoient via le SDK Swift sur iOS et le SDK Android sur Android : tout ce qui suit vaut donc pour eux, à la manière native. Le SDK JVM fait tourner le moteur du SDK Android, configuré pour un serveur.
- Ne bloque jamais et ne lève jamais d'exception dans votre code. Journaliser copie l'événement dans une file et rend la main ; un worker en arrière-plan l'envoie.
- Regroupe jusqu'à 500 événements ou environ 512 KiB par requête, une ligne NDJSON par événement, compressée en gzip quand la plateforme le permet.
- Envoie à
https://ingest.lyrelog.comsauf si vous définissez un autreendpoint. L'endpoint est l'URL de base : si vous collez l'adresse complète.../v1/events:batch, le SDK retire le chemin. Un endpoint incorrect (un404, ou une redirection) est signalé par un avertissement dans le log du SDK. - Réessaie en cas d'échec temporaire (
408,425,429, 5xx, erreurs réseau) avec un backoff exponentiel (1 s, doublé jusqu'à 5 min) et du jitter, en respectantRetry-After, y compris quand vous appelezflushou fermez le client. Tous les SDK sauf Python utilisent le full jitter (une attente aléatoire entre 0 et le plafond) ; Python utilise l'equal jitter (entre la moitié du plafond et le plafond). - Abandonne un lot refusé. Tout autre 4xx (
400,413,415...) signifie que le lot lui-même est invalide : il est donc abandonné plutôt que renvoyé. Une clé refusée (401,403) arrête les envois jusqu'au redémarrage de l'app ou du processus, et conserve les événements. Les redirections ne sont jamais suivies : une réponse 3xx abandonne le lot et journalise un avertissement, car elle signifie que l'endpoint est incorrect. - Conserve les événements malgré un
429. Quand une organisation Free a épuisé les événements de son mois, ou qu'un projet dépasse sa limite de débit, le SDK garde le lot et réessaie aprèsRetry-After(voir HTTP API). Les SDK d'app (Swift, Android, React Native, Flutter) les gardent sur disque d'un lancement à l'autre. Le SDK JVM les garde aussi sur disque, dans un répertoire temporaire propre au processus, sauf si vous lui donnez unstorageDirectory. JavaScript, Python et Go les gardent en mémoire. Dans tous les cas, les plafonds ci-dessous s'appliquent. - Plafonne ce qui est en attente : 10 000 événements et 16 MiB en mémoire par défaut en JavaScript, Python et Go ; 20 MB sur disque et 7 jours dans les SDK d'app et sur la JVM. Les plus anciens partent en premier.
- Masque les secrets, de la même façon dans chaque SDK. La valeur d'un champ devient
"[redacted]"quand son nom, en minuscules et sans-,_,.ni espaces, est ou se termine parauthorization,cookie,password,passwd,secret,token,apikey,privatekey,credential(s),accesskeyousignature. AinsiX-Api-Key,csrf_tokenetSet-Cookiesont masqués, mais pastoken_countnimax_tokens. Cela s'applique à toute profondeur des attributs et du payload, avant toute troncature, si bien qu'un secret ne survit jamais dans une chaîne raccourcie ni dans l'aperçu d'un payload. Seuls les noms sont vérifiés : un secret placé dans un message ou dans le texte d'une erreur est envoyé tel quel. Modifiez la liste avecredactedKeys(Swift, Android, Flutter, JVM),redactKeys(JavaScript, React Native),redact_keys(Python) ouRedactKeys(Go) : votre liste remplace celle par défaut, et une liste vide désactive le masquage. Pour la compléter, étendez les valeurs par défaut exportées :Configuration.defaultRedactedKeysen Swift,Configuration.DEFAULT_REDACTED_KEYSsur Android et la JVM,LyrelogConfiguration.defaultRedactedKeysen Flutter,DEFAULT_REDACT_KEYSen JavaScript, React Native et Python,DefaultRedactKeys()en Go. Les SDK JavaScript et Python acceptent aussi un hookbeforeSend/before_sendpour modifier ou écarter n'importe quel événement. - Vide la file à intervalles réguliers (15 s dans les SDK d'app, 5 s sur le web et les serveurs),
quand vous appelez
flush, quand une app passe en arrière-plan, et à l'arrêt. - Adapte les événements aux limites du serveur avant de les mettre en file, pour ne jamais envoyer une ligne que le serveur rejetterait pour sa forme.
Configuration
Les mêmes réglages existent dans chaque SDK, sous les noms propres à chaque langage. Chaque page de SDK en donne la liste complète.
Apps
| Réglage | Swift | Android | React Native | Flutter | Par défaut |
|---|---|---|---|---|---|
| Clé | apiKey | apiKey | apiKey | apiKey | obligatoire : une clé d'ingestion |
| Endpoint | endpoint | endpoint | endpoint | endpoint | https://ingest.lyrelog.com |
| Environnement | environment | environment | environment | environment | détecté, voir Environnements |
| Plateforme | platform | platform | platform | platform | l'OS, voir Plateformes |
| Version | depuis le bundle | appVersion, sinon depuis le paquet | depuis l'app | depuis l'app | envoyée comme resource.app_version |
| Identifiant de l'app | depuis le bundle | le nom du paquet | le bundle id ou le nom du paquet | le bundle id ou le nom du paquet | envoyé comme resource.app_id |
| Niveau minimal conservé | minimumLevel | minimumLevel | minimumLevel | minimumLevel | debug |
| Intervalle d'envoi | uploadInterval | flushIntervalMillis | flushIntervalMs | flushInterval | 15 s |
| Taille de la file | maxDiskBytes | maxDiskBytes | maxDiskBytes | maxDiskBytes | 20 MB sur disque |
| Consentement | consent | consent | consent | consent | granted |
| Prouver l'app (événements vérifiés) | appAttest | attest | attest | attest | activé |
Web et serveurs
| Réglage | JavaScript | Python | Go | JVM | Par défaut |
|---|---|---|---|---|---|
| Clé | apiKey | api_key | APIKey | apiKey | obligatoire : une clé d'ingestion dans les navigateurs, une clé serveur sur les serveurs |
| Endpoint | endpoint | endpoint | Endpoint | endpoint | https://ingest.lyrelog.com |
| Environnement | environment | environment | Environment | environment | détecté, voir Environnements |
| Plateforme | platform | platform | Platform | platform | détectée, voir Plateformes |
| Version | release | release | Release | release, sinon le manifeste du jar | envoyée comme resource.app_version |
| Identifiant de l'app | appId | app_id | AppID | appId, sinon le manifeste du jar | envoyé comme resource.app_id |
| Niveau minimal conservé | minimumLevel | minimum_level | MinimumLevel | minimumLevel | debug |
| Intervalle d'envoi | flushIntervalMs | flush_interval | FlushInterval | flushIntervalMillis | 5 s |
| Taille de la file | maxQueue | max_queue | MaxQueue | maxDiskBytes | 10 000 événements en mémoire ; 20 MB sur disque sur la JVM |
| Consentement | consent | granted (navigateurs) |
Dans les colonnes JavaScript et Go, l'instance s'appelle client (log dans les exemples
JavaScript) ; les autres SDK journalisent via Lyrelog ou le module lyrelog. Les compteurs
suivent aussi les noms de chaque langage : JavaScript et Python comptent delivered, Go Sent.
Quand les événements n'apparaissent pas
- Vérifiez l'environnement. Le tableau de bord s'ouvre sur
production. Swift envoiedevelopmentdepuis Xcode et le simulateur, Android depuis tout build de debug, et les apps React Native et Flutter font comme le SDK natif sous-jacent. JavaScript envoiedevelopmentsurlocalhost, et sur Node dès queNODE_ENVne vaut pasproduction, y compris quand elle n'est pas définie. Choisissez l'environnement, ou All environments, dans la barre du haut. - Lisez les messages du SDK. Swift : le log unifié, sous-système
com.lyrelog.sdk, au niveau debug (dans Console, activez Include Debug Messages). Android : logcat, tagLyrelog, au niveau debug. React Native et Flutter : ceux du SDK natif, aux mêmes endroits ; React Native avertit aussi une fois dans Metro, dans les builds de développement, quand la clé ou le module natif manque. JavaScript : les lignes de la console qui commencent par[lyrelog]. Python : le loggerlyrelog. Go :Config.ErrorLog; sans lui, le premier problème est écrit une fois sur stderr. JVM : la sortie d'erreur standard, lignes commençant parlyrelog:, ouConfiguration.diagnostics. Ces messages indiquent quand la clé a été refusée, quand l'endpoint est incorrect ou quand un lot a été abandonné. - Laissez le processus envoyer avant de se terminer. Les scripts courts, les fonctions
serverless et les processus qui appellent
exitdoivent d'abord vider la file ou fermer le client. Le shutdown hook du SDK JVM s'en charge lors d'une sortie normale, mais un handler serverless doit quand même appeler flush. Voir la page de chaque SDK. - Vérifiez le consentement et le niveau. Avec le consentement
pending, rien n'est envoyé. Les événements sous le niveau minimal conservé ne sont jamais mis en file. - Vérifiez la clé. Après un
401ou un403, plus rien n'est envoyé jusqu'au redémarrage de l'app ou du processus. Une clé vide n'envoie rien (en Go,Newrenvoie une erreur ; sur la JVM,startrenvoiefalse).
Ce qu'il ne faut pas envoyer
Utilisez message pour un nom d'événement stable, jamais pour un texte contenant des données
personnelles. Utilisez vos propres identifiants pour les personnes (setUser, user_id), pas des
adresses e-mail. Laissez les tokens, les mots de passe et les corps complets de requête ou de
réponse, avec leurs headers, hors des attributs et des payloads. Le masquage est un filet de
sécurité pour les noms de clés qu'il connaît, pas un filtre sur lequel compter.
En développement et dans les tests
- Swift : n'appelez pas
Lyrelog.startdans les tests. Tout ce qui est journalisé avantstartest ignoré. - Android : de même, n'appelez pas
Lyrelog.startdans les tests unitaires. Les builds de debug envoientdevelopment; joindre depuis l'émulateur un endpoint sur votre ordinateur demande quelques réglages, voir En développement et dans les tests. - React Native : n'appelez pas
Lyrelog.initdans les tests : les appels faits avantinitsont ignorés. Les builds de debug envoientdevelopment. - Flutter : n'appelez pas
Lyrelog.startdans les tests de widgets et les tests unitaires : tout ce qui est journalisé avantstartest ignoré. Sur les plateformes que le plugin ne prend pas en charge (web, desktop), les appels sont sans effet. Voir En développement et dans les tests. - JavaScript : laissez
apiKeyvide et le client avertit une fois et n'envoie rien, ou passezconsent: "denied". - Python : une
api_keyvide donne un client qui accepte les événements et n'envoie rien. - Go :
Newrenvoie une erreur sansAPIKey, et un*Clientnilne fait rien, donc le même code fonctionne sans client. - JVM : omettez la clé :
startrenvoiefalseet tous les appels sont sans effet, l'appender Logback compris.