Accès anticipéSur invitation, et les SDK ne sont pas encore publiés.Demander une invitation
Aller au contenu
Docs

Swift

Des logs structurés depuis votre app iOS, macOS, tvOS, watchOS ou visionOS. Sans dépendances.

iOS, iPadOS, macOS, tvOS, watchOS, visionOS

Le SDK Swift nécessite iOS 16, macOS 13, tvOS 16, watchOS 9 ou visionOS 1, et Swift 6. Certaines fonctionnalités dépendent de la plateforme : voir Plateformes.

Préversion interne : ce package n'est pas encore publié. D'ici là, Xcode ne peut pas le récupérer : le dépôt est privé et n'a encore aucune release.

Installation

Swift Package Manager. Dans Xcode, choisissez File > Add Package Dependencies, saisissez https://github.com/GonzaloFuentes28/lyrelog-swift et ajoutez le produit Lyrelog à la target de votre app. Dans 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")]),
]

Démarrage

Démarrez une seule fois, le plus tôt possible, par exemple dans l'init de votre App. Un second appel est ignoré. Les événements journalisés avant start sont ignorés eux aussi, mais setUser et setConsent appelés avant start sont conservés et appliqués au démarrage.

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() } }
}

Les événements partent vers https://ingest.lyrelog.com. Ne passez endpoint que pour les envoyer ailleurs. C'est l'URL de base (un chemin .../v1/events:batch collé est retiré) et elle doit être en https ; le http simple ne fonctionne que pour localhost, 127.0.0.1 ou ::1. Avec tout autre endpoint, rien n'est envoyé et les événements restent sur l'appareil.

Journaliser des événements

Une fonction par niveau : trace, debug, info, notice, warning, error, critical, ou log(_:_:) avec un niveau.

Lyrelog.info("checkout_done", attrs: ["items": 3, "latency_ms": .int(ms)])
Lyrelog.error("payment_declined", category: "checkout",
              attrs: ["code": 51], payload: ["response": .string(raw)])

Les attributs et les payloads sont des LogValue. Les littéraux fonctionnent directement ("text", 412, 0.5, true, ["a", "b"], dictionnaires imbriqués, nil) ; pour les variables, utilisez les cas (.int(ms), .string(name), .double(x), .bool(flag)) ou LogValue(x). LogValue(duration) convertit une Duration en millisecondes.

Si votre app a son propre type LogLevel, désignez celui de Lyrelog par Lyrelog.Level.

Un logger par domaine

Un logger appose sa category sur chaque événement, comme le Logger(category:) d'OSLog. Il a tous les niveaux sauf trace, plus log et captureError.

let sync = Lyrelog.Logger(category: "sync")
sync.warning("sync_conflict", attrs: ["records": 2])

Utilisateurs

Lyrelog.setUser(playerID)   // attached to every following event
Lyrelog.setUser(nil)        // on sign-out

Lyrelog.sessionID donne l'id de la session en cours, par exemple pour l'afficher dans un écran d'assistance.

L'id utilisateur n'est pas conservé d'un lancement à l'autre : appelez de nouveau setUser à chaque lancement, dès que vous savez de qui il s'agit.

Écrans

Indiquez où se trouve la personne. Lyrelog journalise screen_viewed (domaine navigation) avec l'écran précédent et les secondes passées dessus, et marque chaque événement suivant d'un attribut screen.

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

L'événement porte screen, previous_screen et seconds_on_previous. Rappeler screen avec le même nom ne journalise rien. Les deux formes acceptent des attrs supplémentaires pour l'événement screen_viewed. Désactivez le marquage avec attachScreen: false.

Requêtes réseau

Les requêtes deviennent des événements http_request et http_request_failed dans le domaine network, avec la méthode, l'hôte, un chemin dont les ids sont ramenés à :id, le statut, la durée et la taille. Jamais la query string, les headers ni le corps.

let (data, response) = try await URLSession.shared.loggedData(for: request)

Si vos chemins contiennent des éléments que cette normalisation ne sait pas reconnaître, passez la route vous-même : loggedData(for: request, route: "/players/:id/stats").

loggedData(for:route:category:) fonctionne avec n'importe quelle URLSession. Avec votre propre client, enregistrez chaque requête vous-même :

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 est une Duration Swift : mesurez-la avec ContinuousClock, comme ci-dessus.

bytes et category (par défaut network) sont facultatifs. Les 2xx et 3xx sont en debug, les 4xx en warning, les 5xx et les échecs en error (une requête annulée est en debug). Un échec porte error_domain et error_code.

Les erreurs que vous interceptez

do {
    try await store.purchase(product)
} catch {
    Lyrelog.captureError(error, category: "store")
}

Cela envoie l'événement exception qu'envoient tous les SDK : niveau error, les attributs error_type et error_message, et un payload avec la description, le domaine et le code de NSError, et l'erreur sous-jacente. attrs: ajoute les vôtres ; level: change le niveau. Chaque Logger a aussi captureError.

Plantages et blocages

Les plantages et les blocages viennent de MetricKit (iOS, macOS, visionOS), activé par défaut (captureDiagnostics). iOS les transmet au lancement suivant : chacun devient donc un événement daté du moment où il s'est produit, sans session, dans le domaine diagnostics :

ÉvénementNiveauCe qu'il contient
app_crashedcriticalException, signal, motif de terminaison, la version et l'appareil concernés, la première frame de votre app dans la pile, et jusqu'à 60 frames dans le payload
app_hungerrorLa durée du blocage
cpu_overusewarning
disk_write_overusewarning
slow_launchwarning

Un rapport livré deux fois n'est enregistré qu'une fois. Les frames sont des offsets dans chaque binaire, pas des symboles : symbolisez-les avec le dSYM quand vous avez besoin des noms. Chaque frame se lit MyApp +0x1a2b3c : le binaire et l'offset dans son code, et le champ binary_images du payload donne l'UUID de chaque binaire. Avec le dSYM du build qui a planté (l'Organizer de Xcode, ou votre archive), atos traduit un offset en fonction, fichier et ligne. Passez l'adresse de chargement habituelle du binaire, 0x100000000 pour une app sur arm64, et cette adresse plus l'offset :

atos -arch arm64 \
  -o MyApp.app.dSYM/Contents/Resources/DWARF/MyApp \
  -l 0x100000000 \
  0x1001a2b3c

Vérifiez d'abord que l'UUID du dSYM (dwarfdump --uuid MyApp.app.dSYM) correspond à celui de binary_images.

Environnements et plateforme

Au démarrage, le SDK choisit l'environnement :

  • development pour un build Debug, tout build sur le simulateur, ou un build avec un profil de provisionnement intégré (signature de développement, ad hoc et entreprise) ;
  • testflight pour un build avec un reçu App Store de sandbox et sans profil ;
  • production sinon.

Il interroge ensuite StoreKit en arrière-plan (AppTransaction.shared.environment), sans afficher d'invite, et les événements journalisés après sa réponse portent cette réponse : xcode donne development, sandbox donne testflight, production donne production. C'est ainsi qu'on reconnaît une app Mac installée depuis TestFlight. Hors ligne ou sans compte connecté, la première réponse reste, et une app Mac compte comme production tant que StoreKit n'a pas répondu.

Vos propres exécutions depuis Xcode envoient development, alors que le tableau de bord s'ouvre sur production : choisissez development dans la barre du haut pour les voir.

La plateforme est l'OS (ios, macos, tvos, visionos ; apple sur watchOS). Vous pouvez remplacer l'un ou l'autre dans la configuration :

Configuration(apiKey: key,
              environment: isInternalTester ? "internal" : nil,   // nil = detected
              platform: nil)

Lyrelog.detectedEnvironment est la réponse au démarrage ; await Lyrelog.detectEnvironment() attend aussi StoreKit (jusqu'à 10 secondes). N'importe quel nom convient : lettres minuscules, chiffres, - et _, jusqu'à 32 caractères. Tout autre texte est transformé en nom valide (Staging EU devient staging-eu).

Plateformes

iOS, iPadOS, visionOStvOSmacOSwatchOS
platformios, visionostvosmacosapple
Envoie quand l'app passe en arrière-planOuiOuiNonNon
Plantages et blocages (MetricKit)OuiNonOuiNon

Sans envoi au passage en arrière-plan, les événements partent au rythme du minuteur tant que l'app tourne, et ce qui reste part au lancement suivant, puisque la file est sur disque. Sur watchOS, os_name vaut 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 garde les événements sur l'appareil sans les envoyer. Démarrer avec consent: .denied supprime tout ce qui reste en file depuis un lancement précédent ainsi que l'id d'installation, et n'enregistre rien.

Le consentement n'est pas conservé d'un lancement à l'autre : stockez vous-même le choix de la personne et passez-le à start à chaque fois.

Une app complète

Démarrez avec le consentement stocké, définissez la personne quand elle se connecte et marquez les écrans :

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)
}

Vider la file et arrêter

Sur iOS, tvOS et visionOS, le passage en arrière-plan vide déjà la file (avec une tâche d'arrière-plan) : vous en aurez donc rarement besoin.

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

Sans await (depuis du code synchrone), Lyrelog.stop() s'arrête immédiatement et n'envoie rien : les événements encore en mémoire sont perdus, et ce qui était en file sur disque part après le prochain start.

flush respecte un Retry-After demandé par le serveur : il n'envoie pas plus tôt.

Sur macOS, envoyez ce qui reste quand l'app se ferme, en retardant un instant la fermeture :

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 développement et dans les tests

N'appelez pas Lyrelog.start dans les tests unitaires ni dans les previews : tout ce qui est journalisé avant start est ignoré, et le reste de votre code s'exécute sans changement.

if ProcessInfo.processInfo.environment["XCTestConfigurationFilePath"] == nil {
    Lyrelog.start(Configuration(apiKey: "lyr_ing_..."))
}

mirrorToOSLog: true affiche aussi chaque événement dans la console de Xcode pendant que vous travaillez.

Événements vérifiés

Un événement vérifié est un événement qui n'a pas pu être envoyé par quelqu'un ayant extrait la clé d'ingestion publique d'une app ou d'une page web. Ce que cela prouve, et ce que cela ne prouve pas, est expliqué dans Événements vérifiés.

Sur un vrai iPhone, iPad ou Apple Watch, le SDK prouve avec App Attest d'Apple que les événements viennent de votre app authentique, et Lyrelog les enregistre comme vérifiés (verified_by vaut app_attest). L'option appAttest vaut true par défaut ; elle nécessite :

  • La capability App Attest sur la target de l'app (Signing & Capabilities), c'est-à-dire l'entitlement com.apple.developer.devicecheck.appattest-environment. Réglez-le sur production pour les builds App Store et TestFlight ; sans cela, Apple utilise l'environnement de développement.
  • Votre App ID, c'est-à-dire le Team ID, un point et le bundle id (ABCDE12345.com.example.app), dans les réglages du projet, section Verified events from your Apple apps. Tant qu'il n'est pas renseigné, le SDK cesse d'essayer pour ce lancement.

L'envoi ne l'attend jamais : les lots partent sans token tant que l'appareil n'en a pas, si bien que les premiers événements d'une nouvelle installation arrivent non vérifiés, tout comme ceux envoyés chaque fois que quelque chose échoue. Seul l'id de la clé est conservé, dans le Keychain, et un refus du consentement le supprime. Désactivez-le avec appAttest: false.

Pour vérifier, ouvrez l'explorer : dans Filter, choisissez Verified by et App Attest (les autres valeurs sont Server key et Not verified). Un événement ouvert l'indique sous Context, sur sa ligne Sender : Verified, App Attest, ou Not verified, public key.

Les Mac (Apple n'y propose pas App Attest), le simulateur, les extensions d'app (sauf sur watchOS) et les appareils sans App Attest envoient toujours des événements non vérifiés, même si tout est configuré : la clé d'ingestion est publique, donc quiconque la détient aurait pu envoyer la même chose. Un événement vérifié prouve quelle app l'a envoyé, pas que ce qu'il dit est vrai.

Voir Événements vérifiés pour savoir qui vérifie quoi et pour le quota journalier.

Configuration

OptionPar défautSignification
endpointhttps://ingest.lyrelog.comL'URL de base ; un chemin /v1/... collé est retiré. https uniquement, http seulement pour localhost
apiKeyobligatoireLa clé d'ingestion du projet
consent.granted.pending, .granted ou .denied
minimumLevel.debugLes événements en dessous n'atteignent jamais le disque
mirrorToOSLogfalseAffiche aussi chaque événement dans le log unifié (Console, Xcode)
uploadInterval15 sLa fréquence de réveil de l'uploader au premier plan
pauseUploadsInLowPowerModetrueLes envois périodiques se mettent en pause ; le passage en arrière-plan envoie quand même
maxBatchBytes512 KiBUn lot se ferme à la première limite atteinte (maintenu entre 64 KiB et 4 MiB)
maxBatchEvents500Au plus 2 000
maxDiskBytes20 MBPlafond de la file sur disque, les plus anciens partent en premier
maxEventAge7 joursLes événements en file plus anciens sont abandonnés
sessionTimeout30 minLe temps d'inactivité qui ouvre une nouvelle session
storageDirectoryLibrary/Caches/lyrelogL'emplacement de la file
captureDiagnosticstruePlantages, blocages et rapports de surconsommation MetricKit
attachScreentrueMarque les événements avec l'écran en cours
environmentdétectéN'importe quel nom valide, ou nil
platforml'OSN'importe quel nom valide, ou nil
appAttesttrueVérifie les événements avec App Attest d'Apple sur les appareils compatibles

Livraison et limites

Ne bloque jamaisJournaliser copie l'événement et rend la main ; un unique writer en arrière-plan l'écrit sur disque.
Résiste aux arrêts forcés et au hors-ligneUne file dans Library/Caches, plafonnée à 20 MB et 7 jours. Le système peut purger Caches quand l'appareil manque d'espace, et les événements en attente partent avec.
LotsJusqu'à 500 événements ou 512 KiB par requête, compressés en gzip. Un événement de plus de 1 MiB une fois encodé est abandonné et compté.
Nouvelles tentatives1 s, doublé jusqu'à 5 min, avec full jitter, en respectant Retry-After. Tout autre 4xx abandonne le lot, un 3xx (une redirection, jamais suivie) l'abandonne avec un avertissement, et une clé révoquée (401, 403) arrête les envois jusqu'au lancement suivant. Un lot que le serveur continue de refuser alors que d'autres passent est remis en fin de file, puis abandonné.
Quota mensuelQuand une organisation Free a épuisé les événements de son mois, le serveur répond 429. Les événements restent dans la file sur disque et partent dès que le serveur les accepte de nouveau, dans les limites de 20 MB et de 7 jours. Le SDK journalise un avertissement (log unifié, sous-système com.lyrelog.sdk) à chaque arrêt dû au quota.
Les pertes sont visiblesLes événements perdus à cause des plafonds deviennent un avertissement lyrelog_events_dropped (domaine lyrelog) avec leur nombre.
Ses propres problèmesUn endpoint incorrect, une clé refusée ou des lignes rejetées sont signalés une fois par lancement dans le log unifié, sous-système com.lyrelog.sdk, au niveau debug (dans Console, activez Include Debug Messages).
ContexteIdentifiant de l'app, version, build, OS, modèle d'appareil (iPhone18,1), locale, id de session et id d'installation.
SecretsLes valeurs sous des clés dont le nom est ou se termine par authorization, cookie, password, token, secret, apikey et le reste de la liste commune deviennent "[redacted]", à toute profondeur, avant toute troncature.
LimitesLes chaînes longues sont coupées sur une limite de caractère, les attributs en trop comptés dans lyrelog_dropped_attrs, les payloads de plus de 64 KiB résumés en {"lyrelog_truncated": true, "bytes": N, "preview": "..."}.

Modifiez la liste avec redactedKeys : votre liste remplace celle par défaut, et [] désactive le masquage. Pour la compléter :

Lyrelog.start(Configuration(
    apiKey: "lyr_ing_...",
    redactedKeys: Lyrelog.Configuration.defaultRedactedKeys + ["pin"]
))

Manifeste de confidentialité et confidentialité sur l'App Store

Le package inclut un manifeste de confidentialité (PrivacyInfo.xcprivacy) que Xcode fusionne dans le rapport de confidentialité de votre app : aucun suivi, aucun domaine de suivi, l'API d'horodatage des fichiers avec le motif C617.1 (la file lit la taille de ses propres fichiers), et les données qu'il collecte (données de plantage, données de performance, autres données de diagnostic, un identifiant d'appareil), non liées à la personne et non utilisées pour le suivi.

Pour l'étiquette de confidentialité de l'App Store, déclarez ce que votre app envoie via Lyrelog :

  • Diagnostics : Crash Data, Performance Data, Other Diagnostic Data (App Functionality).
  • Identifiers > Device ID : l'id d'installation, un UUID aléatoire qui n'est pas l'identifiant publicitaire, n'est pas sauvegardé et est supprimé en cas de refus (App Functionality). Non lié à la personne, sauf si vous appelez aussi setUser.
  • Identifiers > User ID, lié à la personne : seulement si vous appelez setUser.
  • Usage Data > Product Interaction : si vous journalisez les écrans (screen_viewed) ou les appuis.
  • Tout ce que vos attrs ou votre payload contiennent d'autre (e-mails, achats...), dans sa propre catégorie.

Le serveur ajoute le pays de l'adresse d'envoi ; l'adresse elle-même n'est pas conservée.