Swift
Strukturierte Logs aus deiner App für iOS, macOS, tvOS, watchOS oder visionOS. Ohne Abhängigkeiten.
Das Swift-SDK braucht iOS 16, macOS 13, tvOS 16, watchOS 9 oder visionOS 1 und Swift 6. Manche Funktionen hängen von der Plattform ab: siehe Plattformen.
Interne Vorschau: Dieses Paket ist noch nicht veröffentlicht. Bis dahin kann Xcode es nicht laden: Das Repository ist privat und hat noch kein Release.
Installation
Swift Package Manager. Wähle in Xcode File > Add Package Dependencies, gib
https://github.com/GonzaloFuentes28/lyrelog-swift ein und füge das Produkt Lyrelog zum Target
deiner App hinzu. In 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")]),
]Starten
Starte einmal, so früh wie möglich, zum Beispiel im init deiner App. Ein zweiter Aufruf wird
ignoriert. Events, die vor start geloggt werden, werden ebenfalls ignoriert, aber setUser und
setConsent, vor start aufgerufen, bleiben erhalten und werden angewendet, sobald es läuft.
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() } }
}Events gehen an https://ingest.lyrelog.com. Übergib endpoint nur, um sie woanders hinzuschicken.
Das ist die Basis-URL (ein eingefügter Pfad .../v1/events:batch wird entfernt) und muss https
sein; unverschlüsseltes http geht nur für localhost, 127.0.0.1 oder ::1. Mit jedem anderen
Endpoint wird nichts gesendet, und die Events bleiben auf dem Gerät.
Events loggen
Eine Funktion pro Level: trace, debug, info, notice, warning, error, critical, oder
log(_:_:) mit einem Level.
Lyrelog.info("checkout_done", attrs: ["items": 3, "latency_ms": .int(ms)])
Lyrelog.error("payment_declined", category: "checkout",
attrs: ["code": 51], payload: ["response": .string(raw)])Attribute und Payloads sind LogValues. Literale funktionieren direkt ("text", 412, 0.5,
true, ["a", "b"], verschachtelte Dictionaries, nil); für Variablen nutze die Cases (.int(ms),
.string(name), .double(x), .bool(flag)) oder LogValue(x). LogValue(duration) wandelt eine
Duration in Millisekunden um.
Wenn deine App einen eigenen Typ LogLevel hat, sprich den von Lyrelog als Lyrelog.Level an.
Logger für jeden Bereich
Ein Logger versieht jedes Event mit seiner category, wie Logger(category:) von OSLog. Er hat
jedes Level außer trace, dazu log und captureError.
let sync = Lyrelog.Logger(category: "sync")
sync.warning("sync_conflict", attrs: ["records": 2])Nutzer
Lyrelog.setUser(playerID) // attached to every following event
Lyrelog.setUser(nil) // on sign-outLyrelog.sessionID liefert die ID der aktuellen Session, zum Beispiel zum Anzeigen in einem
Support-Screen.
Die Nutzer-ID wird zwischen Starts nicht gespeichert: Rufe setUser bei jedem Start erneut auf,
sobald du weißt, wer die Person ist.
Screens
Sag, wo die Person gerade ist. Lyrelog loggt screen_viewed (Bereich navigation) mit dem
vorherigen Screen und den darauf verbrachten Sekunden und versieht jedes folgende Event mit einem
Attribut screen.
Lyrelog.screen("Settings") // anywhere
SettingsView().lyrelogScreen("Settings") // or in SwiftUI, on appearDas Event trägt screen, previous_screen und seconds_on_previous. Ein erneuter Aufruf von
screen mit demselben Namen loggt nichts. Beide Formen nehmen zusätzliche attrs für das Event
screen_viewed. Schalte das Taggen mit attachScreen: false ab.
Netzwerk-Requests
Requests werden zu Events http_request und http_request_failed im Bereich network, mit der
Methode, dem Host, einem Pfad, in dem IDs zu :id zusammengefasst sind, dem Status, der Dauer und
der Größe. Nie dabei: Query-String, Header und Body.
let (data, response) = try await URLSession.shared.loggedData(for: request)Wenn deine Pfade Dinge enthalten, die das Zusammenfassen nicht erkennt, übergib die Route selbst:
loggedData(for: request, route: "/players/:id/stats").
loggedData(for:route:category:) funktioniert mit jeder URLSession. Mit einem eigenen Client
erfasst du jeden Request selbst:
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 ist eine Swift-Duration: Miss sie mit ContinuousClock, wie oben.
bytes und category (Standard network) sind optional. 2xx und 3xx sind debug, 4xx warning,
5xx und Fehlschläge error (ein abgebrochener Request ist debug). Ein Fehlschlag trägt
error_domain und error_code.
Abgefangene Fehler
do {
try await store.purchase(product)
} catch {
Lyrelog.captureError(error, category: "store")
}Es sendet das Event exception, das jedes SDK sendet: Level error, die Attribute error_type
und error_message und eine Payload mit der Beschreibung, Domain und Code des NSError und dem
zugrunde liegenden Fehler. attrs: fügt eigene hinzu; level: ändert das Level. Jeder Logger
hat ebenfalls captureError.
Abstürze und Hänger
Abstürze und Hänger kommen von MetricKit (iOS, macOS, visionOS), standardmäßig an
(captureDiagnostics). iOS liefert sie beim nächsten Start aus, also wird jeder zu einem Event mit
dem Zeitstempel des Vorfalls, ohne Session, im Bereich diagnostics:
| Event | Level | Was es enthält |
|---|---|---|
app_crashed | critical | Exception, Signal, Beendigungsgrund, Version und Gerät, auf dem es passiert ist, der oberste Frame deiner App und bis zu 60 Frames in der Payload |
app_hung | error | Wie lange die App hing |
cpu_overuse | warning | |
disk_write_overuse | warning | |
slow_launch | warning |
Ein zweimal ausgelieferter Bericht wird einmal gespeichert. Frames sind Offsets in das jeweilige Binary,
keine Symbole: Symbolisiere sie mit dem dSYM, wenn du Namen brauchst. Jeder Frame lautet
MyApp +0x1a2b3c: das Binary und der Offset in seinen Code, und binary_images in der Payload
liefert die UUID jedes Binaries. Mit dem dSYM des abgestürzten Builds (Organizer in Xcode oder dein
Archiv) macht atos aus einem Offset Funktion, Datei und Zeile. Übergib die übliche Ladeadresse
des Binaries, 0x100000000 für eine App auf arm64, und diese Adresse plus den Offset:
atos -arch arm64 \
-o MyApp.app.dSYM/Contents/Resources/DWARF/MyApp \
-l 0x100000000 \
0x1001a2b3cPrüfe vorher, ob die UUID des dSYMs (dwarfdump --uuid MyApp.app.dSYM) mit der in
binary_images übereinstimmt.
Umgebungen und Plattform
Beim Start wählt das SDK die Umgebung:
developmentfür einen Debug-Build, jeden Build im Simulator oder einen Build mit eingebettetem Provisioning Profile (Development-, Ad-hoc- und Enterprise-Signierung);testflightfür einen Build mit einem Sandbox-App-Store-Beleg und ohne Profil;- sonst
production.
Danach fragt es im Hintergrund StoreKit (AppTransaction.shared.environment), ohne Dialog, und
Events, die nach der Antwort geloggt werden, tragen diese Antwort: xcode ist development,
sandbox ist testflight, production ist production. So lässt sich eine Mac-App aus
TestFlight erkennen. Offline oder abgemeldet bleibt die erste Antwort, und eine Mac-App gilt als
production, bis StoreKit antwortet.
Deine eigenen Läufe aus Xcode senden development, während das Dashboard mit production öffnet:
Wähle development in der oberen Leiste, um sie zu sehen.
Die Plattform ist das Betriebssystem (ios, macos, tvos, visionos; apple unter watchOS).
Beides lässt sich in der Konfiguration überschreiben:
Configuration(apiKey: key,
environment: isInternalTester ? "internal" : nil, // nil = detected
platform: nil)Lyrelog.detectedEnvironment ist die Antwort beim Start; await Lyrelog.detectEnvironment()
wartet zusätzlich auf StoreKit (bis zu 10 Sekunden). Jeder Name geht: Kleinbuchstaben, Ziffern,
- und _, bis zu 32 Zeichen. Anderer Text wird in einen gültigen Namen umgewandelt (Staging EU
wird zu staging-eu).
Plattformen
| iOS, iPadOS, visionOS | tvOS | macOS | watchOS | |
|---|---|---|---|---|
platform | ios, visionos | tvos | macos | apple |
| Sendet, wenn die App in den Hintergrund geht | Ja | Ja | Nein | Nein |
| Abstürze und Hänger (MetricKit) | Ja | Nein | Ja | Nein |
Ohne Senden im Hintergrund werden Events per Timer gesendet, solange die App läuft, und der Rest
geht beim nächsten Start raus, da die Warteschlange auf der Festplatte liegt. Unter watchOS ist os_name
unknown.
Einwilligung
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 behält Events auf dem Gerät, ohne sie zu senden. Ein Start mit consent: .denied
löscht die Installations-ID und alles, was von einem früheren Start noch in der Warteschlange
liegt, und zeichnet nichts auf.
Die Einwilligung wird zwischen Starts nicht gespeichert: Speichere die Entscheidung der Person
selbst und übergib sie jedes Mal an start.
Eine vollständige App
Starte mit der gespeicherten Einwilligung, setze die Person beim Anmelden und tagge Screens:
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)
}Flush und Stopp
Unter iOS, tvOS und visionOS löst der Wechsel in den Hintergrund bereits einen Flush aus (mit einem Background Task), du brauchst es also selten.
await Lyrelog.flush() // write everything to disk and try to send now
await Lyrelog.stop() // send what's queued (up to 2 seconds), then stopOhne await (aus synchronem Code) stoppt Lyrelog.stop() sofort und sendet nichts: Events, die
noch im Speicher sind, gehen verloren, und was auf der Festplatte in der Warteschlange lag, geht nach dem
nächsten start raus.
flush respektiert ein Retry-After, das der Server verlangt hat: Es sendet nicht früher.
Unter macOS sendest du den Rest beim Beenden der App, indem du das Beenden kurz aufhältst:
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 appDelegateIn Entwicklung und Tests
Rufe Lyrelog.start in Unit-Tests oder Previews nicht auf: Alles, was vor start geloggt wird,
wird ignoriert, also läuft der Rest deines Codes unverändert.
if ProcessInfo.processInfo.environment["XCTestConfigurationFilePath"] == nil {
Lyrelog.start(Configuration(apiKey: "lyr_ing_..."))
}mirrorToOSLog: true gibt jedes Event während der Arbeit zusätzlich in der Konsole von Xcode aus.
Verifizierte Events
Ein verifiziertes Event ist eines, das nicht von jemandem gesendet worden sein kann, der den öffentlichen Ingest-Schlüssel aus einer App oder einer Webseite kopiert hat. Was das beweist und was nicht, steht unter Verifizierte Events.
Auf einem echten iPhone, iPad oder einer Apple Watch beweist das SDK mit App Attest von Apple, dass
die Events von deiner echten App kommen, und Lyrelog speichert sie als verifiziert (verified_by
ist app_attest). Die Option appAttest ist standardmäßig true; sie braucht:
- Die Capability App Attest im Target der App (Signing & Capabilities), das Entitlement
com.apple.developer.devicecheck.appattest-environment. Setze es für App-Store- und TestFlight-Builds aufproduction; ohne diesen Wert nutzt Apple die Development-Umgebung. - Deine App ID, also Team ID, ein Punkt und die Bundle-ID (
ABCDE12345.com.example.app), in den Einstellungen des Projekts, Abschnitt Verifizierte Events aus deinen Apple-Apps. Solange sie nicht gesetzt ist, hört das SDK für diesen Start auf, es zu versuchen.
Das Senden wartet nie auf die Verifizierung: Batches gehen ohne Token raus, bis das Gerät eines hat, also kommen
die ersten Events einer frischen Installation unverifiziert an, ebenso Events, die gesendet werden, wenn
irgendetwas fehlschlägt. Gespeichert wird nur die ID des Schlüssels, im Schlüsselbund, und eine
verweigerte Einwilligung löscht sie. Schalte es mit appAttest: false ab.
Zum Prüfen öffne den Explorer: Wähle unter Filter Verified by und App Attest (die anderen Werte sind Server key und Not verified). Ein geöffnetes Event zeigt die Verifizierung unter Context in seiner Zeile Sender: Verified, App Attest oder Not verified, public key.
Macs (Apple bietet App Attest dort nicht an), der Simulator, App Extensions (außer unter watchOS) und Geräte ohne App Attest senden immer unverifizierte Events, selbst wenn alles eingerichtet ist: Der Ingest-Schlüssel ist öffentlich, also hätte jeder, der ihn hat, dasselbe senden können. Ein verifiziertes Event beweist, welche App es gesendet hat, nicht, dass sein Inhalt stimmt.
Unter Verifizierte Events steht, wer was verifiziert, und alles zum Tagesanteil.
Konfiguration
| Option | Standard | Bedeutung |
|---|---|---|
endpoint | https://ingest.lyrelog.com | Die Basis-URL; ein eingefügter Pfad /v1/... wird entfernt. Nur https, http nur für localhost |
apiKey | Pflicht | Der Ingest-Schlüssel des Projekts |
consent | .granted | .pending, .granted oder .denied |
minimumLevel | .debug | Events darunter erreichen nie die Festplatte |
mirrorToOSLog | false | Jedes Event zusätzlich ins Unified Log ausgeben (Console, Xcode) |
uploadInterval | 15 s | Wie oft der Uploader im Vordergrund aufwacht |
pauseUploadsInLowPowerMode | true | Regelmäßige Uploads pausieren; der Wechsel in den Hintergrund sendet trotzdem |
maxBatchBytes | 512 KiB | Ein Batch schließt bei dem Limit, das zuerst erreicht wird (zwischen 64 KiB und 4 MiB gehalten) |
maxBatchEvents | 500 | Höchstens 2.000 |
maxDiskBytes | 20 MB | Obergrenze für die Warteschlange auf der Festplatte, älteste zuerst |
maxEventAge | 7 Tage | Ältere Events in der Warteschlange werden verworfen |
sessionTimeout | 30 min | Inaktive Zeit, nach der eine neue Session beginnt |
storageDirectory | Library/Caches/lyrelog | Wo die Warteschlange liegt |
captureDiagnostics | true | MetricKit-Berichte zu Abstürzen, Hängern und Übernutzung |
attachScreen | true | Events mit dem aktuellen Screen taggen |
environment | erkannt | Jeder gültige Name oder nil |
platform | das Betriebssystem | Jeder gültige Name oder nil |
appAttest | true | Events auf unterstützten Geräten mit App Attest von Apple verifizieren |
Zustellung und Limits
| Blockiert nie | Loggen kopiert das Event und kehrt zurück; ein einzelner Writer im Hintergrund schreibt es auf die Festplatte. |
| Übersteht Beenden und Offline | Eine Warteschlange in Library/Caches, begrenzt auf 20 MB und 7 Tage. Das System kann Caches leeren, wenn auf dem Gerät der Platz knapp wird, und die wartenden Events gehen mit. |
| Batches | Bis zu 500 Events oder 512 KiB pro Request, mit gzip. Ein Event, das kodiert größer als 1 MiB ist, wird verworfen und gezählt. |
| Wiederholungen | 1 s, verdoppelt bis 5 min, mit Full Jitter, unter Beachtung von Retry-After. Jeder andere 4xx-Status verwirft den Batch, ein 3xx (eine Weiterleitung, nie verfolgt) verwirft ihn mit einer Warnung, und ein widerrufener Schlüssel (401, 403) stoppt das Senden bis zum nächsten Start. Ein Batch, an dem der Server immer wieder scheitert, während andere durchgehen, wandert nach hinten und wird dann verworfen. |
| Monatskontingent | Wenn eine Free-Organisation die Events ihres Monats verbraucht hat, antwortet der Server mit 429. Die Events bleiben in der Warteschlange auf der Festplatte und gehen raus, sobald der Server sie wieder annimmt, innerhalb der Obergrenzen von 20 MB und 7 Tagen. Das SDK loggt pro Kontingent-Stopp eine Warnung (Unified Log, Subsystem com.lyrelog.sdk). |
| Verluste sind sichtbar | Events, die durch die Obergrenzen verloren gehen, werden zu einer Warnung lyrelog_events_dropped (Bereich lyrelog) mit der Anzahl. |
| Eigene Probleme | Ein falscher Endpoint, ein abgelehnter Schlüssel oder abgelehnte Zeilen gehen einmal pro Start ins Unified Log, Subsystem com.lyrelog.sdk, auf Debug-Level (schalte in Console Include Debug Messages ein). |
| Kontext | App-ID, Version, Build, Betriebssystem, Gerätemodell (iPhone18,1), Locale, Session-ID und Installations-ID. |
| Secrets | Werte unter Schlüsseln, deren Name authorization, cookie, password, token, secret, apikey oder ein anderer Eintrag der gemeinsamen Liste ist oder darauf endet, werden zu "[redacted]", auf jeder Ebene, bevor etwas gekürzt wird. |
| Limits | Lange Strings werden an einer Zeichengrenze gekürzt, überzählige Attribute in lyrelog_dropped_attrs gezählt, Payloads über 64 KiB zusammengefasst als {"lyrelog_truncated": true, "bytes": N, "preview": "..."}. |
Ändere die Liste mit redactedKeys: Deine Liste ersetzt die Standardwerte, und [] schaltet das
Schwärzen ab. Um etwas hinzuzufügen:
Lyrelog.start(Configuration(
apiKey: "lyr_ing_...",
redactedKeys: Lyrelog.Configuration.defaultRedactedKeys + ["pin"]
))Privacy Manifest und App-Store-Datenschutz
Das Paket bringt ein Privacy Manifest mit (PrivacyInfo.xcprivacy), das Xcode in den
Datenschutzbericht deiner App übernimmt: kein Tracking, keine Tracking-Domains, die API für
Datei-Zeitstempel mit dem Grund C617.1 (die Warteschlange liest die Größe ihrer eigenen Dateien) und die
Daten, die es erhebt (Absturzdaten, Leistungsdaten, andere Diagnosedaten, eine Geräte-ID), nicht
mit der Person verknüpft und nicht für Tracking genutzt.
Gib für das Datenschutz-Label im App Store an, was deine App über Lyrelog sendet:
- Diagnostics: Crash Data, Performance Data, Other Diagnostic Data (App Functionality).
- Identifiers > Device ID: die Installations-ID, eine zufällige UUID, die nicht die
Werbe-ID ist, nicht gesichert wird und bei einer Verweigerung gelöscht wird (App Functionality).
Nicht mit der Person verknüpft, es sei denn, du rufst auch
setUserauf. - Identifiers > User ID, mit der Person verknüpft: nur, wenn du
setUseraufrufst. - Usage Data > Product Interaction: wenn du Screens (
screen_viewed) oder Taps loggst. - Alles andere, was deine
attrsoderpayloadenthalten (E-Mails, Käufe...), unter der jeweils passenden Kategorie.
Der Server ergänzt das Land der sendenden Adresse; die Adresse selbst wird nicht gespeichert.