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

Android

Logs estructurados desde tu app de Android, en Kotlin o Java. Sin más dependencias que la biblioteca estándar de Kotlin.

Móviles y tabletas, en Kotlin o Java

El SDK de Android necesita Android 7.0 (API 24) o posterior. Está escrito en Kotlin, no tiene más dependencias que la biblioteca estándar de Kotlin (ni OkHttp, ni corrutinas, ni AndroidX) y todas sus funciones se pueden llamar también desde Java.

Versión preliminar interna: este paquete aún no está publicado. Hasta que lo esté, Gradle no puede descargar com.lyrelog:lyrelog-android: no está en Maven Central, y el repositorio es privado y todavía no tiene ninguna release.

Instalación

Desde Maven Central, en el build.gradle.kts del módulo de tu app:

dependencies {
    implementation("com.lyrelog:lyrelog-android:0.1.0")
}

La biblioteca añade el permiso INTERNET al manifest de tu app.

Primeros pasos

Arranca el SDK una sola vez y lo antes posible, en el onCreate de tu Application. Una segunda llamada mientras está en marcha se ignora. Los eventos registrados antes de start también se ignoran, pero setUser y setConsent llamados antes de start se guardan y se aplican cuando se ejecuta.

import android.app.Application
import com.lyrelog.Configuration
import com.lyrelog.Lyrelog

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        Lyrelog.start(this, Configuration(
            apiKey = "lyr_ing_...",          // ingest-only: it can append events, never read them
        ))
    }
}

Indica la clase en el manifest (<application android:name=".MyApp" ...>) si tu app todavía no tiene un Application.

Los eventos van a https://ingest.lyrelog.com. Pasa endpoint solo para enviarlos a otro sitio. Es la URL base (si pegas una ruta .../v1/events:batch, se elimina) y tiene que ser https; http sin cifrar solo funciona con localhost, 127.0.0.1 o ::1, y en el emulador con 10.0.2.2 (consulta En desarrollo y en tests). Con cualquier otro endpoint no se envía nada y los eventos se quedan en el dispositivo.

Registrar eventos

Una función por nivel: trace, debug, info, notice, warning, error, critical, o log(level, message, ...) con un Level.

Lyrelog.info("checkout_done", attrs = mapOf("items" to 3, "latency_ms" to ms))
Lyrelog.error("payment_declined", category = "checkout",
              attrs = mapOf("code" to 51), payload = mapOf("response" to raw))

Los atributos son un Map<String, Any?>: cadenas, números, booleanos, null, listas (sus elementos se envían como cadenas) y mapas anidados de hasta 4 niveles. El payload es cualquier mapa, lista o valor, para el detalle que solo lees al abrir un evento.

Loggers por área

Un logger pone su category en cada evento, como una etiqueta de log de Android. Tiene todos los niveles, además de log y captureError. Es barato de crear y de conservar, y registra en el SDK que esté en marcha cuando se le llama.

val sync = Lyrelog.logger("sync")
sync.warning("sync_conflict", mapOf("records" to 2))

Usuarios

Lyrelog.setUser(playerId)   // attached to every following event
Lyrelog.setUser(null)       // on sign-out

Lyrelog.sessionId da el id de la sesión actual, por ejemplo para mostrarlo en una pantalla de soporte.

El id de usuario no se guarda entre arranques: vuelve a llamar a setUser en cada arranque, en cuanto sepas quién es la persona.

Pantallas

Indica dónde está la persona. Lyrelog registra screen_viewed (área navigation) con la pantalla anterior y los segundos que pasó en ella, y etiqueta cada evento siguiente con un atributo screen.

override fun onResume() {
    super.onResume()
    Lyrelog.screen("Settings")
}

En Compose, llámalo desde un LaunchedEffect cuando se muestre un destino. El evento lleva screen, previous_screen y seconds_on_previous. Llamar a screen otra vez con el mismo nombre no registra nada. screen acepta attrs adicionales para el evento screen_viewed. Desactiva el etiquetado con attachScreen = false.

automaticScreens = true lo hace por ti con cada Activity que pasa al frente, con el nombre de su clase (SettingsActivity). Viene desactivado: las apps con Compose o con fragments tienen muchas pantallas en una sola Activity, y un nombre elegido por ti se lee mejor en el panel.

Errores que capturas

try {
    store.purchase(product)
} catch (e: IOException) {
    Lyrelog.captureError(e, category = "store")
}

Envía el evento exception que envían todos los SDK: nivel error, los atributos error_type (el nombre de la clase) y error_message, y un payload con la descripción, hasta 60 frames, las causas (hasta 8, con 20 frames cada una) y las excepciones suprimidas. attrs añade los tuyos; level cambia el nivel. Cada logger también tiene captureError.

Los frames son tal como los da la VM. Si la app está minificada con R8, ejecuta retrace con el archivo de mapping de la build para obtener los nombres originales.

Crashes

Una excepción no capturada se escribe en disco en el momento, en el hilo que está muriendo, junto con cualquier evento que siga de camino al disco. Después se pasa al handler que hubiera antes (el diálogo de crash del sistema, u otro crash reporter que instalara el suyo primero). En ese momento no se envía nada: el proceso está a punto de terminar.

El siguiente arranque lo envía, con la hora en que ocurrió y en la sesión que terminó, en el área diagnostics, igual que los informes de crash del SDK de Swift, así que los crashes de las dos plataformas aparecen juntos en el panel:

EventoNivelQué lleva
app_crashedcriticalerror_type, error_message, handled: false, mechanism: uncaught_exception y un payload con el hilo, los frames, las causas y las excepciones suprimidas

Viene activado por defecto; desactívalo con captureCrashes = false. Los crashes nativos y los ANR no se registran.

Entornos y plataforma

Al arrancar, el SDK elige el entorno: development cuando la app es depurable (android:debuggable, todas las builds de debug) y production en cualquier otro caso.

Tus propias builds de debug envían development, mientras que el panel se abre en production: elige development en la barra superior para verlas.

La plataforma es android. Puedes sobrescribir cualquiera de los dos en la configuración:

Configuration(
    apiKey = key,
    environment = if (BuildConfig.FLAVOR == "beta") "beta" else null,   // null = detected
    platform = null,
)

Vale cualquier nombre: letras minúsculas, dígitos, - y _, hasta 32. Cualquier otro texto se convierte en un nombre válido (Staging EU pasa a ser staging-eu).

Lyrelog.start(this, Configuration(apiKey = key, consent = Consent.PENDING))
// later, when the person chooses:
Lyrelog.setConsent(Consent.GRANTED)   // sends, including what was kept while pending
Lyrelog.setConsent(Consent.DENIED)    // deletes everything and stops recording

PENDING guarda los eventos en el dispositivo sin enviarlos. No se sube nada si no se ha concedido el consentimiento, tampoco lo que dejó un arranque anterior. Arrancar con Consent.DENIED borra lo que quede en la cola de un arranque anterior y el id de instalación, y no registra nada. Un setConsent antes de start prevalece sobre Configuration.consent.

El consentimiento no se guarda entre arranques: guarda tú la elección de la persona y pásala a start cada vez.

Una app completa

Arranca con el consentimiento guardado, asigna la persona cuando inicia sesión y etiqueta las pantallas:

import android.app.Application
import com.lyrelog.Configuration
import com.lyrelog.Consent
import com.lyrelog.Lyrelog

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        val prefs = getSharedPreferences("settings", MODE_PRIVATE)
        val consent = when (prefs.getString("diagnostics", null)) {
            "granted" -> Consent.GRANTED
            "denied" -> Consent.DENIED
            else -> Consent.PENDING
        }
        Lyrelog.start(this, Configuration(apiKey = "lyr_ing_...", consent = consent))
    }
}

class HomeActivity : AppCompatActivity() {
    override fun onResume() {
        super.onResume()
        Lyrelog.screen("Home")
    }

    private fun signedIn(account: Account) {
        Lyrelog.setUser(account.id)
        Lyrelog.info("signed_in", category = "auth")
    }
}

fun choose(context: Context, allowed: Boolean) {
    context.getSharedPreferences("settings", Context.MODE_PRIVATE).edit()
        .putString("diagnostics", if (allowed) "granted" else "denied").apply()
    Lyrelog.setConsent(if (allowed) Consent.GRANTED else Consent.DENIED)
}

Vaciar la cola y detener

Pasar a segundo plano ya envía (cuando se detiene la última Activity; una rotación no cuenta), así que rara vez te hará falta.

Lyrelog.flushInBackground()   // send now, without waiting
Lyrelog.flush()               // write everything to disk and send, waiting up to 5 seconds
Lyrelog.stop()                // send what's queued (up to 2 seconds), then stop
Lyrelog.stopNow()             // stop at once; what was logged goes with the next launch

flush y stop bloquean, así que nunca los llames en el hilo principal. flush devuelve true cuando termina a tiempo, y respeta el Retry-After que haya pedido el servidor: no envía antes. Después de stop se puede volver a llamar a start.

En desarrollo y en tests

No llames a Lyrelog.start en los tests unitarios: todo lo que se registra antes de start se ignora, así que el resto de tu código se ejecuta sin cambios. Con mirrorToLogcat = true, además, cada evento se imprime en logcat (etiqueta Lyrelog) mientras trabajas.

Las builds de debug envían el entorno development. Para enviar desde el emulador a un endpoint que corre en tu ordenador, usa http://10.0.2.2 y su puerto como endpoint (10.0.2.2 es tu ordenador visto desde el emulador), solo en la build de debug:

  • Permite http sin cifrar hacia 10.0.2.2. Android lo bloquea salvo que la app lo permita: añade a la build de debug una network security config que permita cleartext para esa única dirección.
  • En Android 17, una app con target API 37 también necesita ACCESS_LOCAL_NETWORK para llegar a una dirección privada como 10.0.2.2; sin él, la conexión simplemente agota el tiempo de espera. Declara el permiso en el manifest de debug (src/debug/AndroidManifest.xml) y concédelo: adb shell pm grant <your.app> android.permission.ACCESS_LOCAL_NETWORK.

Esto es solo para desarrollo local. La ingesta alojada es una dirección https pública y no necesita ninguna de las dos cosas.

Eventos verificados

Un evento verificado es uno que no puede haber enviado alguien que copió la clave de ingesta pública de una app o de una página web. Qué demuestra eso, y qué no, está en Eventos verificados.

Los eventos de una app de Android se verifican con Key Attestation: el hardware seguro del teléfono demuestra que vienen de tu propia app, firmada con tu certificado, en un dispositivo real que no está rooteado ni desbloqueado. Lyrelog lo comprueba en sus propios servidores; no hace falta ninguna cuenta de Google, ni Play Integrity, ni un proyecto de Google Cloud.

Viene activado por defecto (attest en Configuration); configúralo en el proyecto:

  1. En Project settings, en Verified events from your Android apps, añade tu paquete y la huella SHA-256 de cada certificado que firme builds que envían eventos: la clave de firma de apps de Play (Play Console, Test and release, App integrity) y, para las builds que firmas tú, la que muestra ./gradlew signingReport.
  2. En la app no hace falta nada más. Para desactivarlo:
Lyrelog.start(this, Configuration(apiKey = "lyr_ing_...", attest = false))

Una vez por instalación, el SDK crea una clave en el hardware seguro del teléfono (StrongBox o el trusted execution environment) y hace que el dispositivo la ateste; a partir de ahí, sus lotes llevan un token y llegan verificados (verified_by es key_attestation). El token dura 24 horas y se renueva en segundo plano antes de caducar. El envío nunca espera a esto: hasta que la app tiene un token, y cada vez que algo falla, los eventos se envían sin verificar.

  • Los emuladores nunca verifican, y el SDK ni lo intenta en ellos.
  • Mientras el proyecto no tenga una app de Android configurada, o cuando la clave se rechaza o el dispositivo no puede atestar, el SDK desactiva la atestación durante ese arranque y lo avisa una vez en logcat.
  • Un dispositivo que el servidor rechaza (un teléfono rooteado, un bootloader desbloqueado, un certificado que el proyecto no tiene en su lista) vuelve a intentarlo un día después.
  • Denegar el consentimiento borra la clave atestada y su registro (noBackupFilesDir/lyrelog/attest.json).

Mientras no esté configurado, los eventos llegan sin verificar y cuentan para la cuota diaria de una dirección. Antes de hacer que el proyecto acepte solo eventos verificados de android, comprueba en el explorador que los eventos de tus usuarios reales llegan verificados: los eventos de versiones antiguas, de emuladores y de dispositivos rechazados se quedarían retenidos con un 425.

Los eventos que tus propios servidores envían con una clave de servidor, lyr_srv_..., están verificados. Nunca pongas una clave de servidor en una app: cualquier cosa que vaya en un APK se puede leer.

Para comprobarlo, abre el explorador: un evento abierto lo indica en Context, en su línea Sender: Verified, Key Attestation o Not verified, public key.

Consulta Eventos verificados para saber quién verifica qué y cómo funciona la cuota diaria.

Desde Java

Desde Java, todas las funciones de Lyrelog son estáticas, con sobrecargas para los argumentos opcionales:

Lyrelog.start(this, new Configuration("lyr_ing_..."));
Lyrelog.info("checkout_done");
Lyrelog.captureError(e, "store");

Configuration y las funciones de un logger también tienen sobrecargas, así que los argumentos finales se pueden omitir (logger.warning("sync_conflict"), logger.warning("sync_conflict", attrs)).

Configuración

OpciónPor defectoSignificado
apiKeyobligatoriaLa clave de ingesta del proyecto
endpointhttps://ingest.lyrelog.comLa URL base; si pegas una ruta /v1/..., se elimina. Solo https; http solo para localhost y el 10.0.2.2 del emulador
consentConsent.GRANTEDPENDING, GRANTED o DENIED
minimumLevelLevel.DEBUGLos eventos por debajo nunca llegan al disco
flushIntervalMillis15 sCada cuánto se ejecuta el envío mientras hay una Activity iniciada
maxBatchBytes512 KiBUn lote se cierra en el primer límite que se alcance (se mantiene dentro de 4 MiB)
maxBatchEvents500Como máximo 2.000
maxDiskBytes20 MBTope de la cola en disco; se descartan primero los más antiguos
maxEventAgeMillis7 díasLos eventos en cola más antiguos se descartan
sessionTimeoutMillis30 minTiempo de inactividad que inicia una sesión nueva
environmentdetectadoCualquier nombre válido, o null
platformandroidCualquier nombre válido, o null
appVersionel versionName de la appSe envía como resource.app_version
redactedKeysnull: DEFAULT_REDACTED_KEYSNombres de clave cuyos valores se ocultan; tu lista sustituye a la predeterminada, y una lista vacía desactiva la ocultación
captureCrashestrueRegistra las excepciones no capturadas, que se envían en el siguiente arranque
attachScreentrueEtiqueta los eventos con la pantalla actual
automaticScreensfalseRegistra screen_viewed para cada Activity, con el nombre de su clase
attesttrueDemuestra la app con Key Attestation para que sus eventos lleguen verificados, cuando el proyecto tiene su paquete y su certificado
mirrorToLogcatfalseImprime además cada evento en logcat (etiqueta Lyrelog)
storageDirectorynoBackupFilesDir/lyrelogDónde vive la cola

Entrega y límites

Nunca bloqueaAl registrar, el SDK copia el evento y vuelve; un único proceso de escritura en segundo plano lo pone en disco y nunca espera a la red.
Sobrevive a cierres forzados y a la falta de conexiónUna cola en noBackupFilesDir/lyrelog, con un tope de 20 MB y 7 días. Lo que llegó al disco sobrevive a un crash, a un cierre forzado o a días sin conexión; los eventos que aún van de camino al proceso de escritura (milisegundos) los escribe el handler de crashes, o se pierden si el proceso se mata de golpe. La carpeta nunca entra en una copia de seguridad, así que un teléfono restaurado no reenvía los eventos de otro dispositivo.
Cuándo envíaCada 15 s mientras hay una Activity iniciada, y una vez cuando la app pasa a segundo plano. En segundo plano no se ejecuta nada con temporizador: lo que queda sale en el siguiente arranque o la próxima vez que la app pasa al frente.
LotesHasta 500 eventos o 512 KiB por petición, con gzip. Un evento de más de 1 MiB una vez codificado se descarta y se cuenta.
Reintentos1 s, doblando hasta 5 min, con full jitter y respetando Retry-After. Cualquier otro 4xx descarta el lote, un 3xx (una redirección, que nunca se sigue) también lo descarta, y una clave revocada (401, 403) detiene los envíos hasta el siguiente arranque y conserva los eventos. Un lote que el servidor sigue rechazando mientras otros pasan se manda al final de la cola y después se descarta.
Cuota mensualCuando una organización Free ha gastado los eventos del mes, el servidor responde 429. Los eventos se quedan en la cola en disco y salen cuando el servidor vuelve a aceptarlos, dentro de los topes de 20 MB y 7 días. El SDK registra un aviso en logcat, y no vuelve a hacerlo hasta que se haya aceptado algún lote entre medias.
Los descartes se venLos eventos perdidos por los topes se convierten en un aviso lyrelog_events_dropped (área lyrelog) con el número.
Sus propios problemasUn endpoint incorrecto, un 404, líneas rechazadas o un endpoint que no responde se registran una vez por arranque en logcat, etiqueta Lyrelog, a nivel debug.
ContextoId de la app (el nombre del paquete), version name, version code, android, la versión de Android, el dispositivo (Google Pixel 9), configuración regional, entorno, plataforma android, id de sesión (nuevo tras 30 min de inactividad) e id de instalación.
SecretosLos valores de las claves cuyo nombre es o termina en authorization, cookie, password, token, secret, apikey y el resto de la lista común pasan a ser "[redacted]", a cualquier profundidad, antes de recortar nada.
LímitesLas cadenas largas se cortan sin partir ningún carácter, los atributos de más se cuentan en lyrelog_dropped_attrs y los payloads de más de 64 KiB se resumen como {"lyrelog_truncated": true, "bytes": N, "preview": "..."}.

Cambia la lista con redactedKeys: tu lista sustituye a la predeterminada, y una lista vacía desactiva la ocultación. Para ampliarla:

Lyrelog.start(this, Configuration(
    apiKey = "lyr_ing_...",
    redactedKeys = Configuration.DEFAULT_REDACTED_KEYS + "pin",
))

Seguridad de los datos en Play

Para el formulario de seguridad de los datos de Play Console, declara lo que tu app envía a través de Lyrelog:

  • App info and performance: Crash logs, Diagnostics (App functionality, y Analytics si lo usas para eso). Recogidos, no compartidos.
  • Device or other IDs: el id de instalación, un UUID aleatorio que no es el id de publicidad, no entra en las copias de seguridad y se borra si se deniega el consentimiento. No está vinculado a la persona salvo que también llames a setUser.
  • App activity > App interactions: si registras pantallas (screen_viewed) o toques.
  • Cualquier otra cosa que lleven tus attrs o tu payload (emails, compras...), en su propia categoría.

Los datos van cifrados en tránsito (https). El servidor añade el país de la dirección que envía; la propia dirección no se guarda.