Acceso anticipadoSolo por invitación, y los SDK aún no están publicados.Pedir una invitación
Ir al contenido
Docs

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

SwiftAndroidReact NativeFlutter
InicioLyrelog.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: {...})
Logger por áreaLyrelog.Logger(category: "checkout")Lyrelog.logger("checkout")Lyrelog.logger("checkout")Lyrelog.logger('checkout')
UsuarioLyrelog.setUser("u_123")Lyrelog.setUser("u_123")Lyrelog.setUser("u_123")Lyrelog.setUser('u_123')
PantallaLyrelog.screen("Settings")Lyrelog.screen("Settings")trackNavigation(ref), o Lyrelog.screen("Settings")LyrelogNavigatorObserver(), o Lyrelog.screen('Settings')
Peticionessession.loggedData(for:)
Capturar un errorLyrelog.captureError(error)Lyrelog.captureError(e)Lyrelog.captureException(error)Lyrelog.captureError(e, stackTrace: s)
Errores no capturados y crashesCrashes y bloqueos de MetricKit, automáticoExcepciones no capturadas, automático, se envían en el siguiente arranqueErrores fatales de JavaScript y de renderizado como crashes, promesas rechazadas y otros errores, además de los crashes nativos; automáticoErrores de Dart (FlutterError, PlatformDispatcher), además de los crashes nativos; automático
Vaciarawait Lyrelog.flush()Lyrelog.flush() (fuera del hilo principal)await Lyrelog.flush()await Lyrelog.flush()
Detenerawait Lyrelog.stop()Lyrelog.stop()await Lyrelog.close()await Lyrelog.stop()

Web y servidores

JavaScriptPythonGoJVM
InicioLyrelog.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 = ...)
Logger por áreaclient.logger("checkout")lyrelog.logger("checkout")client.Logger("checkout")Lyrelog.logger("checkout")
Usuarioclient.setUser("u_123")lyrelog.set_user("u_123")client.SetUser("u_123")Lyrelog.setUser("u_123"), o Lyrelog.userScope(id) para un hilo
Pantallaclient.screen("Settings")
Capturar un errorclient.captureException(err)lyrelog.capture_exception(exc)client.CaptureError(err)Lyrelog.captureError(e)
Errores no capturados y crasheswindow y Node, automáticotu propio sys.excepthooktu propio recovercaptureUncaught = true (desactivado por defecto)
Vaciarawait client.flush()lyrelog.flush()client.Flush(ctx)Lyrelog.flush()
Detenerawait client.close()lyrelog.shutdown()client.Close()Lyrelog.close() (un shutdown hook lo hace al salir)
Logging estándarlyrelog.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.com salvo que configures otro endpoint. El endpoint es la URL base: si pegas la dirección completa .../v1/events:batch, el SDK elimina la ruta. Un endpoint incorrecto (un 404 o 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, respetando Retry-After, también cuando llamas a flush o 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 de Retry-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 un storageDirectory. 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 en authorization, cookie, password, passwd, secret, token, apikey, privatekey, credential(s), accesskey o signature. Así, X-Api-Key, csrf_token y Set-Cookie se ocultan, y token_count y max_tokens no. 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 con redactedKeys (Swift, Android, Flutter, JVM), redactKeys (JavaScript, React Native), redact_keys (Python) o RedactKeys (Go): tu lista sustituye a la predeterminada, y una vacía desactiva la ocultación. Para ampliarla, extiende los valores predeterminados exportados: Configuration.defaultRedactedKeys en Swift, Configuration.DEFAULT_REDACTED_KEYS en Android y en la JVM, LyrelogConfiguration.defaultRedactedKeys en Flutter, DEFAULT_REDACT_KEYS en JavaScript, React Native y Python, y DefaultRedactKeys() en Go. Los SDK de JavaScript y Python aceptan además un hook beforeSend / before_send para 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

AjusteSwiftAndroidReact NativeFlutterPor defecto
ClaveapiKeyapiKeyapiKeyapiKeyobligatoria: una clave de ingesta
Endpointendpointendpointendpointendpointhttps://ingest.lyrelog.com
Entornoenvironmentenvironmentenvironmentenvironmentdetectado, consulta Entornos
Plataformaplatformplatformplatformplatformel sistema operativo, consulta Plataformas
Versióndel bundleappVersion, si no, del paquetede la appde la appse envía como resource.app_version
Id de la appdel bundleel nombre del paqueteel bundle id o el nombre del paqueteel bundle id o el nombre del paquetese envía como resource.app_id
Nivel mínimo que se conservaminimumLevelminimumLevelminimumLevelminimumLeveldebug
Intervalo de envíouploadIntervalflushIntervalMillisflushIntervalMsflushInterval15 s
Tamaño de la colamaxDiskBytesmaxDiskBytesmaxDiskBytesmaxDiskBytes20 MB en disco
Consentimientoconsentconsentconsentconsentgranted
Demostrar la app (eventos verificados)appAttestattestattestattestactivado

Web y servidores

AjusteJavaScriptPythonGoJVMPor defecto
ClaveapiKeyapi_keyAPIKeyapiKeyobligatoria: una clave de ingesta en navegadores, una clave de servidor en servidores
EndpointendpointendpointEndpointendpointhttps://ingest.lyrelog.com
EntornoenvironmentenvironmentEnvironmentenvironmentdetectado, consulta Entornos
PlataformaplatformplatformPlatformplatformdetectada, consulta Plataformas
VersiónreleasereleaseReleaserelease, si no, el manifest del jarse envía como resource.app_version
Id de la appappIdapp_idAppIDappId, si no, el manifest del jarse envía como resource.app_id
Nivel mínimo que se conservaminimumLevelminimum_levelMinimumLevelminimumLeveldebug
Intervalo de envíoflushIntervalMsflush_intervalFlushIntervalflushIntervalMillis5 s
Tamaño de la colamaxQueuemax_queueMaxQueuemaxDiskBytes10.000 eventos en memoria; 20 MB en disco en la JVM
Consentimientoconsentgranted (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

  1. Comprueba el entorno. El panel se abre en production. Swift envía development desde 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ía development en localhost, y en Node siempre que NODE_ENV no sea production, también cuando no está definido. Elige el entorno, o All environments, en la barra superior.
  2. 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, etiqueta Lyrelog, 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 logger lyrelog. 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 por lyrelog: , o Configuration.diagnostics. Te dicen cuándo se rechazó la clave, cuándo el endpoint está mal o cuándo se descartó un lote.
  3. Deja que el proceso envíe antes de terminar. Los scripts cortos, las funciones serverless y los procesos que llaman a exit tienen 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.
  4. Comprueba el consentimiento y el nivel. Con el consentimiento en pending no se envía nada. Los eventos por debajo del nivel mínimo que se conserva nunca entran en la cola.
  5. Comprueba la clave. Después de un 401 o un 403, 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, New devuelve un error; en la JVM, start devuelve false).

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.start en los tests. Todo lo que se registra antes de start se ignora.
  • Android: lo mismo, no llames a Lyrelog.start en los tests unitarios. Las builds de debug envían development; 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.init en los tests: las llamadas anteriores a init se ignoran. Las builds de debug envían development.
  • Flutter: no llames a Lyrelog.start en los tests de widgets y unitarios: todo lo que se registra antes de start se ignora. En las plataformas que el plugin no admite (web, escritorio), ninguna llamada hace nada. Consulta En desarrollo y en tests.
  • JavaScript: deja apiKey vacío y el cliente avisa una vez y no envía nada, o pasa consent: "denied".
  • Python: un api_key vacío da un cliente que acepta eventos y no envía nada.
  • Go: New devuelve un error sin APIKey, y un *Client nil no hace nada, así que el mismo código funciona sin él.
  • JVM: omite la clave: start devuelve false y ninguna llamada hace nada, tampoco el appender de Logback.