SDKs
The same model in every language. Pick yours, or send events over HTTP.
The Lyrelog SDKs share one model (levels, areas, attributes, users) and use the same names where the language allows, in its own casing. The table shows where they differ.
Apps
Web and servers
Anything else
Apps
| Swift | Android | React Native | Flutter | |
|---|---|---|---|---|
| Start | Lyrelog.start(Configuration(...)) | Lyrelog.start(context, Configuration(...)) | Lyrelog.init({...}) | Lyrelog.start(LyrelogConfiguration(...)) |
| Log | Lyrelog.info("checkout_done", attrs:) | Lyrelog.info("checkout_done", attrs = ...) | Lyrelog.info("checkout_done", { attrs }) | Lyrelog.info('checkout_done', attrs: {...}) |
| Area logger | Lyrelog.Logger(category: "checkout") | Lyrelog.logger("checkout") | Lyrelog.logger("checkout") | Lyrelog.logger('checkout') |
| User | 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), or Lyrelog.screen("Settings") | LyrelogNavigatorObserver(), or Lyrelog.screen('Settings') |
| Requests | session.loggedData(for:) | |||
| Capture an error | Lyrelog.captureError(error) | Lyrelog.captureError(e) | Lyrelog.captureException(error) | Lyrelog.captureError(e, stackTrace: s) |
| Uncaught errors and crashes | MetricKit crashes and hangs, automatic | Uncaught exceptions, automatic, sent on the next launch | Fatal JavaScript and render errors as crashes, rejections and other errors, plus the native crashes; automatic | Dart errors (FlutterError, PlatformDispatcher), plus the native crashes; automatic |
| Flush | await Lyrelog.flush() | Lyrelog.flush() (off the main thread) | await Lyrelog.flush() | await Lyrelog.flush() |
| Stop | await Lyrelog.stop() | Lyrelog.stop() | await Lyrelog.close() | await Lyrelog.stop() |
Web and servers
| JavaScript | Python | Go | JVM | |
|---|---|---|---|---|
| Start | Lyrelog.init({...}) | lyrelog.init(...) | lyrelog.New(lyrelog.Config{...}) | Lyrelog.start(Configuration(...)) |
| Log | client.info("checkout_done", { attrs }) | lyrelog.info("checkout_done", attrs=) | client.Info("checkout_done", lyrelog.Attrs{}) | Lyrelog.info("checkout_done", attrs = ...) |
| Area logger | client.logger("checkout") | lyrelog.logger("checkout") | client.Logger("checkout") | Lyrelog.logger("checkout") |
| User | client.setUser("u_123") | lyrelog.set_user("u_123") | client.SetUser("u_123") | Lyrelog.setUser("u_123"), or Lyrelog.userScope(id) for a thread |
| Screen | client.screen("Settings") | |||
| Capture an error | client.captureException(err) | lyrelog.capture_exception(exc) | client.CaptureError(err) | Lyrelog.captureError(e) |
| Uncaught errors and crashes | window and Node, automatic | your own sys.excepthook | your own recover | captureUncaught = true (off by default) |
| Flush | await client.flush() | lyrelog.flush() | client.Flush(ctx) | Lyrelog.flush() |
| Stop | await client.close() | lyrelog.shutdown() | client.Close() | Lyrelog.close() (a shutdown hook does it on exit) |
| Standard logging | lyrelog.LoggingHandler() | lyrelog.NewSlogHandler(client, nil) | LyrelogAppender for Logback |
The app SDKs can also copy every event to the platform's own log, so it shows in Xcode and
logcat: mirrorToOSLog in Swift, mirrorToLogcat on Android, mirrorToNativeLog in React
Native and mirrorToConsole in Flutter.
Internal preview
None of the SDKs is published yet, so every install command on these pages fails for now:
pnpm add, flutter pub add and uv add find no package, Gradle and Maven find nothing on
Maven Central, and Swift Package Manager and go get can't reach the private repositories. Each page shows the line as it will be once the SDKs are published.
What every SDK does for you
The React Native and Flutter SDKs send through the Swift SDK on iOS and the Android SDK on Android, so everything below is theirs, done the native way. The JVM SDK runs the Android SDK's engine, set up for a server.
- Never blocks or throws in your code. Logging copies the event into a queue and returns; a background worker sends it.
- Batches up to 500 events or about 512 KiB per request, one NDJSON line per event, gzipped where the platform can.
- Sends to
https://ingest.lyrelog.comunless you set anotherendpoint. The endpoint is the base URL: if you paste the whole.../v1/events:batchaddress, the SDK strips the path. A wrong endpoint (a404, or a redirect) is reported as a warning in the SDK's own log. - Retries temporary failures (
408,425,429, 5xx, network errors) with exponential backoff (1 s doubling up to 5 min) and jitter, honoringRetry-After, also when you callflushor close the client. Every SDK but Python uses full jitter (a random wait between 0 and the ceiling); Python uses equal jitter (between half the ceiling and the ceiling). - Drops a refused batch. Any other 4xx (
400,413,415...) means the batch itself is wrong, so it is dropped rather than resent. A refused key (401,403) stops sending until the app or process restarts, and keeps the events. Redirects are never followed: a 3xx answer drops the batch and logs a warning, since it means the endpoint is wrong. - Keeps events through a
429. When a Free organization has used its month's events, or a project goes over its rate limit, the SDK keeps the batch and tries again afterRetry-After(see HTTP API). The app SDKs (Swift, Android, React Native, Flutter) keep them on disk across launches. The JVM SDK keeps them on disk too, in a temporary directory for the process unless you give it astorageDirectory. JavaScript, Python and Go keep them in memory. Either way the caps below still apply. - Caps what waits: 10,000 events and 16 MiB in memory by default in JavaScript, Python and Go; 20 MB on disk and 7 days in the app SDKs and the JVM. The oldest go first.
- Redacts secrets, the same way in every SDK. A field's value becomes
"[redacted]"when its name, lowercased and without-,_,.or spaces, is or ends withauthorization,cookie,password,passwd,secret,token,apikey,privatekey,credential(s),accesskeyorsignature. SoX-Api-Key,csrf_tokenandSet-Cookieare redacted, andtoken_countandmax_tokensaren't. It happens at any depth of attributes and payload, before anything is cut, so a secret never survives in a shortened string or a payload's preview. Only names are checked: a secret inside a message or an error's text is sent as is. Change the list withredactedKeys(Swift, Android, Flutter, JVM),redactKeys(JavaScript, React Native),redact_keys(Python) orRedactKeys(Go): your list replaces it, and an empty one turns redaction off. To add to it, extend the exported defaults:Configuration.defaultRedactedKeysin Swift,Configuration.DEFAULT_REDACTED_KEYSon Android and the JVM,LyrelogConfiguration.defaultRedactedKeysin Flutter,DEFAULT_REDACT_KEYSin JavaScript, React Native and Python,DefaultRedactKeys()in Go. The JavaScript and Python SDKs also take abeforeSend/before_sendhook to change or drop any event. - Flushes on a timer (15 s in the app SDKs, 5 s on the web and servers), when you call
flush, when an app goes to the background, and on shutdown. - Fits events to the server's limits before queueing them, so it never sends a line the server would reject for its shape.
Configuration
The same settings exist in every SDK, under each language's names. Each SDK page has the full list.
Apps
| Setting | Swift | Android | React Native | Flutter | Default |
|---|---|---|---|---|---|
| Key | apiKey | apiKey | apiKey | apiKey | required: an ingest key |
| Endpoint | endpoint | endpoint | endpoint | endpoint | https://ingest.lyrelog.com |
| Environment | environment | environment | environment | environment | detected, see Environments |
| Platform | platform | platform | platform | platform | the OS, see Platforms |
| Version | from the bundle | appVersion, else from the package | from the app | from the app | sent as resource.app_version |
| App id | from the bundle | the package name | the bundle id or package name | the bundle id or package name | sent as resource.app_id |
| Lowest level kept | minimumLevel | minimumLevel | minimumLevel | minimumLevel | debug |
| Send interval | uploadInterval | flushIntervalMillis | flushIntervalMs | flushInterval | 15 s |
| Queue size | maxDiskBytes | maxDiskBytes | maxDiskBytes | maxDiskBytes | 20 MB on disk |
| Consent | consent | consent | consent | consent | granted |
| Prove the app (verified events) | appAttest | attest | attest | attest | on |
Web and servers
| Setting | JavaScript | Python | Go | JVM | Default |
|---|---|---|---|---|---|
| Key | apiKey | api_key | APIKey | apiKey | required: an ingest key in browsers, a server key on servers |
| Endpoint | endpoint | endpoint | Endpoint | endpoint | https://ingest.lyrelog.com |
| Environment | environment | environment | Environment | environment | detected, see Environments |
| Platform | platform | platform | Platform | platform | detected, see Platforms |
| Version | release | release | Release | release, else the jar's manifest | sent as resource.app_version |
| App id | appId | app_id | AppID | appId, else the jar's manifest | sent as resource.app_id |
| Lowest level kept | minimumLevel | minimum_level | MinimumLevel | minimumLevel | debug |
| Send interval | flushIntervalMs | flush_interval | FlushInterval | flushIntervalMillis | 5 s |
| Queue size | maxQueue | max_queue | MaxQueue | maxDiskBytes | 10,000 events in memory; 20 MB on disk on the JVM |
| Consent | consent | granted (browsers) |
In the JavaScript and Go columns the instance is called client (log in the JavaScript
examples); the other SDKs log through Lyrelog or the lyrelog module. The counters are named
after each language too: JavaScript and Python count delivered, Go Sent.
When events don't show up
- Check the environment. The dashboard opens on
production. Swift sendsdevelopmentfrom Xcode and the simulator, Android from every debug build, and React Native and Flutter apps do as the native SDK under them does. JavaScript sendsdevelopmentonlocalhost, and on Node wheneverNODE_ENVisn'tproduction, including when it's unset. Pick the environment, or All environments, in the top bar. - Read the SDK's own messages. Swift: the unified log, subsystem
com.lyrelog.sdk, at debug level (in Console, turn on Include Debug Messages). Android: logcat, tagLyrelog, at debug level. React Native and Flutter: the native SDK's, in the same places; React Native also warns once in Metro, in development builds, when the key or the native module is missing. JavaScript: console lines starting with[lyrelog]. Python: thelyreloglogger. Go:Config.ErrorLog; without it, the first problem is printed to stderr once. JVM: standard error, lines starting withlyrelog:, orConfiguration.diagnostics. They say when the key was refused, the endpoint is wrong or a batch was dropped. - Let the process send before it ends. Short scripts, serverless functions and processes
that call
exitmust flush or close the client first. The JVM SDK's shutdown hook does it on a normal exit, but a serverless handler still has to flush. See each SDK's page. - Check consent and level. With consent
pendingnothing is sent. Events below the lowest level kept are never queued. - Check the key. After a
401or403, nothing more is sent until the app or process restarts. An empty key sends nothing (in Go,Newreturns an error; on the JVM,startreturnsfalse).
What not to send
Use message for a stable event name, never for text with personal data in it. Use your own ids
for people (setUser, user_id), not email addresses. Keep tokens, passwords and full request or
response bodies with their headers out of attributes and payloads. Redaction is a safety net for
the key names it knows, not a filter you can rely on.
In development and tests
- Swift: don't call
Lyrelog.startin tests. Anything logged beforestartis ignored. - Android: the same, don't call
Lyrelog.startin unit tests. Debug builds senddevelopment; reaching an endpoint on your computer from the emulator needs a few settings, see In development and tests. - React Native: don't call
Lyrelog.initin tests: calls beforeinitare ignored. Debug builds senddevelopment. - Flutter: don't call
Lyrelog.startin widget and unit tests: anything logged beforestartis ignored. On platforms the plugin doesn't support (web, desktop) every call does nothing. See In development and tests. - JavaScript: leave
apiKeyempty and the client warns once and sends nothing, or passconsent: "denied". - Python: an empty
api_keygives a client that accepts events and sends nothing. - Go:
Newreturns an error without anAPIKey, and anil*Clientdoes nothing, so the same code runs without one. - JVM: leave the key out:
startreturnsfalseand every call does nothing, the Logback appender included.