Early AccessNur auf Einladung, und die SDKs sind noch nicht veröffentlicht.Einladung anfragen
Zum Inhalt springen
Docs

Swift

Strukturierte Logs aus deiner App für iOS, macOS, tvOS, watchOS oder visionOS. Ohne Abhängigkeiten.

iOS, iPadOS, macOS, tvOS, watchOS, visionOS

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

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

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

EventLevelWas es enthält
app_crashedcriticalException, 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_hungerrorWie lange die App hing
cpu_overusewarning
disk_write_overusewarning
slow_launchwarning

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

Prü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:

  • development für einen Debug-Build, jeden Build im Simulator oder einen Build mit eingebettetem Provisioning Profile (Development-, Ad-hoc- und Enterprise-Signierung);
  • testflight fü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, visionOStvOSmacOSwatchOS
platformios, visionostvosmacosapple
Sendet, wenn die App in den Hintergrund gehtJaJaNeinNein
Abstürze und Hänger (MetricKit)JaNeinJaNein

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.

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 stop

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

In 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 auf production; 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

OptionStandardBedeutung
endpointhttps://ingest.lyrelog.comDie Basis-URL; ein eingefügter Pfad /v1/... wird entfernt. Nur https, http nur für localhost
apiKeyPflichtDer Ingest-Schlüssel des Projekts
consent.granted.pending, .granted oder .denied
minimumLevel.debugEvents darunter erreichen nie die Festplatte
mirrorToOSLogfalseJedes Event zusätzlich ins Unified Log ausgeben (Console, Xcode)
uploadInterval15 sWie oft der Uploader im Vordergrund aufwacht
pauseUploadsInLowPowerModetrueRegelmäßige Uploads pausieren; der Wechsel in den Hintergrund sendet trotzdem
maxBatchBytes512 KiBEin Batch schließt bei dem Limit, das zuerst erreicht wird (zwischen 64 KiB und 4 MiB gehalten)
maxBatchEvents500Höchstens 2.000
maxDiskBytes20 MBObergrenze für die Warteschlange auf der Festplatte, älteste zuerst
maxEventAge7 TageÄltere Events in der Warteschlange werden verworfen
sessionTimeout30 minInaktive Zeit, nach der eine neue Session beginnt
storageDirectoryLibrary/Caches/lyrelogWo die Warteschlange liegt
captureDiagnosticstrueMetricKit-Berichte zu Abstürzen, Hängern und Übernutzung
attachScreentrueEvents mit dem aktuellen Screen taggen
environmenterkanntJeder gültige Name oder nil
platformdas BetriebssystemJeder gültige Name oder nil
appAttesttrueEvents auf unterstützten Geräten mit App Attest von Apple verifizieren

Zustellung und Limits

Blockiert nieLoggen kopiert das Event und kehrt zurück; ein einzelner Writer im Hintergrund schreibt es auf die Festplatte.
Übersteht Beenden und OfflineEine 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.
BatchesBis 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.
Wiederholungen1 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.
MonatskontingentWenn 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 sichtbarEvents, die durch die Obergrenzen verloren gehen, werden zu einer Warnung lyrelog_events_dropped (Bereich lyrelog) mit der Anzahl.
Eigene ProblemeEin 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).
KontextApp-ID, Version, Build, Betriebssystem, Gerätemodell (iPhone18,1), Locale, Session-ID und Installations-ID.
SecretsWerte 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.
LimitsLange 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 setUser auf.
  • Identifiers > User ID, mit der Person verknüpft: nur, wenn du setUser aufrufst.
  • Usage Data > Product Interaction: wenn du Screens (screen_viewed) oder Taps loggst.
  • Alles andere, was deine attrs oder payload enthalten (E-Mails, Käufe...), unter der jeweils passenden Kategorie.

Der Server ergänzt das Land der sendenden Adresse; die Adresse selbst wird nicht gespeichert.