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

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

SwiftAndroidReact NativeFlutter
DémarrerLyrelog.start(Configuration(...))Lyrelog.start(context, Configuration(...))Lyrelog.init({...})Lyrelog.start(LyrelogConfiguration(...))
JournaliserLyrelog.info("checkout_done", attrs:)Lyrelog.info("checkout_done", attrs = ...)Lyrelog.info("checkout_done", { attrs })Lyrelog.info('checkout_done', attrs: {...})
Logger par domaineLyrelog.Logger(category: "checkout")Lyrelog.logger("checkout")Lyrelog.logger("checkout")Lyrelog.logger('checkout')
UtilisateurLyrelog.setUser("u_123")Lyrelog.setUser("u_123")Lyrelog.setUser("u_123")Lyrelog.setUser('u_123')
ÉcranLyrelog.screen("Settings")Lyrelog.screen("Settings")trackNavigation(ref), ou Lyrelog.screen("Settings")LyrelogNavigatorObserver(), ou Lyrelog.screen('Settings')
Requêtessession.loggedData(for:)
Capturer une erreurLyrelog.captureError(error)Lyrelog.captureError(e)Lyrelog.captureException(error)Lyrelog.captureError(e, stackTrace: s)
Erreurs non interceptées et plantagesPlantages et blocages MetricKit, automatiqueExceptions non interceptées, automatique, envoyées au lancement suivantErreurs JavaScript fatales et erreurs de rendu comme plantages, rejets et autres erreurs, plus les plantages natifs ; automatiqueErreurs Dart (FlutterError, PlatformDispatcher), plus les plantages natifs ; automatique
Vider la fileawait Lyrelog.flush()Lyrelog.flush() (hors du thread principal)await Lyrelog.flush()await Lyrelog.flush()
Arrêterawait Lyrelog.stop()Lyrelog.stop()await Lyrelog.close()await Lyrelog.stop()

Web et serveurs

JavaScriptPythonGoJVM
DémarrerLyrelog.init({...})lyrelog.init(...)lyrelog.New(lyrelog.Config{...})Lyrelog.start(Configuration(...))
Journaliserclient.info("checkout_done", { attrs })lyrelog.info("checkout_done", attrs=)client.Info("checkout_done", lyrelog.Attrs{})Lyrelog.info("checkout_done", attrs = ...)
Logger par domaineclient.logger("checkout")lyrelog.logger("checkout")client.Logger("checkout")Lyrelog.logger("checkout")
Utilisateurclient.setUser("u_123")lyrelog.set_user("u_123")client.SetUser("u_123")Lyrelog.setUser("u_123"), ou Lyrelog.userScope(id) pour un thread
Écranclient.screen("Settings")
Capturer une erreurclient.captureException(err)lyrelog.capture_exception(exc)client.CaptureError(err)Lyrelog.captureError(e)
Erreurs non interceptées et plantageswindow et Node, automatiquevotre propre sys.excepthookvotre propre recovercaptureUncaught = true (désactivé par défaut)
Vider la fileawait client.flush()lyrelog.flush()client.Flush(ctx)Lyrelog.flush()
Arrêterawait client.close()lyrelog.shutdown()client.Close()Lyrelog.close() (un shutdown hook s'en charge à la sortie)
Logging standardlyrelog.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.com sauf si vous définissez un autre endpoint. 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 (un 404, 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 respectant Retry-After, y compris quand vous appelez flush ou 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ès Retry-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 un storageDirectory. 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 par authorization, cookie, password, passwd, secret, token, apikey, privatekey, credential(s), accesskey ou signature. Ainsi X-Api-Key, csrf_token et Set-Cookie sont masqués, mais pas token_count ni max_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 avec redactedKeys (Swift, Android, Flutter, JVM), redactKeys (JavaScript, React Native), redact_keys (Python) ou RedactKeys (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.defaultRedactedKeys en Swift, Configuration.DEFAULT_REDACTED_KEYS sur Android et la JVM, LyrelogConfiguration.defaultRedactedKeys en Flutter, DEFAULT_REDACT_KEYS en JavaScript, React Native et Python, DefaultRedactKeys() en Go. Les SDK JavaScript et Python acceptent aussi un hook beforeSend / before_send pour 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églageSwiftAndroidReact NativeFlutterPar défaut
CléapiKeyapiKeyapiKeyapiKeyobligatoire : une clé d'ingestion
Endpointendpointendpointendpointendpointhttps://ingest.lyrelog.com
Environnementenvironmentenvironmentenvironmentenvironmentdétecté, voir Environnements
Plateformeplatformplatformplatformplatforml'OS, voir Plateformes
Versiondepuis le bundleappVersion, sinon depuis le paquetdepuis l'appdepuis l'appenvoyée comme resource.app_version
Identifiant de l'appdepuis le bundlele nom du paquetle bundle id ou le nom du paquetle bundle id ou le nom du paquetenvoyé comme resource.app_id
Niveau minimal conservéminimumLevelminimumLevelminimumLevelminimumLeveldebug
Intervalle d'envoiuploadIntervalflushIntervalMillisflushIntervalMsflushInterval15 s
Taille de la filemaxDiskBytesmaxDiskBytesmaxDiskBytesmaxDiskBytes20 MB sur disque
Consentementconsentconsentconsentconsentgranted
Prouver l'app (événements vérifiés)appAttestattestattestattestactivé

Web et serveurs

RéglageJavaScriptPythonGoJVMPar défaut
CléapiKeyapi_keyAPIKeyapiKeyobligatoire : une clé d'ingestion dans les navigateurs, une clé serveur sur les serveurs
EndpointendpointendpointEndpointendpointhttps://ingest.lyrelog.com
EnvironnementenvironmentenvironmentEnvironmentenvironmentdétecté, voir Environnements
PlateformeplatformplatformPlatformplatformdétectée, voir Plateformes
VersionreleasereleaseReleaserelease, sinon le manifeste du jarenvoyée comme resource.app_version
Identifiant de l'appappIdapp_idAppIDappId, sinon le manifeste du jarenvoyé comme resource.app_id
Niveau minimal conservéminimumLevelminimum_levelMinimumLevelminimumLeveldebug
Intervalle d'envoiflushIntervalMsflush_intervalFlushIntervalflushIntervalMillis5 s
Taille de la filemaxQueuemax_queueMaxQueuemaxDiskBytes10 000 événements en mémoire ; 20 MB sur disque sur la JVM
Consentementconsentgranted (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

  1. Vérifiez l'environnement. Le tableau de bord s'ouvre sur production. Swift envoie development depuis 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 envoie development sur localhost, et sur Node dès que NODE_ENV ne vaut pas production, y compris quand elle n'est pas définie. Choisissez l'environnement, ou All environments, dans la barre du haut.
  2. 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, tag Lyrelog, 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 logger lyrelog. Go : Config.ErrorLog ; sans lui, le premier problème est écrit une fois sur stderr. JVM : la sortie d'erreur standard, lignes commençant par lyrelog: , ou Configuration.diagnostics. Ces messages indiquent quand la clé a été refusée, quand l'endpoint est incorrect ou quand un lot a été abandonné.
  3. Laissez le processus envoyer avant de se terminer. Les scripts courts, les fonctions serverless et les processus qui appellent exit doivent 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.
  4. 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.
  5. Vérifiez la clé. Après un 401 ou un 403, plus rien n'est envoyé jusqu'au redémarrage de l'app ou du processus. Une clé vide n'envoie rien (en Go, New renvoie une erreur ; sur la JVM, start renvoie false).

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.start dans les tests. Tout ce qui est journalisé avant start est ignoré.
  • Android : de même, n'appelez pas Lyrelog.start dans les tests unitaires. Les builds de debug envoient development ; 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.init dans les tests : les appels faits avant init sont ignorés. Les builds de debug envoient development.
  • Flutter : n'appelez pas Lyrelog.start dans les tests de widgets et les tests unitaires : tout ce qui est journalisé avant start est 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 apiKey vide et le client avertit une fois et n'envoie rien, ou passez consent: "denied".
  • Python : une api_key vide donne un client qui accepte les événements et n'envoie rien.
  • Go : New renvoie une erreur sans APIKey, et un *Client nil ne fait rien, donc le même code fonctionne sans client.
  • JVM : omettez la clé : start renvoie false et tous les appels sont sans effet, l'appender Logback compris.