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

SDKs

Dasselbe Modell in jeder Sprache. Wähle deine, oder sende Events über HTTP.

Die Lyrelog-SDKs teilen ein Modell (Level, Bereiche, Attribute, Nutzer) und verwenden dieselben Namen, wo die Sprache es zulässt, in deren eigener Schreibweise. Die Tabelle zeigt, wo sie sich unterscheiden.

Apps

SwiftAndroidReact NativeFlutter
StartenLyrelog.start(Configuration(...))Lyrelog.start(context, Configuration(...))Lyrelog.init({...})Lyrelog.start(LyrelogConfiguration(...))
LoggenLyrelog.info("checkout_done", attrs:)Lyrelog.info("checkout_done", attrs = ...)Lyrelog.info("checkout_done", { attrs })Lyrelog.info('checkout_done', attrs: {...})
Logger für einen BereichLyrelog.Logger(category: "checkout")Lyrelog.logger("checkout")Lyrelog.logger("checkout")Lyrelog.logger('checkout')
NutzerLyrelog.setUser("u_123")Lyrelog.setUser("u_123")Lyrelog.setUser("u_123")Lyrelog.setUser('u_123')
ScreenLyrelog.screen("Settings")Lyrelog.screen("Settings")trackNavigation(ref) oder Lyrelog.screen("Settings")LyrelogNavigatorObserver() oder Lyrelog.screen('Settings')
Requestssession.loggedData(for:)
Fehler erfassenLyrelog.captureError(error)Lyrelog.captureError(e)Lyrelog.captureException(error)Lyrelog.captureError(e, stackTrace: s)
Nicht abgefangene Fehler und AbstürzeMetricKit-Abstürze und -Hänger, automatischNicht abgefangene Exceptions, automatisch, beim nächsten Start gesendetFatale JavaScript- und Render-Fehler als Abstürze, Rejections und andere Fehler, dazu die nativen Abstürze; automatischDart-Fehler (FlutterError, PlatformDispatcher), dazu die nativen Abstürze; automatisch
Flushawait Lyrelog.flush()Lyrelog.flush() (nicht auf dem Main Thread)await Lyrelog.flush()await Lyrelog.flush()
Stoppenawait Lyrelog.stop()Lyrelog.stop()await Lyrelog.close()await Lyrelog.stop()

Web und Server

JavaScriptPythonGoJVM
StartenLyrelog.init({...})lyrelog.init(...)lyrelog.New(lyrelog.Config{...})Lyrelog.start(Configuration(...))
Loggenclient.info("checkout_done", { attrs })lyrelog.info("checkout_done", attrs=)client.Info("checkout_done", lyrelog.Attrs{})Lyrelog.info("checkout_done", attrs = ...)
Logger für einen Bereichclient.logger("checkout")lyrelog.logger("checkout")client.Logger("checkout")Lyrelog.logger("checkout")
Nutzerclient.setUser("u_123")lyrelog.set_user("u_123")client.SetUser("u_123")Lyrelog.setUser("u_123") oder Lyrelog.userScope(id) für einen Thread
Screenclient.screen("Settings")
Fehler erfassenclient.captureException(err)lyrelog.capture_exception(exc)client.CaptureError(err)Lyrelog.captureError(e)
Nicht abgefangene Fehler und Abstürzewindow und Node, automatischdein eigener sys.excepthookdein eigenes recovercaptureUncaught = true (standardmäßig aus)
Flushawait client.flush()lyrelog.flush()client.Flush(ctx)Lyrelog.flush()
Stoppenawait client.close()lyrelog.shutdown()client.Close()Lyrelog.close() (ein Shutdown-Hook erledigt das beim Beenden)
Standard-Logginglyrelog.LoggingHandler()lyrelog.NewSlogHandler(client, nil)LyrelogAppender für Logback

Die App-SDKs können außerdem jedes Event in das Log der Plattform kopieren, damit es in Xcode und logcat erscheint: mirrorToOSLog in Swift, mirrorToLogcat unter Android, mirrorToNativeLog in React Native und mirrorToConsole in Flutter.

Interne Vorschau

Noch ist keines der SDKs veröffentlicht, deshalb schlägt vorerst jeder Installationsbefehl auf diesen Seiten fehl: pnpm add, flutter pub add und uv add finden kein Paket, Gradle und Maven finden nichts auf Maven Central, und Swift Package Manager und go get erreichen die privaten Repositorys nicht. Jede Seite zeigt die Zeile so, wie sie nach der Veröffentlichung der SDKs aussehen wird.

Was jedes SDK für dich erledigt

Die SDKs für React Native und Flutter senden unter iOS über das Swift-SDK und unter Android über das Android-SDK, also gilt alles Folgende auch für sie, auf native Art umgesetzt. Das JVM-SDK nutzt die Engine des Android-SDKs, eingerichtet für einen Server.

  • Blockiert nie und wirft nie Fehler in deinem Code. Loggen kopiert das Event in eine Warteschlange und kehrt zurück; ein Worker im Hintergrund sendet es.
  • Bündelt bis zu 500 Events oder etwa 512 KiB pro Request, eine NDJSON-Zeile pro Event, mit gzip komprimiert, wo die Plattform es kann.
  • Sendet an https://ingest.lyrelog.com, sofern du keinen anderen endpoint setzt. Der Endpoint ist die Basis-URL: Wenn du die ganze Adresse .../v1/events:batch einfügst, entfernt das SDK den Pfad. Ein falscher Endpoint (ein 404 oder eine Weiterleitung) wird als Warnung im eigenen Log des SDKs gemeldet.
  • Wiederholt vorübergehende Fehler (408, 425, 429, 5xx, Netzwerkfehler) mit exponentiellem Backoff (1 s, verdoppelt bis 5 min) und Jitter und beachtet dabei Retry-After, auch wenn du flush aufrufst oder den Client schließt. Alle SDKs außer Python nutzen Full Jitter (eine zufällige Wartezeit zwischen 0 und der Obergrenze); Python nutzt Equal Jitter (zwischen der halben Obergrenze und der Obergrenze).
  • Verwirft einen abgelehnten Batch. Jeder andere 4xx-Status (400, 413, 415...) bedeutet, dass der Batch selbst fehlerhaft ist, also wird er verworfen statt erneut gesendet. Ein abgelehnter Schlüssel (401, 403) stoppt das Senden, bis die App oder der Prozess neu startet, und behält die Events. Weiterleitungen werden nie verfolgt: Eine 3xx-Antwort verwirft den Batch und loggt eine Warnung, denn sie bedeutet, dass der Endpoint falsch ist.
  • Behält Events bei einem 429. Wenn eine Free-Organisation die Events ihres Monats verbraucht hat oder ein Projekt sein Ratenlimit überschreitet, behält das SDK den Batch und versucht es nach Retry-After erneut (siehe HTTP API). Die App-SDKs (Swift, Android, React Native, Flutter) speichern sie über Starts hinweg auf der Festplatte. Das JVM-SDK speichert sie ebenfalls auf der Festplatte, in einem temporären Verzeichnis für den Prozess, sofern du ihm kein storageDirectory gibst. JavaScript, Python und Go halten sie im Speicher. So oder so gelten die Obergrenzen unten.
  • Begrenzt, was wartet: standardmäßig 10.000 Events und 16 MiB im Speicher in JavaScript, Python und Go; 20 MB auf der Festplatte und 7 Tage in den App-SDKs und der JVM. Die ältesten gehen zuerst.
  • Schwärzt Secrets, in jedem SDK auf dieselbe Weise. Der Wert eines Felds wird zu "[redacted]", wenn sein Name, in Kleinbuchstaben und ohne -, _, . oder Leerzeichen, authorization, cookie, password, passwd, secret, token, apikey, privatekey, credential(s), accesskey oder signature ist oder darauf endet. Also werden X-Api-Key, csrf_token und Set-Cookie geschwärzt, token_count und max_tokens dagegen nicht. Das passiert auf jeder Ebene von Attributen und Payload, bevor etwas gekürzt wird, sodass ein Secret nie in einem gekürzten String oder in der Vorschau einer Payload überlebt. Geprüft werden nur Namen: Ein Secret in einer Nachricht oder im Text eines Fehlers wird unverändert gesendet. Ändere die Liste mit redactedKeys (Swift, Android, Flutter, JVM), redactKeys (JavaScript, React Native), redact_keys (Python) oder RedactKeys (Go): Deine Liste ersetzt sie, und eine leere schaltet das Schwärzen ab. Um etwas hinzuzufügen, erweitere die exportierten Standardwerte: Configuration.defaultRedactedKeys in Swift, Configuration.DEFAULT_REDACTED_KEYS unter Android und auf der JVM, LyrelogConfiguration.defaultRedactedKeys in Flutter, DEFAULT_REDACT_KEYS in JavaScript, React Native und Python, DefaultRedactKeys() in Go. Die SDKs für JavaScript und Python nehmen außerdem einen Hook beforeSend / before_send, um jedes Event zu ändern oder zu verwerfen.
  • Flusht per Timer (15 s in den App-SDKs, 5 s im Web und auf Servern), wenn du flush aufrufst, wenn eine App in den Hintergrund geht, und beim Herunterfahren.
  • Passt Events an die Limits des Servers an, bevor sie in die Warteschlange kommen, sodass es nie eine Zeile sendet, die der Server wegen ihrer Form ablehnen würde.

Konfiguration

Dieselben Einstellungen gibt es in jedem SDK, unter den Namen der jeweiligen Sprache. Jede SDK-Seite hat die vollständige Liste.

Apps

EinstellungSwiftAndroidReact NativeFlutterStandard
SchlüsselapiKeyapiKeyapiKeyapiKeyPflicht: ein Ingest-Schlüssel
Endpointendpointendpointendpointendpointhttps://ingest.lyrelog.com
Umgebungenvironmentenvironmentenvironmentenvironmenterkannt, siehe Umgebungen
Plattformplatformplatformplatformplatformdas Betriebssystem, siehe Plattformen
Versionaus dem BundleappVersion, sonst aus dem Packageaus der Appaus der Appgesendet als resource.app_version
App-IDaus dem Bundleder Package-Namedie Bundle-ID oder der Package-Namedie Bundle-ID oder der Package-Namegesendet als resource.app_id
Niedrigstes behaltenes LevelminimumLevelminimumLevelminimumLevelminimumLeveldebug
SendeintervalluploadIntervalflushIntervalMillisflushIntervalMsflushInterval15 s
Größe der WarteschlangemaxDiskBytesmaxDiskBytesmaxDiskBytesmaxDiskBytes20 MB auf der Festplatte
Einwilligungconsentconsentconsentconsentgranted
Die App nachweisen (verifizierte Events)appAttestattestattestattestan

Web und Server

EinstellungJavaScriptPythonGoJVMStandard
SchlüsselapiKeyapi_keyAPIKeyapiKeyPflicht: ein Ingest-Schlüssel im Browser, ein Server-Schlüssel auf Servern
EndpointendpointendpointEndpointendpointhttps://ingest.lyrelog.com
UmgebungenvironmentenvironmentEnvironmentenvironmenterkannt, siehe Umgebungen
PlattformplatformplatformPlatformplatformerkannt, siehe Plattformen
VersionreleasereleaseReleaserelease, sonst das Manifest des JARsgesendet als resource.app_version
App-IDappIdapp_idAppIDappId, sonst das Manifest des JARsgesendet als resource.app_id
Niedrigstes behaltenes LevelminimumLevelminimum_levelMinimumLevelminimumLeveldebug
SendeintervallflushIntervalMsflush_intervalFlushIntervalflushIntervalMillis5 s
Größe der WarteschlangemaxQueuemax_queueMaxQueuemaxDiskBytes10.000 Events im Speicher; 20 MB auf der Festplatte auf der JVM
Einwilligungconsentgranted (Browser)

In den Spalten für JavaScript und Go heißt die Instanz client (log in den JavaScript-Beispielen); die anderen SDKs loggen über Lyrelog oder das Modul lyrelog. Auch die Zähler sind nach der jeweiligen Sprache benannt: JavaScript und Python zählen delivered, Go Sent.

Wenn Events nicht ankommen

  1. Prüfe die Umgebung. Das Dashboard öffnet mit production. Swift sendet development aus Xcode und dem Simulator, Android aus jedem Debug-Build, und Apps mit React Native und Flutter verhalten sich wie das native SDK darunter. JavaScript sendet development auf localhost und unter Node immer dann, wenn NODE_ENV nicht production ist, auch wenn es gar nicht gesetzt ist. Wähle die Umgebung oder All environments in der oberen Leiste.
  2. Lies die eigenen Meldungen des SDKs. Swift: das Unified Log, Subsystem com.lyrelog.sdk, auf Debug-Level (schalte in Console Include Debug Messages ein). Android: logcat, Tag Lyrelog, auf Debug-Level. React Native und Flutter: die des nativen SDKs, an denselben Stellen; React Native warnt in Debug-Builds außerdem einmal in Metro, wenn der Schlüssel oder das native Modul fehlt. JavaScript: Konsolenzeilen, die mit [lyrelog] beginnen. Python: der Logger lyrelog. Go: Config.ErrorLog; ohne ihn wird das erste Problem einmal auf stderr ausgegeben. JVM: Standard Error, Zeilen, die mit lyrelog: beginnen, oder Configuration.diagnostics. Sie melden, wenn der Schlüssel abgelehnt wurde, der Endpoint falsch ist oder ein Batch verworfen wurde.
  3. Lass den Prozess senden, bevor er endet. Kurze Skripte, Serverless-Funktionen und Prozesse, die exit aufrufen, müssen vorher flushen oder den Client schließen. Der Shutdown-Hook des JVM-SDKs erledigt das bei einem normalen Beenden, aber ein Serverless-Handler muss trotzdem flushen. Siehe die Seite des jeweiligen SDKs.
  4. Prüfe Einwilligung und Level. Mit der Einwilligung pending wird nichts gesendet. Events unter dem niedrigsten behaltenen Level kommen nie in die Warteschlange.
  5. Prüfe den Schlüssel. Nach einem 401 oder 403 wird nichts mehr gesendet, bis die App oder der Prozess neu startet. Ein leerer Schlüssel sendet nichts (in Go gibt New einen Fehler zurück; auf der JVM gibt start false zurück).

Was du nicht senden solltest

Nutze message für einen stabilen Event-Namen, nie für Text mit personenbezogenen Daten darin. Nutze deine eigenen IDs für Personen (setUser, user_id), keine E-Mail-Adressen. Halte Tokens, Passwörter und vollständige Request- oder Response-Bodys samt Headern aus Attributen und Payloads heraus. Das Schwärzen ist ein Sicherheitsnetz für die Schlüsselnamen, die es kennt, kein Filter, auf den du dich verlassen kannst.

In Entwicklung und Tests

  • Swift: Rufe Lyrelog.start in Tests nicht auf. Alles, was vor start geloggt wird, wird ignoriert.
  • Android: Auch hier: Rufe Lyrelog.start in Unit-Tests nicht auf. Debug-Builds senden development; damit der Emulator einen Endpoint auf deinem Rechner erreicht, braucht es ein paar Einstellungen, siehe In Entwicklung und Tests.
  • React Native: Rufe Lyrelog.init in Tests nicht auf: Aufrufe vor init werden ignoriert. Debug-Builds senden development.
  • Flutter: Rufe Lyrelog.start in Widget- und Unit-Tests nicht auf: Alles, was vor start geloggt wird, wird ignoriert. Auf Plattformen, die das Plugin nicht unterstützt (Web, Desktop), tut jeder Aufruf nichts. Siehe In Entwicklung und Tests.
  • JavaScript: Lass apiKey leer, dann warnt der Client einmal und sendet nichts, oder übergib consent: "denied".
  • Python: Ein leerer api_key ergibt einen Client, der Events annimmt und nichts sendet.
  • Go: New gibt ohne APIKey einen Fehler zurück, und ein nil-*Client tut nichts, sodass derselbe Code auch ohne Schlüssel läuft.
  • JVM: Lass den Schlüssel weg: start gibt false zurück, und jeder Aufruf tut nichts, einschließlich des Logback-Appenders.