Early accessBy invitation, and the SDKs aren't published yet.Ask for an invitation
Skip to Content
Docs

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

SwiftAndroidReact NativeFlutter
StartLyrelog.start(Configuration(...))Lyrelog.start(context, Configuration(...))Lyrelog.init({...})Lyrelog.start(LyrelogConfiguration(...))
LogLyrelog.info("checkout_done", attrs:)Lyrelog.info("checkout_done", attrs = ...)Lyrelog.info("checkout_done", { attrs })Lyrelog.info('checkout_done', attrs: {...})
Area loggerLyrelog.Logger(category: "checkout")Lyrelog.logger("checkout")Lyrelog.logger("checkout")Lyrelog.logger('checkout')
UserLyrelog.setUser("u_123")Lyrelog.setUser("u_123")Lyrelog.setUser("u_123")Lyrelog.setUser('u_123')
ScreenLyrelog.screen("Settings")Lyrelog.screen("Settings")trackNavigation(ref), or Lyrelog.screen("Settings")LyrelogNavigatorObserver(), or Lyrelog.screen('Settings')
Requestssession.loggedData(for:)
Capture an errorLyrelog.captureError(error)Lyrelog.captureError(e)Lyrelog.captureException(error)Lyrelog.captureError(e, stackTrace: s)
Uncaught errors and crashesMetricKit crashes and hangs, automaticUncaught exceptions, automatic, sent on the next launchFatal JavaScript and render errors as crashes, rejections and other errors, plus the native crashes; automaticDart errors (FlutterError, PlatformDispatcher), plus the native crashes; automatic
Flushawait Lyrelog.flush()Lyrelog.flush() (off the main thread)await Lyrelog.flush()await Lyrelog.flush()
Stopawait Lyrelog.stop()Lyrelog.stop()await Lyrelog.close()await Lyrelog.stop()

Web and servers

JavaScriptPythonGoJVM
StartLyrelog.init({...})lyrelog.init(...)lyrelog.New(lyrelog.Config{...})Lyrelog.start(Configuration(...))
Logclient.info("checkout_done", { attrs })lyrelog.info("checkout_done", attrs=)client.Info("checkout_done", lyrelog.Attrs{})Lyrelog.info("checkout_done", attrs = ...)
Area loggerclient.logger("checkout")lyrelog.logger("checkout")client.Logger("checkout")Lyrelog.logger("checkout")
Userclient.setUser("u_123")lyrelog.set_user("u_123")client.SetUser("u_123")Lyrelog.setUser("u_123"), or Lyrelog.userScope(id) for a thread
Screenclient.screen("Settings")
Capture an errorclient.captureException(err)lyrelog.capture_exception(exc)client.CaptureError(err)Lyrelog.captureError(e)
Uncaught errors and crasheswindow and Node, automaticyour own sys.excepthookyour own recovercaptureUncaught = true (off by default)
Flushawait client.flush()lyrelog.flush()client.Flush(ctx)Lyrelog.flush()
Stopawait client.close()lyrelog.shutdown()client.Close()Lyrelog.close() (a shutdown hook does it on exit)
Standard logginglyrelog.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.com unless you set another endpoint. The endpoint is the base URL: if you paste the whole .../v1/events:batch address, the SDK strips the path. A wrong endpoint (a 404, 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, honoring Retry-After, also when you call flush or 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 after Retry-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 a storageDirectory. 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 with authorization, cookie, password, passwd, secret, token, apikey, privatekey, credential(s), accesskey or signature. So X-Api-Key, csrf_token and Set-Cookie are redacted, and token_count and max_tokens aren'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 with redactedKeys (Swift, Android, Flutter, JVM), redactKeys (JavaScript, React Native), redact_keys (Python) or RedactKeys (Go): your list replaces it, and an empty one turns redaction off. To add to it, extend the exported defaults: Configuration.defaultRedactedKeys in Swift, Configuration.DEFAULT_REDACTED_KEYS on Android and the JVM, LyrelogConfiguration.defaultRedactedKeys in Flutter, DEFAULT_REDACT_KEYS in JavaScript, React Native and Python, DefaultRedactKeys() in Go. The JavaScript and Python SDKs also take a beforeSend / before_send hook 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

SettingSwiftAndroidReact NativeFlutterDefault
KeyapiKeyapiKeyapiKeyapiKeyrequired: an ingest key
Endpointendpointendpointendpointendpointhttps://ingest.lyrelog.com
Environmentenvironmentenvironmentenvironmentenvironmentdetected, see Environments
Platformplatformplatformplatformplatformthe OS, see Platforms
Versionfrom the bundleappVersion, else from the packagefrom the appfrom the appsent as resource.app_version
App idfrom the bundlethe package namethe bundle id or package namethe bundle id or package namesent as resource.app_id
Lowest level keptminimumLevelminimumLevelminimumLevelminimumLeveldebug
Send intervaluploadIntervalflushIntervalMillisflushIntervalMsflushInterval15 s
Queue sizemaxDiskBytesmaxDiskBytesmaxDiskBytesmaxDiskBytes20 MB on disk
Consentconsentconsentconsentconsentgranted
Prove the app (verified events)appAttestattestattestatteston

Web and servers

SettingJavaScriptPythonGoJVMDefault
KeyapiKeyapi_keyAPIKeyapiKeyrequired: an ingest key in browsers, a server key on servers
EndpointendpointendpointEndpointendpointhttps://ingest.lyrelog.com
EnvironmentenvironmentenvironmentEnvironmentenvironmentdetected, see Environments
PlatformplatformplatformPlatformplatformdetected, see Platforms
VersionreleasereleaseReleaserelease, else the jar's manifestsent as resource.app_version
App idappIdapp_idAppIDappId, else the jar's manifestsent as resource.app_id
Lowest level keptminimumLevelminimum_levelMinimumLevelminimumLeveldebug
Send intervalflushIntervalMsflush_intervalFlushIntervalflushIntervalMillis5 s
Queue sizemaxQueuemax_queueMaxQueuemaxDiskBytes10,000 events in memory; 20 MB on disk on the JVM
Consentconsentgranted (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

  1. Check the environment. The dashboard opens on production. Swift sends development from Xcode and the simulator, Android from every debug build, and React Native and Flutter apps do as the native SDK under them does. JavaScript sends development on localhost, and on Node whenever NODE_ENV isn't production, including when it's unset. Pick the environment, or All environments, in the top bar.
  2. 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, tag Lyrelog, 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: the lyrelog logger. Go: Config.ErrorLog; without it, the first problem is printed to stderr once. JVM: standard error, lines starting with lyrelog: , or Configuration.diagnostics. They say when the key was refused, the endpoint is wrong or a batch was dropped.
  3. Let the process send before it ends. Short scripts, serverless functions and processes that call exit must 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.
  4. Check consent and level. With consent pending nothing is sent. Events below the lowest level kept are never queued.
  5. Check the key. After a 401 or 403, nothing more is sent until the app or process restarts. An empty key sends nothing (in Go, New returns an error; on the JVM, start returns false).

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.start in tests. Anything logged before start is ignored.
  • Android: the same, don't call Lyrelog.start in unit tests. Debug builds send development; reaching an endpoint on your computer from the emulator needs a few settings, see In development and tests.
  • React Native: don't call Lyrelog.init in tests: calls before init are ignored. Debug builds send development.
  • Flutter: don't call Lyrelog.start in widget and unit tests: anything logged before start is ignored. On platforms the plugin doesn't support (web, desktop) every call does nothing. See In development and tests.
  • JavaScript: leave apiKey empty and the client warns once and sends nothing, or pass consent: "denied".
  • Python: an empty api_key gives a client that accepts events and sends nothing.
  • Go: New returns an error without an APIKey, and a nil *Client does nothing, so the same code runs without one.
  • JVM: leave the key out: start returns false and every call does nothing, the Logback appender included.