Swift
Des logs structurés depuis votre app iOS, macOS, tvOS, watchOS ou visionOS. Sans dépendances.
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-outLyrelog.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 appearL'é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énement | Niveau | Ce qu'il contient |
|---|---|---|
app_crashed | critical | Exception, 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_hung | error | La durée du blocage |
cpu_overuse | warning | |
disk_write_overuse | warning | |
slow_launch | warning |
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 \
0x1001a2b3cVé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 :
developmentpour 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) ;testflightpour un build avec un reçu App Store de sandbox et sans profil ;productionsinon.
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, visionOS | tvOS | macOS | watchOS | |
|---|---|---|---|---|
platform | ios, visionos | tvos | macos | apple |
| Envoie quand l'app passe en arrière-plan | Oui | Oui | Non | Non |
| Plantages et blocages (MetricKit) | Oui | Non | Oui | Non |
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.
Consentement
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 stopSans 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 appDelegateEn 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 surproductionpour 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
| Option | Par défaut | Signification |
|---|---|---|
endpoint | https://ingest.lyrelog.com | L'URL de base ; un chemin /v1/... collé est retiré. https uniquement, http seulement pour localhost |
apiKey | obligatoire | La clé d'ingestion du projet |
consent | .granted | .pending, .granted ou .denied |
minimumLevel | .debug | Les événements en dessous n'atteignent jamais le disque |
mirrorToOSLog | false | Affiche aussi chaque événement dans le log unifié (Console, Xcode) |
uploadInterval | 15 s | La fréquence de réveil de l'uploader au premier plan |
pauseUploadsInLowPowerMode | true | Les envois périodiques se mettent en pause ; le passage en arrière-plan envoie quand même |
maxBatchBytes | 512 KiB | Un lot se ferme à la première limite atteinte (maintenu entre 64 KiB et 4 MiB) |
maxBatchEvents | 500 | Au plus 2 000 |
maxDiskBytes | 20 MB | Plafond de la file sur disque, les plus anciens partent en premier |
maxEventAge | 7 jours | Les événements en file plus anciens sont abandonnés |
sessionTimeout | 30 min | Le temps d'inactivité qui ouvre une nouvelle session |
storageDirectory | Library/Caches/lyrelog | L'emplacement de la file |
captureDiagnostics | true | Plantages, blocages et rapports de surconsommation MetricKit |
attachScreen | true | Marque les événements avec l'écran en cours |
environment | détecté | N'importe quel nom valide, ou nil |
platform | l'OS | N'importe quel nom valide, ou nil |
appAttest | true | Vérifie les événements avec App Attest d'Apple sur les appareils compatibles |
Livraison et limites
| Ne bloque jamais | Journaliser 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-ligne | Une 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. |
| Lots | Jusqu'à 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 tentatives | 1 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 mensuel | Quand 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 visibles | Les événements perdus à cause des plafonds deviennent un avertissement lyrelog_events_dropped (domaine lyrelog) avec leur nombre. |
| Ses propres problèmes | Un 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). |
| Contexte | Identifiant de l'app, version, build, OS, modèle d'appareil (iPhone18,1), locale, id de session et id d'installation. |
| Secrets | Les 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. |
| Limites | Les 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
attrsou votrepayloadcontiennent 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.