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

Flutter

Logs estructurados desde tu app de Flutter en iOS y Android, sobre los SDK nativos de Lyrelog.

Apps de iOS y Android, sobre los SDK nativos

El SDK de Flutter es el paquete de Dart lyrelog, un plugin para iOS 16 y Android 7.0 (API 24) o posteriores, hecho con Flutter 3.50. Es una capa ligera de Dart sobre los SDK nativos, el SDK de Swift en iOS y el SDK de Android en Android, así que la cola en disco, los crashes nativos, el envío en segundo plano, las sesiones, el consentimiento y los eventos verificados funcionan igual que en ellos. Además, registra los errores de Dart que nadie captura y pone nombre a las pantallas a partir de tu navigator.

Versión preliminar interna: este paquete aún no está publicado. Hasta que lo esté, flutter pub add lyrelog no encuentra nada: no está en pub.dev, y el repositorio es privado y todavía no tiene ninguna release.

Instalación

flutter pub add lyrelog

O en pubspec.yaml:

dependencies:
  lyrelog: ^0.1.0

Configuración en iOS

  • El plugin es un paquete Swift, así que tu app lo compila con Swift Package Manager, que Flutter usa por defecto. No hay versión para CocoaPods.
  • Pon el mínimo de la app en iOS 16: en Xcode, el target Runner, General, Minimum Deployments (IPHONEOS_DEPLOYMENT_TARGET = 16.0). El valor por defecto de Flutter es más bajo, y la build se detiene con un mensaje que lo indica.

Configuración en Android

  • Los valores por defecto de Flutter funcionan: compileSdk 36 y Kotlin 2.2 o posterior. minSdk puede quedarse en 24.

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 main, antes de runApp. Una segunda llamada mientras está en marcha se ignora. start llama por sí mismo a WidgetsFlutterBinding.ensureInitialized(), así que puede ir lo primero, y nada tiene que esperarlo: lo que registres después de start llega al SDK nativo después de él. Los eventos registrados antes de start se ignoran, pero setUser y setConsent llamados antes de start se guardan y se aplican cuando se ejecuta.

import 'package:flutter/widgets.dart';
import 'package:lyrelog/lyrelog.dart';

void main() {
  Lyrelog.start(const LyrelogConfiguration(
    apiKey: 'lyr_ing_...', // ingest-only: it can append events, never read them
  ));
  runApp(const MyApp());
}

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 de Android 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 LogLevel.

Lyrelog.info('checkout_done', attrs: {'items': 3, 'latency_ms': ms});
Lyrelog.error('payment_declined', category: 'checkout',
    attrs: {'code': 51}, payload: {'response': raw});

Los atributos son un Map<String, Object?>: cadenas, números, booleanos, null, listas y mapas anidados de hasta 4 niveles. Un DateTime se envía como texto ISO 8601, un Duration en milisegundos, un enum como su nombre, y cualquier otra cosa como su toString(). El payload es cualquier valor de esos tipos, 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. 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.

final sync = Lyrelog.logger('sync');
sync.warning('sync_conflict', attrs: {'records': 2});

Usuarios

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

await 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.

Añade LyrelogNavigatorObserver al navigator de tu app, y cada page route que pasa a primer plano es una pantalla, con el nombre de su ruta:

MaterialApp(
  navigatorObservers: [LyrelogNavigatorObserver()],
  routes: {
    '/': (_) => const HomePage(),
    '/settings': (_) => const SettingsPage(),
  },
)

Funciona con cualquier Navigator, así que también con un router que acepte observers (con go_router, GoRouter(observers: [LyrelogNavigatorObserver()], ...)). Volver a una página la registra otra vez, porque vuelve a ser la pantalla actual. Los diálogos, los bottom sheets y los menús no cambian la pantalla, y las rutas sin nombre se omiten. Puedes cambiar las dos cosas:

LyrelogNavigatorObserver(
  nameExtractor: (settings) => settings.name?.replaceFirst('/', ''), // null or '' skips the route
  routeFilter: (route) => route is PageRoute,                         // which routes are screens
)

O llámalo tú:

Lyrelog.screen('Settings');

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.

Errores que capturas

try {
  await store.purchase(product);
} catch (e, s) {
  Lyrelog.captureError(e, stackTrace: s, category: 'store');
}

Envía el evento exception que envían todos los SDK: nivel error, los atributos error_type (el tipo en tiempo de ejecución) y error_message (su toString()), y un payload con la descripción y hasta 60 frames del stack. Sin stackTrace, los frames son el stack propio de un Error, si lo tiene. attrs añade los tuyos; level cambia el nivel. Cada logger también tiene captureError.

Errores y crashes

Errores de Dart que nadie captura

start los registra por su cuenta (captureErrors, activado por defecto), como eventos exception con handled: false y un mechanism que indica dónde los entregó Flutter:

mechanismDe dóndeEl payload también lleva
flutter_errorFlutterError.onError: errores al construir, maquetar o pintar widgets, y en callbacks de gestoslibrary (widgets library) y context (building MyWidget)
platform_dispatcherPlatformDispatcher.instance.onError: errores en código asíncrono, en temporizadores y en futures que nadie esperó

Los handlers que había antes siguen ejecutándose, después de los de Lyrelog, y PlatformDispatcher.onError devuelve lo que devolvía el anterior (si no había ninguno, Flutter sigue imprimiendo el error). Si configuras tus propios handlers, hazlo antes de start, o llama a captureError desde ellos.

Se envían como máximo 10 por minuto, y el mismo error (su tipo, su mensaje y su frame superior) solo una vez cada 10 segundos, así que un error de layout que se repite en cada frame envía un solo evento. Los errores que Flutter marca como silenciosos, que tampoco notifica en las builds de release (una imagen que no se pudo cargar, por ejemplo), se dejan fuera.

Un error de Dart no cierra una app de Flutter, así que son eventos exception, nunca app_crashed.

Si tu app se ejecuta en una zona propia, registra los errores de la zona del mismo modo:

runZonedGuarded(() => runApp(const MyApp()), (error, stack) {
  Lyrelog.captureError(error, stackTrace: stack, handled: false, mechanism: 'zone');
});

Crashes nativos

Los crashes de la propia app llegan de los SDK nativos (captureNativeCrashes, activado por defecto). Se envían en el siguiente arranque, con la hora en que ocurrieron, en el área diagnostics:

PlataformaEventosDe dónde
iOSapp_crashed (critical), app_hung (error), cpu_overuse, disk_write_overuse, slow_launch (warnings)MetricKit, como en la página de Swift
Androidapp_crashed (critical) con handled: false y mechanism: uncaught_exceptionExcepciones de la JVM no capturadas, como en la página de Android

En Android, los crashes nativos (C o C++) y los ANR no se registran.

Builds ofuscadas

Con flutter build --obfuscate --split-debug-info=<dir>, los nombres de tipo de error_type y de los frames quedan ofuscados. Guarda los símbolos que escribe la build y ejecuta flutter symbolize con ellos sobre los frames para poder leerlos.

Entornos y plataforma

El SDK nativo elige el entorno al arrancar:

  • iOS: development para una build de debug, cualquier build en el simulador o una build con un provisioning profile incrustado (firma de desarrollo y ad hoc); testflight para una build de TestFlight; production en cualquier otro caso. Después, la respuesta de StoreKit, como en la página de Swift.
  • Android: development cuando la app es depurable (todas las builds de debug) y production en cualquier otro caso.

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

La plataforma es el sistema operativo, ios o android, así que un mismo proyecto recoge las dos y el panel puede filtrar por cada una. Puedes sobrescribir cualquiera de los dos en la configuración:

LyrelogConfiguration(
  apiKey: key,
  environment: isInternalTester ? 'internal' : 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(LyrelogConfiguration(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

Consent.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 el consent de la configuración.

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 pon nombre a las pantallas a partir del navigator:

import 'package:flutter/material.dart';
import 'package:lyrelog/lyrelog.dart';
import 'package:shared_preferences/shared_preferences.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  final prefs = await SharedPreferences.getInstance();
  final consent = switch (prefs.getString('diagnostics')) {
    'granted' => Consent.granted,
    'denied' => Consent.denied,
    _ => Consent.pending,
  };
  Lyrelog.start(LyrelogConfiguration(apiKey: 'lyr_ing_...', consent: consent));
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) => MaterialApp(
        navigatorObservers: [LyrelogNavigatorObserver()],
        routes: {
          '/': (_) => const HomePage(),
          '/sign-in': (_) => SignInPage(onSignedIn: signedIn),
        },
      );
}

void signedIn(Account account) {
  Lyrelog.setUser(account.id);
  Lyrelog.info('signed_in', category: 'auth');
}

Future<void> choose(bool allowed) async {
  final prefs = await SharedPreferences.getInstance();
  await prefs.setString('diagnostics', allowed ? 'granted' : 'denied');
  Lyrelog.setConsent(allowed ? Consent.granted : Consent.denied);
}

Vaciar la cola y detener

Pasar a segundo plano ya envía: en iOS, dentro de una background task; en Android, cuando se detiene la Activity de la app. Así que rara vez te hará falta.

await Lyrelog.flush(); // write everything to disk and send, waiting up to 5 seconds
await Lyrelog.stop();  // send what's queued (up to 2 seconds), then stop

flush devuelve true cuando termina a tiempo (timeout: cambia la espera), 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

En los tests de widgets y unitarios, no llames a Lyrelog.start: todo lo que se registra antes de start se ignora, así que el resto de tu código se ejecuta sin cambios. En una plataforma que el plugin no admite (web, escritorio), ninguna llamada hace nada ni lanza excepciones.

Con mirrorToConsole: true, además, cada evento se imprime en el log nativo mientras trabajas: la consola de Xcode en iOS y logcat (etiqueta Lyrelog) en Android.

Las builds de debug envían el entorno development. Para enviar a un endpoint que corre en tu ordenador:

  • Simulador de iOS: usa http://127.0.0.1 y su puerto. El simulador comparte la red de tu ordenador, y no hace falta ninguna excepción de App Transport Security para ello.
  • Emulador de Android: usa http://10.0.2.2 y su puerto (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 (android/app/src/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 (android/app/src/debug/AndroidManifest.xml) y concédelo: adb shell pm grant <your.app> android.permission.ACCESS_LOCAL_NETWORK.

Deja la clave fuera de tu código fuente con --dart-define-from-file, por ejemplo flutter run --dart-define-from-file=lyrelog.local.json y String.fromEnvironment('LYRELOG_KEY'), con ese archivo ignorado por git.

Esto es solo para desarrollo local. La ingesta alojada es una dirección https pública y no necesita nada de esto.

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 SDK nativos verifican la app en dispositivos reales (attest, activado por defecto), y en tu código Dart no cambia nada. Configura cada plataforma en la que se publica la app:

  • iOS, con App Attest de Apple (verified_by es app_attest):
    • Añade la capability App Attest al target Runner en Xcode (Signing & Capabilities), el entitlement com.apple.developer.devicecheck.appattest-environment. Ponlo a production para las builds de App Store y TestFlight; sin él, Apple usa el entorno de desarrollo.
    • Añade tu App ID, es decir, el Team ID, un punto y el bundle id (ABCDE12345.com.example.app), en Project settings, en Verified events from your Apple apps.
  • Android, con Key Attestation (verified_by es key_attestation): 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 (ejecútalo en la carpeta android de tu app).

Para desactivarlo en las dos:

Lyrelog.start(const LyrelogConfiguration(apiKey: 'lyr_ing_...', attest: false));

El envío nunca espera a la atestación: hasta que la app tiene un token, y cada vez que algo falla, los eventos se envían sin verificar. Mientras una plataforma no esté configurada en el proyecto, el SDK deja de intentarlo durante ese arranque.

  • El simulador de iOS y los emuladores de Android nunca verifican.
  • Un dispositivo que el servidor rechaza (un teléfono rooteado, un bootloader desbloqueado, un certificado que el proyecto no tiene en su lista) envía eventos sin verificar; Android vuelve a intentarlo un día después.
  • Denegar el consentimiento borra el registro de la clave atestada en las dos plataformas.

Antes de hacer que el proyecto acepte solo eventos verificados de ios o android, comprueba en el explorador que los eventos de tus usuarios reales llegan verificados: los eventos de versiones antiguas, simuladores, emuladores y dispositivos rechazados se quedarían retenidos con un 425. Nunca pongas una clave de servidor (lyr_srv_...) en una app: cualquier cosa que vaya en una app se puede leer.

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

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 de Android
consentConsent.grantedpending, granted o denied
minimumLevelLogLevel.debugLos eventos por debajo se descartan antes de llegar a la cola del dispositivo
flushInterval15 sCada cuánto se ejecuta el envío en primer plano
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
maxEventAge7 díasLos eventos en cola más antiguos se descartan
sessionTimeout30 minTiempo de inactividad que inicia una sesión nueva
environmentdetectadoCualquier nombre válido, o null
platformel sistema operativoCualquier nombre válido, o null
redactedKeysnull: defaultRedactedKeysNombres de clave cuyos valores se ocultan; tu lista sustituye a la predeterminada, y una lista vacía desactiva la ocultación
captureErrorstrueRegistra los errores de Dart que nadie capturó
captureNativeCrashestrueiOS: crashes, bloqueos e informes de uso excesivo de MetricKit. Android: excepciones de la JVM no capturadas. Se envían en el siguiente arranque
attachScreentrueEtiqueta los eventos con la pantalla actual
attesttrueVerifica los eventos con App Attest o Key Attestation cuando el proyecto está configurado
mirrorToConsolefalseImprime además cada evento en el log nativo (la consola de Xcode, logcat)
pauseUploadsInLowPowerModetrueSolo iOS: los envíos periódicos se pausan; pasar a segundo plano sigue enviando

Entrega y límites

La entrega es la del SDK nativo, la misma que en una app de Swift o Kotlin:

iOSAndroid
Nunca bloqueaUna llamada pasa el evento al SDK nativo y vuelve; un único proceso de escritura en segundo plano lo pone en disco y nunca espera a la red.Igual.
Sobrevive a cierres forzados y a la falta de conexiónUna cola en Library/Caches, con un tope de 20 MB y 7 días. El sistema puede vaciar Caches cuando el dispositivo se queda sin espacio, y los eventos en espera se van con ello.Una cola en noBackupFilesDir/lyrelog, con un tope de 20 MB y 7 días, que 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 en primer plano (en pausa en el modo de bajo consumo), y cuando la app pasa a segundo plano, dentro de una background task.Cada 15 s mientras la Activity de la app está iniciada, y cuando 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.Igual.
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.Igual.
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. Un aviso en el unified log (subsistema com.lyrelog.sdk).Igual, con el aviso en logcat (etiqueta Lyrelog).
Los descartes se venLos eventos perdidos por los topes se convierten en un aviso lyrelog_events_dropped (área lyrelog) con el número.Igual.
Sus propios problemasUn endpoint incorrecto, una clave rechazada o líneas rechazadas se registran una vez por arranque en el unified log, subsistema com.lyrelog.sdk, a nivel debug.Igual, en logcat, etiqueta Lyrelog, a nivel debug.
ContextoId de la app, versión, build, sistema operativo, modelo de dispositivo (iPhone18,1), configuración regional, plataforma ios, id de sesión (nuevo tras 30 min de inactividad) e id de instalación. sdk es lyrelog-flutter/0.1.0 lyrelog-swift/0.1.0.Id de la app (el nombre del paquete), version name, version code, la versión de Android, el dispositivo (Google Pixel 9), configuración regional, plataforma android, id de sesión e id de instalación. sdk es lyrelog-flutter/0.1.0 lyrelog-android/0.1.0.
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.Igual.
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": "..."}.Igual.

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

Lyrelog.start(const LyrelogConfiguration(
  apiKey: 'lyr_ing_...',
  redactedKeys: [...LyrelogConfiguration.defaultRedactedKeys, 'pin'],
));

Privacidad en el App Store y seguridad de los datos en Play

El manifiesto de privacidad del SDK de Swift (PrivacyInfo.xcprivacy) va dentro de la app, y Xcode lo combina en el informe de privacidad de la app, como en la página de Swift.

Para la etiqueta de privacidad del App Store, declara lo que tu app envía a través de Lyrelog:

  • Diagnostics: Crash Data, Performance Data, Other Diagnostic Data (App Functionality).
  • Identifiers > Device ID: 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 (App Functionality). No está vinculado a la persona salvo que también llames a setUser.
  • Identifiers > User ID, vinculado a la persona: solo si llamas a setUser.
  • Usage Data > Product Interaction: si registras pantallas (screen_viewed) o toques.

Para el formulario de seguridad de los datos de Play Console:

  • 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, como arriba.
  • App activity > App interactions: si registras pantallas o toques.

En los dos, cualquier otra cosa que lleven tus attrs o tu payload (emails, compras...) va 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.