Swift
Logs estructurados desde tu app de iOS, macOS, tvOS, watchOS o visionOS. Sin dependencias.
El SDK de Swift necesita iOS 16, macOS 13, tvOS 16, watchOS 9 o visionOS 1, y Swift 6. Algunas funciones dependen de la plataforma: consulta Plataformas.
Versión preliminar interna: este paquete aún no está publicado. Hasta que lo esté, Xcode no puede descargarlo: el repositorio es privado y todavía no tiene ninguna release.
Instalación
Swift Package Manager. En Xcode, elige File > Add Package Dependencies, introduce
https://github.com/GonzaloFuentes28/lyrelog-swift y añade el producto Lyrelog al target de tu
app. En Package.swift:
dependencies: [
.package(url: "https://github.com/GonzaloFuentes28/lyrelog-swift", from: "0.1.0"),
],
targets: [
.target(name: "MyApp", dependencies: [.product(name: "Lyrelog", package: "lyrelog-swift")]),
]Primeros pasos
Arranca el SDK una sola vez y lo antes posible, por ejemplo en el init de tu App. Una segunda
llamada 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 Lyrelog
@main
struct MyApp: App {
init() {
Lyrelog.start(Configuration(
apiKey: "lyr_ing_..." // ingest-only: it can append events, never read them
))
}
var body: some Scene { WindowGroup { ContentView() } }
}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. 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(_:_:) con un nivel.
Lyrelog.info("checkout_done", attrs: ["items": 3, "latency_ms": .int(ms)])
Lyrelog.error("payment_declined", category: "checkout",
attrs: ["code": 51], payload: ["response": .string(raw)])Los atributos y los payloads son LogValue. Los literales funcionan directamente ("text", 412,
0.5, true, ["a", "b"], diccionarios anidados, nil); para variables, usa los casos
(.int(ms), .string(name), .double(x), .bool(flag)) o LogValue(x). LogValue(duration)
convierte un Duration en milisegundos.
Si tu app tiene su propio tipo LogLevel, refiérete al de Lyrelog como Lyrelog.Level.
Loggers por área
Un logger pone su category en cada evento, como el Logger(category:) de OSLog. Tiene todos los
niveles salvo trace, además de log y captureError.
let sync = Lyrelog.Logger(category: "sync")
sync.warning("sync_conflict", attrs: ["records": 2])Usuarios
Lyrelog.setUser(playerID) // attached to every following event
Lyrelog.setUser(nil) // on sign-outLyrelog.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.
Lyrelog.screen("Settings") // anywhere
SettingsView().lyrelogScreen("Settings") // or in SwiftUI, on appearEl evento lleva screen, previous_screen y seconds_on_previous. Llamar a screen otra vez con
el mismo nombre no registra nada. Las dos formas aceptan attrs adicionales para el evento
screen_viewed. Desactiva el etiquetado con attachScreen: false.
Peticiones de red
Las peticiones se convierten en eventos http_request y http_request_failed en el área
network, con el método, el host, una ruta cuyos ids se reducen a :id, el estado, la duración y
el tamaño. Nunca la query string, los headers ni el cuerpo.
let (data, response) = try await URLSession.shared.loggedData(for: request)Si tus rutas llevan cosas que esa reducción no sabe reconocer, pasa tú la ruta:
loggedData(for: request, route: "/players/:id/stats").
loggedData(for:route:category:) funciona con cualquier URLSession. Con tu propio cliente,
registra tú cada petición:
let clock = ContinuousClock()
let start = clock.now
let (data, response) = try await myClient.send(request)
Lyrelog.Network.record(request, response: response, error: nil, duration: clock.now - start, bytes: data.count, route: "/orders/:id")duration es un Duration de Swift: mídelo con ContinuousClock, como arriba.
bytes y category (por defecto network) son opcionales. Los 2xx y 3xx son debug, los 4xx
warning, y los 5xx y los fallos error (una petición cancelada es debug). Un fallo lleva
error_domain y error_code.
Errores que capturas
do {
try await store.purchase(product)
} catch {
Lyrelog.captureError(error, category: "store")
}Envía el evento exception que envían todos los SDK: nivel error, los atributos error_type y
error_message, y un payload con la descripción, el dominio y el código de NSError y el error
subyacente. attrs: añade los tuyos; level: cambia el nivel. Cada Logger también tiene
captureError.
Crashes y bloqueos
Los crashes y los bloqueos llegan de MetricKit (iOS, macOS, visionOS), activado por defecto
(captureDiagnostics). iOS los entrega en el siguiente arranque, así que cada uno se convierte en
un evento con la hora en que ocurrió, sin sesión, en el área diagnostics:
| Evento | Nivel | Qué lleva |
|---|---|---|
app_crashed | critical | Excepción, señal, motivo de terminación, la versión y el dispositivo en que ocurrió, el frame superior de tu app y hasta 60 frames en el payload |
app_hung | error | Cuánto tiempo estuvo bloqueada |
cpu_overuse | warning | |
disk_write_overuse | warning | |
slow_launch | warning |
Un informe entregado dos veces se guarda una sola vez. Los frames son offsets dentro de cada
binario, no símbolos: simbolízalos con el dSYM cuando necesites los nombres. Cada frame se lee
MyApp +0x1a2b3c: el binario y el offset dentro de su código, y el binary_images del payload da
el UUID de cada binario. Con el dSYM de la build que sufrió el crash (el Organizer de Xcode o tu
archive), atos convierte un offset en la función, el archivo y la línea. Pásale la dirección de
carga habitual del binario, 0x100000000 para una app en arm64, y esa dirección más el offset:
atos -arch arm64 \
-o MyApp.app.dSYM/Contents/Resources/DWARF/MyApp \
-l 0x100000000 \
0x1001a2b3cComprueba primero que el UUID del dSYM (dwarfdump --uuid MyApp.app.dSYM) coincide con el de
binary_images.
Entornos y plataforma
Al arrancar, el SDK elige el entorno:
developmentpara una build Debug, cualquier build en el simulador o una build con un provisioning profile incrustado (firma de desarrollo, ad hoc y enterprise);testflightpara una build con un recibo de App Store de sandbox y sin profile;productionen cualquier otro caso.
Después pregunta a StoreKit en segundo plano (AppTransaction.shared.environment), sin mostrar
ningún aviso, y los eventos registrados después de su respuesta llevan esa respuesta: xcode es
development, sandbox es testflight y production es production. Así se distingue una app
de Mac que viene de TestFlight. Sin conexión o sin sesión iniciada, se queda la primera respuesta,
y una app de Mac cuenta como production hasta que StoreKit responde.
Tus propias ejecuciones desde Xcode 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, macos, tvos, visionos; apple en watchOS).
Puedes sobrescribir cualquiera de los dos en la configuración:
Configuration(apiKey: key,
environment: isInternalTester ? "internal" : nil, // nil = detected
platform: nil)Lyrelog.detectedEnvironment es la respuesta al arrancar; await Lyrelog.detectEnvironment()
espera también a StoreKit (hasta 10 segundos). 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).
Plataformas
| iOS, iPadOS, visionOS | tvOS | macOS | watchOS | |
|---|---|---|---|---|
platform | ios, visionos | tvos | macos | apple |
| Envía cuando la app pasa a segundo plano | Sí | Sí | No | No |
| Crashes y bloqueos (MetricKit) | Sí | No | Sí | No |
Sin envío en segundo plano, los eventos se envían con el temporizador mientras la app está en
marcha, y lo que queda sale en el siguiente arranque, porque la cola está en disco. En watchOS,
os_name es unknown.
Consentimiento
Lyrelog.start(Configuration(apiKey: key, consent: .pending))
// later, when the person chooses:
Lyrelog.setConsent(.granted) // sends, including what was kept while pending
Lyrelog.setConsent(.denied) // deletes everything and stops recording.pending guarda los eventos en el dispositivo sin enviarlos. 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.
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 Lyrelog
import SwiftUI
@main
struct MyApp: App {
init() {
let consent: Lyrelog.Consent = switch UserDefaults.standard.string(forKey: "diagnostics") {
case "granted": .granted
case "denied": .denied
default: .pending
}
Lyrelog.start(Configuration(apiKey: "lyr_ing_...", consent: consent))
}
var body: some Scene {
WindowGroup { RootView() }
}
}
struct RootView: View {
@State private var account: Account?
var body: some View {
Group {
if let account {
HomeView(account: account).lyrelogScreen("Home")
} else {
SignInView { signedIn in
account = signedIn
Lyrelog.setUser(signedIn.id)
Lyrelog.info("signed_in", category: "auth")
}
.lyrelogScreen("Sign in")
}
}
}
}
func choose(_ allowed: Bool) {
UserDefaults.standard.set(allowed ? "granted" : "denied", forKey: "diagnostics")
Lyrelog.setConsent(allowed ? .granted : .denied)
}Vaciar la cola y detener
En iOS, tvOS y visionOS, pasar a segundo plano ya vacía la cola (con una background task), así que rara vez te hará falta.
await Lyrelog.flush() // write everything to disk and try to send now
await Lyrelog.stop() // send what's queued (up to 2 seconds), then stopSin await (desde código síncrono), Lyrelog.stop() se detiene en el acto y no envía nada: los
eventos que siguen en memoria se pierden, y lo que estaba en la cola en disco sale después del
siguiente start.
flush respeta el Retry-After que haya pedido el servidor: no envía antes.
En macOS, envía lo que quede cuando la app se cierra reteniendo el cierre un momento:
final class AppDelegate: NSObject, NSApplicationDelegate {
func applicationShouldTerminate(_ sender: NSApplication) -> NSApplication.TerminateReply {
Task {
await Lyrelog.stop() // sends what's queued, up to 2 seconds
sender.reply(toApplicationShouldTerminate: true)
}
return .terminateLater
}
}
// In your App: @NSApplicationDelegateAdaptor(AppDelegate.self) var appDelegateEn desarrollo y en tests
No llames a Lyrelog.start en los tests unitarios ni en las previews: todo lo que se registra
antes de start se ignora, así que el resto de tu código se ejecuta sin cambios.
if ProcessInfo.processInfo.environment["XCTestConfigurationFilePath"] == nil {
Lyrelog.start(Configuration(apiKey: "lyr_ing_..."))
}Con mirrorToOSLog: true, además, cada evento se imprime en la consola de Xcode mientras
trabajas.
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.
En un iPhone, iPad o Apple Watch real, el SDK demuestra con App Attest de Apple que los eventos
vienen de tu app auténtica, y Lyrelog los guarda como verificados (verified_by es
app_attest). La opción appAttest es true por defecto; necesita:
- La capability App Attest en el target de la app (Signing & Capabilities), el entitlement
com.apple.developer.devicecheck.appattest-environment. Ponlo aproductionpara las builds de App Store y TestFlight; sin él, Apple usa el entorno de desarrollo. - Tu App ID, es decir, el Team ID, un punto y el bundle id (
ABCDE12345.com.example.app), en los ajustes del proyecto, sección Verified events from your Apple apps. Mientras no esté configurado, el SDK deja de intentarlo durante ese arranque.
El envío nunca espera a App Attest: los lotes salen sin token hasta que el dispositivo tiene uno, así que
los primeros eventos de una instalación nueva llegan sin verificar, igual que los que se envían
cada vez que algo falla. Solo se guarda el id de la clave, en el Keychain, y si se deniega el
consentimiento se borra. Desactívalo con appAttest: false.
Para comprobarlo, abre el explorador: en Filter, elige Verified by y App Attest (los otros valores son Server key y Not verified). Un evento abierto lo indica en Context, en su línea Sender: Verified, App Attest o Not verified, public key.
Los Mac (Apple no ofrece App Attest allí), el simulador, las extensiones de app (salvo en watchOS) y los dispositivos sin App Attest siempre envían eventos sin verificar, aunque todo esté configurado: la clave de ingesta es pública, así que cualquiera que la tenga podría haber enviado lo mismo. Un evento verificado demuestra qué app lo envió, no que lo que dice sea cierto.
Consulta Eventos verificados para saber quién verifica qué y cómo funciona la cuota diaria.
Configuración
| Opción | Por defecto | Significado |
|---|---|---|
endpoint | https://ingest.lyrelog.com | La URL base; si pegas una ruta /v1/..., se elimina. Solo https; http solo para localhost |
apiKey | obligatoria | La clave de ingesta del proyecto |
consent | .granted | .pending, .granted o .denied |
minimumLevel | .debug | Los eventos por debajo nunca llegan al disco |
mirrorToOSLog | false | Imprime además cada evento en el unified log (Console, Xcode) |
uploadInterval | 15 s | Cada cuánto se despierta el envío en primer plano |
pauseUploadsInLowPowerMode | true | Los envíos periódicos se pausan; pasar a segundo plano sigue enviando |
maxBatchBytes | 512 KiB | Un lote se cierra en el primer límite que se alcance (se mantiene entre 64 KiB y 4 MiB) |
maxBatchEvents | 500 | Como máximo 2.000 |
maxDiskBytes | 20 MB | Tope de la cola en disco; se descartan primero los más antiguos |
maxEventAge | 7 días | Los eventos en cola más antiguos se descartan |
sessionTimeout | 30 min | Tiempo de inactividad que inicia una sesión nueva |
storageDirectory | Library/Caches/lyrelog | Dónde vive la cola |
captureDiagnostics | true | Crashes, bloqueos e informes de uso excesivo de MetricKit |
attachScreen | true | Etiqueta los eventos con la pantalla actual |
environment | detectado | Cualquier nombre válido, o nil |
platform | el sistema operativo | Cualquier nombre válido, o nil |
appAttest | true | Verifica los eventos con App Attest de Apple en los dispositivos compatibles |
Entrega y límites
| Nunca bloquea | Al registrar, el SDK copia el evento y vuelve; un único proceso de escritura en segundo plano lo pone en disco. |
| Sobrevive a cierres forzados y a la falta de conexión | Una 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. |
| Lotes | Hasta 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. |
| Reintentos | 1 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) lo descarta con un aviso, y una clave revocada (401, 403) detiene los envíos hasta el siguiente arranque. Un lote que el servidor sigue rechazando mientras otros pasan se manda al final de la cola y después se descarta. |
| Cuota mensual | Cuando 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 (unified log, subsistema com.lyrelog.sdk) cada vez que la cuota lo detiene. |
| Los descartes se ven | Los eventos perdidos por los topes se convierten en un aviso lyrelog_events_dropped (área lyrelog) con el número. |
| Sus propios problemas | Un 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 (en Console, activa Include Debug Messages). |
| Contexto | Id de la app, versión, build, sistema operativo, modelo de dispositivo (iPhone18,1), configuración regional, id de sesión e id de instalación. |
| Secretos | Los 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ímites | Las 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 [] desactiva la
ocultación. Para ampliarla:
Lyrelog.start(Configuration(
apiKey: "lyr_ing_...",
redactedKeys: Lyrelog.Configuration.defaultRedactedKeys + ["pin"]
))Manifiesto de privacidad y privacidad en el App Store
El paquete incluye un manifiesto de privacidad (PrivacyInfo.xcprivacy) que Xcode combina en el
informe de privacidad de tu app: sin tracking, sin dominios de tracking, la API de marcas de tiempo
de archivos con el motivo C617.1 (la cola lee el tamaño de sus propios archivos) y los datos que
recoge (datos de crashes, datos de rendimiento, otros datos de diagnóstico, un id de dispositivo),
no vinculados a la persona y no usados para tracking.
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. - Cualquier otra cosa que lleven tus
attrso tupayload(emails, compras...), en su propia categoría.
El servidor añade el país de la dirección que envía; la propia dirección no se guarda.