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
Web und Server
Alles andere
Apps
| Swift | Android | React Native | Flutter | |
|---|---|---|---|---|
| Starten | Lyrelog.start(Configuration(...)) | Lyrelog.start(context, Configuration(...)) | Lyrelog.init({...}) | Lyrelog.start(LyrelogConfiguration(...)) |
| Loggen | Lyrelog.info("checkout_done", attrs:) | Lyrelog.info("checkout_done", attrs = ...) | Lyrelog.info("checkout_done", { attrs }) | Lyrelog.info('checkout_done', attrs: {...}) |
| Logger für einen Bereich | Lyrelog.Logger(category: "checkout") | Lyrelog.logger("checkout") | Lyrelog.logger("checkout") | Lyrelog.logger('checkout') |
| Nutzer | Lyrelog.setUser("u_123") | Lyrelog.setUser("u_123") | Lyrelog.setUser("u_123") | Lyrelog.setUser('u_123') |
| Screen | Lyrelog.screen("Settings") | Lyrelog.screen("Settings") | trackNavigation(ref) oder Lyrelog.screen("Settings") | LyrelogNavigatorObserver() oder Lyrelog.screen('Settings') |
| Requests | session.loggedData(for:) | |||
| Fehler erfassen | Lyrelog.captureError(error) | Lyrelog.captureError(e) | Lyrelog.captureException(error) | Lyrelog.captureError(e, stackTrace: s) |
| Nicht abgefangene Fehler und Abstürze | MetricKit-Abstürze und -Hänger, automatisch | Nicht abgefangene Exceptions, automatisch, beim nächsten Start gesendet | Fatale JavaScript- und Render-Fehler als Abstürze, Rejections und andere Fehler, dazu die nativen Abstürze; automatisch | Dart-Fehler (FlutterError, PlatformDispatcher), dazu die nativen Abstürze; automatisch |
| Flush | await Lyrelog.flush() | Lyrelog.flush() (nicht auf dem Main Thread) | await Lyrelog.flush() | await Lyrelog.flush() |
| Stoppen | await Lyrelog.stop() | Lyrelog.stop() | await Lyrelog.close() | await Lyrelog.stop() |
Web und Server
| JavaScript | Python | Go | JVM | |
|---|---|---|---|---|
| Starten | Lyrelog.init({...}) | lyrelog.init(...) | lyrelog.New(lyrelog.Config{...}) | Lyrelog.start(Configuration(...)) |
| Loggen | client.info("checkout_done", { attrs }) | lyrelog.info("checkout_done", attrs=) | client.Info("checkout_done", lyrelog.Attrs{}) | Lyrelog.info("checkout_done", attrs = ...) |
| Logger für einen Bereich | client.logger("checkout") | lyrelog.logger("checkout") | client.Logger("checkout") | Lyrelog.logger("checkout") |
| Nutzer | client.setUser("u_123") | lyrelog.set_user("u_123") | client.SetUser("u_123") | Lyrelog.setUser("u_123") oder Lyrelog.userScope(id) für einen Thread |
| Screen | client.screen("Settings") | |||
| Fehler erfassen | client.captureException(err) | lyrelog.capture_exception(exc) | client.CaptureError(err) | Lyrelog.captureError(e) |
| Nicht abgefangene Fehler und Abstürze | window und Node, automatisch | dein eigener sys.excepthook | dein eigenes recover | captureUncaught = true (standardmäßig aus) |
| Flush | await client.flush() | lyrelog.flush() | client.Flush(ctx) | Lyrelog.flush() |
| Stoppen | await client.close() | lyrelog.shutdown() | client.Close() | Lyrelog.close() (ein Shutdown-Hook erledigt das beim Beenden) |
| Standard-Logging | lyrelog.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 anderenendpointsetzt. Der Endpoint ist die Basis-URL: Wenn du die ganze Adresse.../v1/events:batcheinfügst, entfernt das SDK den Pfad. Ein falscher Endpoint (ein404oder 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 dabeiRetry-After, auch wenn duflushaufrufst 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 nachRetry-Aftererneut (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 keinstorageDirectorygibst. 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),accesskeyodersignatureist oder darauf endet. Also werdenX-Api-Key,csrf_tokenundSet-Cookiegeschwärzt,token_countundmax_tokensdagegen 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 mitredactedKeys(Swift, Android, Flutter, JVM),redactKeys(JavaScript, React Native),redact_keys(Python) oderRedactKeys(Go): Deine Liste ersetzt sie, und eine leere schaltet das Schwärzen ab. Um etwas hinzuzufügen, erweitere die exportierten Standardwerte:Configuration.defaultRedactedKeysin Swift,Configuration.DEFAULT_REDACTED_KEYSunter Android und auf der JVM,LyrelogConfiguration.defaultRedactedKeysin Flutter,DEFAULT_REDACT_KEYSin JavaScript, React Native und Python,DefaultRedactKeys()in Go. Die SDKs für JavaScript und Python nehmen außerdem einen HookbeforeSend/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
flushaufrufst, 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
| Einstellung | Swift | Android | React Native | Flutter | Standard |
|---|---|---|---|---|---|
| Schlüssel | apiKey | apiKey | apiKey | apiKey | Pflicht: ein Ingest-Schlüssel |
| Endpoint | endpoint | endpoint | endpoint | endpoint | https://ingest.lyrelog.com |
| Umgebung | environment | environment | environment | environment | erkannt, siehe Umgebungen |
| Plattform | platform | platform | platform | platform | das Betriebssystem, siehe Plattformen |
| Version | aus dem Bundle | appVersion, sonst aus dem Package | aus der App | aus der App | gesendet als resource.app_version |
| App-ID | aus dem Bundle | der Package-Name | die Bundle-ID oder der Package-Name | die Bundle-ID oder der Package-Name | gesendet als resource.app_id |
| Niedrigstes behaltenes Level | minimumLevel | minimumLevel | minimumLevel | minimumLevel | debug |
| Sendeintervall | uploadInterval | flushIntervalMillis | flushIntervalMs | flushInterval | 15 s |
| Größe der Warteschlange | maxDiskBytes | maxDiskBytes | maxDiskBytes | maxDiskBytes | 20 MB auf der Festplatte |
| Einwilligung | consent | consent | consent | consent | granted |
| Die App nachweisen (verifizierte Events) | appAttest | attest | attest | attest | an |
Web und Server
| Einstellung | JavaScript | Python | Go | JVM | Standard |
|---|---|---|---|---|---|
| Schlüssel | apiKey | api_key | APIKey | apiKey | Pflicht: ein Ingest-Schlüssel im Browser, ein Server-Schlüssel auf Servern |
| Endpoint | endpoint | endpoint | Endpoint | endpoint | https://ingest.lyrelog.com |
| Umgebung | environment | environment | Environment | environment | erkannt, siehe Umgebungen |
| Plattform | platform | platform | Platform | platform | erkannt, siehe Plattformen |
| Version | release | release | Release | release, sonst das Manifest des JARs | gesendet als resource.app_version |
| App-ID | appId | app_id | AppID | appId, sonst das Manifest des JARs | gesendet als resource.app_id |
| Niedrigstes behaltenes Level | minimumLevel | minimum_level | MinimumLevel | minimumLevel | debug |
| Sendeintervall | flushIntervalMs | flush_interval | FlushInterval | flushIntervalMillis | 5 s |
| Größe der Warteschlange | maxQueue | max_queue | MaxQueue | maxDiskBytes | 10.000 Events im Speicher; 20 MB auf der Festplatte auf der JVM |
| Einwilligung | consent | granted (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
- Prüfe die Umgebung. Das Dashboard öffnet mit
production. Swift sendetdevelopmentaus Xcode und dem Simulator, Android aus jedem Debug-Build, und Apps mit React Native und Flutter verhalten sich wie das native SDK darunter. JavaScript sendetdevelopmentauflocalhostund unter Node immer dann, wennNODE_ENVnichtproductionist, auch wenn es gar nicht gesetzt ist. Wähle die Umgebung oder All environments in der oberen Leiste. - 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, TagLyrelog, 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 Loggerlyrelog. Go:Config.ErrorLog; ohne ihn wird das erste Problem einmal auf stderr ausgegeben. JVM: Standard Error, Zeilen, die mitlyrelog:beginnen, oderConfiguration.diagnostics. Sie melden, wenn der Schlüssel abgelehnt wurde, der Endpoint falsch ist oder ein Batch verworfen wurde. - Lass den Prozess senden, bevor er endet. Kurze Skripte, Serverless-Funktionen und Prozesse,
die
exitaufrufen, 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. - Prüfe Einwilligung und Level. Mit der Einwilligung
pendingwird nichts gesendet. Events unter dem niedrigsten behaltenen Level kommen nie in die Warteschlange. - Prüfe den Schlüssel. Nach einem
401oder403wird nichts mehr gesendet, bis die App oder der Prozess neu startet. Ein leerer Schlüssel sendet nichts (in Go gibtNeweinen Fehler zurück; auf der JVM gibtstartfalsezurü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.startin Tests nicht auf. Alles, was vorstartgeloggt wird, wird ignoriert. - Android: Auch hier: Rufe
Lyrelog.startin Unit-Tests nicht auf. Debug-Builds sendendevelopment; damit der Emulator einen Endpoint auf deinem Rechner erreicht, braucht es ein paar Einstellungen, siehe In Entwicklung und Tests. - React Native: Rufe
Lyrelog.initin Tests nicht auf: Aufrufe vorinitwerden ignoriert. Debug-Builds sendendevelopment. - Flutter: Rufe
Lyrelog.startin Widget- und Unit-Tests nicht auf: Alles, was vorstartgeloggt wird, wird ignoriert. Auf Plattformen, die das Plugin nicht unterstützt (Web, Desktop), tut jeder Aufruf nichts. Siehe In Entwicklung und Tests. - JavaScript: Lass
apiKeyleer, dann warnt der Client einmal und sendet nichts, oder übergibconsent: "denied". - Python: Ein leerer
api_keyergibt einen Client, der Events annimmt und nichts sendet. - Go:
Newgibt ohneAPIKeyeinen Fehler zurück, und einnil-*Clienttut nichts, sodass derselbe Code auch ohne Schlüssel läuft. - JVM: Lass den Schlüssel weg:
startgibtfalsezurück, und jeder Aufruf tut nichts, einschließlich des Logback-Appenders.