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

Swift

Logs estructurados desde tu app de iOS, macOS, tvOS, watchOS o visionOS. Sin dependencias.

iOS, iPadOS, macOS, tvOS, watchOS, visionOS

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

Lyrelog.screen("Settings")                 // anywhere
SettingsView().lyrelogScreen("Settings")   // or in SwiftUI, on appear

El 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:

EventoNivelQué lleva
app_crashedcriticalExcepció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_hungerrorCuánto tiempo estuvo bloqueada
cpu_overusewarning
disk_write_overusewarning
slow_launchwarning

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 \
  0x1001a2b3c

Comprueba 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:

  • development para una build Debug, cualquier build en el simulador o una build con un provisioning profile incrustado (firma de desarrollo, ad hoc y enterprise);
  • testflight para una build con un recibo de App Store de sandbox y sin profile;
  • production en 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, visionOStvOSmacOSwatchOS
platformios, visionostvosmacosapple
Envía cuando la app pasa a segundo planoSíSíNoNo
Crashes y bloqueos (MetricKit)SíNoSí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.

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 stop

Sin 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 appDelegate

En 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 a production para 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ónPor defectoSignificado
endpointhttps://ingest.lyrelog.comLa URL base; si pegas una ruta /v1/..., se elimina. Solo https; http solo para localhost
apiKeyobligatoriaLa clave de ingesta del proyecto
consent.granted.pending, .granted o .denied
minimumLevel.debugLos eventos por debajo nunca llegan al disco
mirrorToOSLogfalseImprime además cada evento en el unified log (Console, Xcode)
uploadInterval15 sCada cuánto se despierta el envío en primer plano
pauseUploadsInLowPowerModetrueLos envíos periódicos se pausan; pasar a segundo plano sigue enviando
maxBatchBytes512 KiBUn lote se cierra en el primer límite que se alcance (se mantiene entre 64 KiB y 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
storageDirectoryLibrary/Caches/lyrelogDónde vive la cola
captureDiagnosticstrueCrashes, bloqueos e informes de uso excesivo de MetricKit
attachScreentrueEtiqueta los eventos con la pantalla actual
environmentdetectadoCualquier nombre válido, o nil
platformel sistema operativoCualquier nombre válido, o nil
appAttesttrueVerifica los eventos con App Attest de Apple en los dispositivos compatibles

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.
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.
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) 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 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 (unified log, subsistema com.lyrelog.sdk) cada vez que la cuota lo detiene.
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, 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).
ContextoId 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.
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 [] 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 attrs o tu payload (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.