SDK
El mismo modelo en todos los lenguajes. Elige el tuyo, o envía eventos por HTTP.
Los SDK de Lyrelog comparten un mismo modelo (niveles, áreas, atributos, usuarios) y usan los mismos nombres siempre que el lenguaje lo permite, con su propio estilo de mayúsculas y minúsculas. La tabla muestra en qué se diferencian.
Apps
Web y servidores
Cualquier otra cosa
Apps
| Swift | Android | React Native | Flutter | |
|---|---|---|---|---|
| Inicio | 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: {...}) |
| Logger por área | Lyrelog.Logger(category: "checkout") | Lyrelog.logger("checkout") | Lyrelog.logger("checkout") | Lyrelog.logger('checkout') |
| Usuario | Lyrelog.setUser("u_123") | Lyrelog.setUser("u_123") | Lyrelog.setUser("u_123") | Lyrelog.setUser('u_123') |
| Pantalla | Lyrelog.screen("Settings") | Lyrelog.screen("Settings") | trackNavigation(ref), o Lyrelog.screen("Settings") | LyrelogNavigatorObserver(), o Lyrelog.screen('Settings') |
| Peticiones | session.loggedData(for:) | |||
| Capturar un error | Lyrelog.captureError(error) | Lyrelog.captureError(e) | Lyrelog.captureException(error) | Lyrelog.captureError(e, stackTrace: s) |
| Errores no capturados y crashes | Crashes y bloqueos de MetricKit, automático | Excepciones no capturadas, automático, se envían en el siguiente arranque | Errores fatales de JavaScript y de renderizado como crashes, promesas rechazadas y otros errores, además de los crashes nativos; automático | Errores de Dart (FlutterError, PlatformDispatcher), además de los crashes nativos; automático |
| Vaciar | await Lyrelog.flush() | Lyrelog.flush() (fuera del hilo principal) | await Lyrelog.flush() | await Lyrelog.flush() |
| Detener | await Lyrelog.stop() | Lyrelog.stop() | await Lyrelog.close() | await Lyrelog.stop() |
Web y servidores
| JavaScript | Python | Go | JVM | |
|---|---|---|---|---|
| Inicio | 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 = ...) |
| Logger por área | client.logger("checkout") | lyrelog.logger("checkout") | client.Logger("checkout") | Lyrelog.logger("checkout") |
| Usuario | client.setUser("u_123") | lyrelog.set_user("u_123") | client.SetUser("u_123") | Lyrelog.setUser("u_123"), o Lyrelog.userScope(id) para un hilo |
| Pantalla | client.screen("Settings") | |||
| Capturar un error | client.captureException(err) | lyrelog.capture_exception(exc) | client.CaptureError(err) | Lyrelog.captureError(e) |
| Errores no capturados y crashes | window y Node, automático | tu propio sys.excepthook | tu propio recover | captureUncaught = true (desactivado por defecto) |
| Vaciar | await client.flush() | lyrelog.flush() | client.Flush(ctx) | Lyrelog.flush() |
| Detener | await client.close() | lyrelog.shutdown() | client.Close() | Lyrelog.close() (un shutdown hook lo hace al salir) |
| Logging estándar | lyrelog.LoggingHandler() | lyrelog.NewSlogHandler(client, nil) | LyrelogAppender para Logback |
Los SDK de apps también pueden copiar cada evento al log propio de la plataforma, para que aparezca
en Xcode y en logcat: mirrorToOSLog en Swift, mirrorToLogcat en Android, mirrorToNativeLog
en React Native y mirrorToConsole en Flutter.
Versión preliminar interna
Todavía no hay ningún SDK publicado, así que por ahora todos los comandos de instalación de
estas páginas fallan: pnpm add, flutter pub add y uv add no encuentran ningún paquete,
Gradle y Maven no encuentran nada en Maven Central, y Swift Package Manager y go get no pueden
acceder a los repositorios privados. Cada página muestra la línea tal como quedará cuando los SDK
estén publicados.
Lo que cada SDK hace por ti
Los SDK de React Native y Flutter envían a través del SDK de Swift en iOS y del SDK de Android en Android, así que todo lo que sigue también es suyo, hecho a la manera nativa. El SDK de la JVM usa el motor del SDK de Android, configurado para un servidor.
- Nunca bloquea ni lanza excepciones en tu código. Al registrar un evento, el SDK lo copia en una cola y vuelve; un worker en segundo plano lo envía.
- Agrupa en lotes de hasta 500 eventos o unos 512 KiB por petición, una línea NDJSON por evento, con gzip cuando la plataforma lo permite.
- Envía a
https://ingest.lyrelog.comsalvo que configures otroendpoint. El endpoint es la URL base: si pegas la dirección completa.../v1/events:batch, el SDK elimina la ruta. Un endpoint incorrecto (un404o una redirección) se notifica como aviso en el log propio del SDK. - Reintenta los fallos temporales (
408,425,429, 5xx, errores de red) con backoff exponencial (1 s, doblando hasta 5 min) y jitter, respetandoRetry-After, también cuando llamas aflusho cierras el cliente. Todos los SDK menos el de Python usan full jitter (una espera aleatoria entre 0 y el máximo); Python usa equal jitter (entre la mitad del máximo y el máximo). - Descarta un lote rechazado. Cualquier otro 4xx (
400,413,415...) significa que el propio lote está mal, así que se descarta en lugar de reenviarlo. Una clave rechazada (401,403) detiene los envíos hasta que la app o el proceso se reinicia, y conserva los eventos. Las redirecciones nunca se siguen: una respuesta 3xx descarta el lote y registra un aviso, porque significa que el endpoint está mal. - Conserva los eventos ante un
429. Cuando una organización Free ha gastado los eventos del mes, o un proyecto supera su límite de frecuencia, el SDK conserva el lote y lo vuelve a intentar después deRetry-After(consulta API HTTP). Los SDK de apps (Swift, Android, React Native, Flutter) los guardan en disco entre arranques. El SDK de la JVM también los guarda en disco, en un directorio temporal para el proceso, salvo que le des unstorageDirectory. JavaScript, Python y Go los guardan en memoria. En cualquier caso, siguen aplicándose los topes de abajo. - Pone un tope a lo que espera: 10.000 eventos y 16 MiB en memoria por defecto en JavaScript, Python y Go; 20 MB en disco y 7 días en los SDK de apps y en la JVM. Los más antiguos se descartan primero.
- Oculta los secretos, igual en todos los SDK. El valor de un campo pasa a ser
"[redacted]"cuando su nombre, en minúsculas y sin-,_,.ni espacios, es o termina enauthorization,cookie,password,passwd,secret,token,apikey,privatekey,credential(s),accesskeyosignature. Así,X-Api-Key,csrf_tokenySet-Cookiese ocultan, ytoken_countymax_tokensno. Ocurre a cualquier profundidad de los atributos y del payload, antes de recortar nada, así que un secreto nunca sobrevive en una cadena acortada ni en la vista previa de un payload. Solo se comprueban los nombres: un secreto dentro de un mensaje o del texto de un error se envía tal cual. Cambia la lista conredactedKeys(Swift, Android, Flutter, JVM),redactKeys(JavaScript, React Native),redact_keys(Python) oRedactKeys(Go): tu lista sustituye a la predeterminada, y una vacía desactiva la ocultación. Para ampliarla, extiende los valores predeterminados exportados:Configuration.defaultRedactedKeysen Swift,Configuration.DEFAULT_REDACTED_KEYSen Android y en la JVM,LyrelogConfiguration.defaultRedactedKeysen Flutter,DEFAULT_REDACT_KEYSen JavaScript, React Native y Python, yDefaultRedactKeys()en Go. Los SDK de JavaScript y Python aceptan además un hookbeforeSend/before_sendpara modificar o descartar cualquier evento. - Vacía la cola con un temporizador (15 s en los SDK de apps, 5 s en la web y en los
servidores), cuando llamas a
flush, cuando una app pasa a segundo plano y al apagarse. - Ajusta los eventos a los límites del servidor antes de ponerlos en la cola, así que nunca envía una línea que el servidor rechazaría por su forma.
Configuración
Los mismos ajustes existen en todos los SDK, con los nombres de cada lenguaje. La página de cada SDK tiene la lista completa.
Apps
| Ajuste | Swift | Android | React Native | Flutter | Por defecto |
|---|---|---|---|---|---|
| Clave | apiKey | apiKey | apiKey | apiKey | obligatoria: una clave de ingesta |
| Endpoint | endpoint | endpoint | endpoint | endpoint | https://ingest.lyrelog.com |
| Entorno | environment | environment | environment | environment | detectado, consulta Entornos |
| Plataforma | platform | platform | platform | platform | el sistema operativo, consulta Plataformas |
| Versión | del bundle | appVersion, si no, del paquete | de la app | de la app | se envía como resource.app_version |
| Id de la app | del bundle | el nombre del paquete | el bundle id o el nombre del paquete | el bundle id o el nombre del paquete | se envía como resource.app_id |
| Nivel mínimo que se conserva | minimumLevel | minimumLevel | minimumLevel | minimumLevel | debug |
| Intervalo de envío | uploadInterval | flushIntervalMillis | flushIntervalMs | flushInterval | 15 s |
| Tamaño de la cola | maxDiskBytes | maxDiskBytes | maxDiskBytes | maxDiskBytes | 20 MB en disco |
| Consentimiento | consent | consent | consent | consent | granted |
| Demostrar la app (eventos verificados) | appAttest | attest | attest | attest | activado |
Web y servidores
| Ajuste | JavaScript | Python | Go | JVM | Por defecto |
|---|---|---|---|---|---|
| Clave | apiKey | api_key | APIKey | apiKey | obligatoria: una clave de ingesta en navegadores, una clave de servidor en servidores |
| Endpoint | endpoint | endpoint | Endpoint | endpoint | https://ingest.lyrelog.com |
| Entorno | environment | environment | Environment | environment | detectado, consulta Entornos |
| Plataforma | platform | platform | Platform | platform | detectada, consulta Plataformas |
| Versión | release | release | Release | release, si no, el manifest del jar | se envía como resource.app_version |
| Id de la app | appId | app_id | AppID | appId, si no, el manifest del jar | se envía como resource.app_id |
| Nivel mínimo que se conserva | minimumLevel | minimum_level | MinimumLevel | minimumLevel | debug |
| Intervalo de envío | flushIntervalMs | flush_interval | FlushInterval | flushIntervalMillis | 5 s |
| Tamaño de la cola | maxQueue | max_queue | MaxQueue | maxDiskBytes | 10.000 eventos en memoria; 20 MB en disco en la JVM |
| Consentimiento | consent | granted (navegadores) |
En las columnas de JavaScript y Go, la instancia se llama client (log en los ejemplos de
JavaScript); los demás SDK registran a través de Lyrelog o del módulo lyrelog. Los contadores
también se llaman según cada lenguaje: JavaScript y Python cuentan delivered, y Go, Sent.
Cuando los eventos no aparecen
- Comprueba el entorno. El panel se abre en
production. Swift envíadevelopmentdesde Xcode y el simulador, Android desde todas las builds de debug, y las apps de React Native y Flutter hacen lo mismo que el SDK nativo que tienen por debajo. JavaScript envíadevelopmentenlocalhost, y en Node siempre queNODE_ENVno seaproduction, también cuando no está definido. Elige el entorno, o All environments, en la barra superior. - Lee los mensajes propios del SDK. Swift: el unified log, subsistema
com.lyrelog.sdk, a nivel debug (en Console, activa Include Debug Messages). Android: logcat, etiquetaLyrelog, a nivel debug. React Native y Flutter: los del SDK nativo, en los mismos sitios; React Native, además, avisa una vez en Metro, en las builds de desarrollo, cuando falta la clave o el módulo nativo. JavaScript: líneas de consola que empiezan por[lyrelog]. Python: el loggerlyrelog. Go:Config.ErrorLog; sin él, el primer problema se imprime una vez en stderr. JVM: la salida de error estándar, líneas que empiezan porlyrelog:, oConfiguration.diagnostics. Te dicen cuándo se rechazó la clave, cuándo el endpoint está mal o cuándo se descartó un lote. - Deja que el proceso envíe antes de terminar. Los scripts cortos, las funciones serverless
y los procesos que llaman a
exittienen que vaciar o cerrar el cliente antes. El shutdown hook del SDK de la JVM lo hace en una salida normal, pero un handler serverless sigue teniendo que llamar a flush. Consulta la página de cada SDK. - Comprueba el consentimiento y el nivel. Con el consentimiento en
pendingno se envía nada. Los eventos por debajo del nivel mínimo que se conserva nunca entran en la cola. - Comprueba la clave. Después de un
401o un403, no se envía nada más hasta que la app o el proceso se reinicia. Una clave vacía no envía nada (en Go,Newdevuelve un error; en la JVM,startdevuelvefalse).
Qué no enviar
Usa message para un nombre de evento estable, nunca para texto con datos personales. Usa tus
propios ids para las personas (setUser, user_id), no direcciones de email. No pongas tokens,
contraseñas ni cuerpos completos de peticiones o respuestas con sus headers en los atributos ni en
los payloads. La ocultación es una red de seguridad para los nombres de clave que conoce, no un
filtro en el que puedas confiar.
En desarrollo y en tests
- Swift: no llames a
Lyrelog.starten los tests. Todo lo que se registra antes destartse ignora. - Android: lo mismo, no llames a
Lyrelog.starten los tests unitarios. Las builds de debug envíandevelopment; llegar desde el emulador a un endpoint en tu ordenador requiere algunos ajustes, consulta En desarrollo y en tests. - React Native: no llames a
Lyrelog.initen los tests: las llamadas anteriores ainitse ignoran. Las builds de debug envíandevelopment. - Flutter: no llames a
Lyrelog.starten los tests de widgets y unitarios: todo lo que se registra antes destartse ignora. En las plataformas que el plugin no admite (web, escritorio), ninguna llamada hace nada. Consulta En desarrollo y en tests. - JavaScript: deja
apiKeyvacío y el cliente avisa una vez y no envía nada, o pasaconsent: "denied". - Python: un
api_keyvacío da un cliente que acepta eventos y no envía nada. - Go:
Newdevuelve un error sinAPIKey, y un*Clientnilno hace nada, así que el mismo código funciona sin él. - JVM: omite la clave:
startdevuelvefalsey ninguna llamada hace nada, tampoco el appender de Logback.