抢先体验仅限邀请,SDK 尚未发布。申请邀请
跳到正文
文档

Swift

为你的 iOS、macOS、tvOS、watchOS 或 visionOS 应用提供结构化日志。无任何依赖。

iOS、iPadOS、macOS、tvOS、watchOS、visionOS

Swift SDK 需要 iOS 16、macOS 13、tvOS 16、watchOS 9 或 visionOS 1,以及 Swift 6。部分功能取决于平台:见平台。

内部预览:这个包还没有发布。在发布之前,Xcode 无法拉取它:仓库是私有的,也还没有任何 release。

安装

使用 Swift Package Manager。在 Xcode 中选择 File > Add Package Dependencies,输入 https://github.com/GonzaloFuentes28/lyrelog-swift,然后把 product Lyrelog 添加到你应用的 target。在 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")]),
]

启动

只启动一次,越早越好,例如在你的 App 的 init 中。第二次调用会被忽略。在 start 之前记录的事件同样会被忽略,但在 start 之前调用的 setUser 和 setConsent 会被保留,并在启动时生效。

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

事件发送到 https://ingest.lyrelog.com。只有要发送到其他地方时才需要传 endpoint。它是基础 URL(粘贴进来的 .../v1/events:batch 路径会被去掉),并且必须是 https;普通 http 只适用于 localhost、127.0.0.1 或 ::1。如果是其他 endpoint,什么都不会发送,事件会留在设备上。

记录事件

每个级别一个函数:trace、debug、info、notice、warning、error、critical,或者带级别参数的 log(_:_:)。

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

属性和 payload 都是 LogValue。字面量可以直接使用("text"、412、0.5、true、["a", "b"]、嵌套字典、nil);变量则使用对应的 case(.int(ms)、.string(name)、.double(x)、.bool(flag))或 LogValue(x)。LogValue(duration) 会把 Duration 转换为毫秒。

如果你的应用有自己的 LogLevel 类型,请用 Lyrelog.Level 来指代 Lyrelog 的级别类型。

按分类使用 logger

logger 会在每个事件上打上它的 category,就像 OSLog 的 Logger(category:)。除了 trace 之外,它有所有级别,外加 log 和 captureError。

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

用户

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

Lyrelog.sessionID 返回当前的会话 id,例如可以显示在客服支持页面上。

用户 id 不会在两次启动之间保存:每次启动时,一旦知道用户是谁,就再调用一次 setUser。

页面

告诉 Lyrelog 用户当前在哪个页面。Lyrelog 会记录 screen_viewed(分类 navigation),带上前一个页面,以及在该页面停留的秒数,并给之后的每个事件打上 screen 属性。

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

该事件携带 screen、previous_screen 和 seconds_on_previous。用相同的名字再次调用 screen 不会记录任何内容。两种写法都可以为 screen_viewed 事件传入额外的 attrs。用 attachScreen: false 可以关闭这种标记。

网络请求

请求会变成 network 分类中的 http_request 和 http_request_failed 事件,包含请求方法、主机、路径(其中的 id 会被归并为 :id)、状态码、耗时和大小。绝不包含 query string、header 或请求体。

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

如果你的路径中有归并规则识别不了的内容,可以自己传入路由: loggedData(for: request, route: "/players/:id/stats")。

loggedData(for:route:category:) 适用于任何 URLSession。如果用的是你自己的客户端,就自己记录每个请求:

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 是 Swift 的 Duration:像上面那样用 ContinuousClock 来测量。

bytes 和 category(默认 network)是可选的。2xx 和 3xx 记为 debug,4xx 记为 warning,5xx 和失败记为 error(被取消的请求记为 debug)。失败时会带上 error_domain 和 error_code。

你捕获的错误

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

它发送的是每个 SDK 都会发送的 exception 事件:级别为 error,带有属性 error_type 和 error_message,payload 中包含错误描述、NSError 的 domain 和 code,以及底层错误。attrs: 用于添加你自己的属性;level: 用于修改级别。每个 Logger 也都有 captureError。

崩溃和卡顿

崩溃和卡顿来自 MetricKit(iOS、macOS、visionOS),默认开启(captureDiagnostics)。iOS 会在下次启动时交付这些报告,所以每一份都会变成一个事件,时间是它发生的时间,没有会话,位于 diagnostics 分类:

事件级别携带的内容
app_crashedcritical异常、信号、终止原因、发生时的版本和设备、你应用中的栈顶帧,以及 payload 中最多 60 个栈帧
app_hungerror卡顿了多久
cpu_overusewarning
disk_write_overusewarning
slow_launchwarning

同一份报告交付两次只会保存一次。栈帧是各个二进制文件内的偏移量,而不是符号:需要函数名时,用 dSYM 做符号化。每个栈帧的形式是 MyApp +0x1a2b3c:二进制文件名和它代码内的偏移量,payload 中的 binary_images 给出每个二进制文件的 UUID。有了崩溃那个构建的 dSYM(来自 Xcode 的 Organizer 或你的归档),atos 就能把偏移量转换成函数、文件和行号。传入二进制文件通常的加载地址(arm64 上的应用是 0x100000000),以及该地址加上偏移量的值:

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

先确认 dSYM 的 UUID(dwarfdump --uuid MyApp.app.dSYM)与 binary_images 中的一致。

环境和平台

启动时,SDK 会选择环境:

  • development:Debug 构建、模拟器上的任何构建,或嵌入了 provisioning profile 的构建(development、ad hoc 和 enterprise 签名);
  • testflight:带有 sandbox App Store 收据且没有 profile 的构建;
  • production:其他情况。

然后它会在后台询问 StoreKit(AppTransaction.shared.environment),不会弹出任何提示,之后记录的事件都会采用这个结果:xcode 对应 development,sandbox 对应 testflight,production 对应 production。来自 TestFlight 的 Mac 应用就是这样区分出来的。离线或未登录时,保留最初的判断,而 Mac 应用在 StoreKit 回应之前都算作 production。

你自己从 Xcode 运行时发送的是 development,而控制台默认打开 production:在顶部栏选择 development 才能看到它们。

平台就是操作系统(ios、macos、tvos、visionos;watchOS 上为 apple)。两者都可以在配置中覆盖:

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

Lyrelog.detectedEnvironment 是启动时的判断结果;await Lyrelog.detectEnvironment() 还会等待 StoreKit 的回应(最多 10 秒)。任何名字都可以:小写字母、数字、- 和 _,最多 32 个字符。其他文本会被转换成合法的名字(Staging EU 变成 staging-eu)。

平台

iOS、iPadOS、visionOStvOSmacOSwatchOS
platformios、visionostvosmacosapple
应用进入后台时发送是是否否
崩溃和卡顿(MetricKit)是否是否

没有后台发送时,事件会在应用运行期间按定时器发送,剩下的在下次启动时发出,因为队列保存在磁盘上。在 watchOS 上,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 会把事件保留在设备上而不发送。以 consent: .denied 启动时,会删除之前启动遗留在队列中的所有内容以及安装 id,并且不记录任何内容。

同意状态不会在两次启动之间保存:请自己保存用户的选择,并在每次调用 start 时传入。

完整的应用示例

用保存的同意状态启动,在用户登录时设置用户,并给页面打标签:

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)和停止

在 iOS、tvOS 和 visionOS 上,进入后台时已经会自动发送(通过后台任务),所以你很少需要手动立即发送。

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

不带 await(在同步代码中)时,Lyrelog.stop() 会立即停止,什么都不发送:仍在内存中的事件会丢失,已经排在磁盘队列里的会在下次 start 之后发出。

flush 会遵守服务器要求的 Retry-After:不会提前发送。

在 macOS 上,可以在应用退出时稍微推迟一下退出,把剩下的事件发出去:

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

开发和测试中

不要在单元测试或预览中调用 Lyrelog.start:在 start 之前记录的任何内容都会被忽略,所以其余代码照常运行,无需改动。

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

开发时,mirrorToOSLog: true 还会把每个事件打印到 Xcode 的 console。

已验证事件

已验证事件是别人伪造不了的事件:即使有人从应用或网页里复制了公开的采集密钥,也发不出这样的事件。它能证明什么、不能证明什么,见已验证事件。

在真实的 iPhone、iPad 或 Apple Watch 上,SDK 会用 Apple 的 App Attest 证明事件来自你的正版应用,Lyrelog 会把它们保存为已验证事件(verified_by 为 app_attest)。选项 appAttest 默认为 true;它需要:

  • 应用 target 上的 App Attest capability(Signing & Capabilities),即 entitlement com.apple.developer.devicecheck.appattest-environment。App Store 和 TestFlight 构建请设为 production;不设置时 Apple 使用开发环境。
  • 你的 App ID,即 Team ID、一个点号和 bundle id(ABCDE12345.com.example.app),填写在项目设置的 Verified events from your Apple apps 部分。没有设置时,SDK 会在本次启动期间停止尝试。

发送不会等待它:在设备拿到 token 之前,批次不带 token 发送,所以全新安装后最初的事件到达时是未验证的,任何环节出错时发送的事件也是如此。只有密钥的 id 会保存在 Keychain 中,拒绝同意时会将其删除。用 appAttest: false 关闭。

要确认是否生效,打开事件浏览器:在 Filter 中选择 Verified by 和 App Attest(其他值为 Server key 和 Not verified)。打开一个事件,在 Context 下的 Sender 一行会显示:Verified, App Attest 或 Not verified, public key。

Mac(Apple 在 Mac 上不提供 App Attest)、模拟器、app extension(watchOS 除外)以及不支持 App Attest 的设备,即使一切都已设置好,发送的也始终是未验证事件:采集密钥是公开的,任何持有它的人都可能发出同样的事件。已验证事件证明的是哪个应用发送了它,而不是它的内容属实。

谁验证什么,以及每日配额,见已验证事件。

配置

选项默认值含义
endpointhttps://ingest.lyrelog.com基础 URL;粘贴进来的 /v1/... 路径会被去掉。只能用 https,http 仅限 localhost
apiKey必填项目的采集密钥
consent.granted.pending、.granted 或 .denied
minimumLevel.debug低于该级别的事件永远不会写入磁盘
mirrorToOSLogfalse同时把每个事件打印到统一日志(Console 应用、Xcode)
uploadInterval15 s前台时上传器多久唤醒一次
pauseUploadsInLowPowerModetrue暂停定期上传;进入后台时仍然会发送
maxBatchBytes512 KiB批次达到任一限制时即关闭(取值范围 64 KiB 到 4 MiB)
maxBatchEvents500最多 2,000
maxDiskBytes20 MB磁盘队列的上限,最旧的先丢弃
maxEventAge7 天队列中更旧的事件会被丢弃
sessionTimeout30 min空闲多久后开始新会话
storageDirectoryLibrary/Caches/lyrelog队列存放的位置
captureDiagnosticstrueMetricKit 的崩溃、卡顿和资源过度使用报告
attachScreentrue给事件打上当前页面的标签
environment自动检测任何合法名称,或 nil
platform操作系统任何合法名称,或 nil
appAttesttrue在支持的设备上用 Apple 的 App Attest 验证事件

投递和限制

从不阻塞记录日志只复制事件就返回;由一个后台写入器把它写入磁盘。
进程被杀和离线时不丢失队列位于 Library/Caches,上限为 20 MB 和 7 天。设备空间不足时,系统可能会清理 Caches,等待中的事件也会随之丢失。
批量发送每个请求最多 500 个事件或 512 KiB,gzip 压缩。编码后超过 1 MiB 的事件会被丢弃并计数。
重试从 1 s 开始翻倍,最长 5 min,采用 full jitter,遵守 Retry-After。其他任何 4xx 会丢弃批次,3xx(重定向,从不跟随)会丢弃批次并给出警告,已撤销的密钥(401、403)会在下次启动前停止发送。如果某个批次一直失败而其他批次都能发送成功,它会被移到队尾,之后被丢弃。
月度配额Free 组织用完当月事件数后,服务器返回 429。事件会留在磁盘队列中,等服务器再次接收时发出,但仍受 20 MB 和 7 天的上限约束。每次因配额停止发送,SDK 都会记录一条警告(统一日志,subsystem 为 com.lyrelog.sdk)。
丢弃有迹可查因上限而丢失的事件会汇总成一条 lyrelog_events_dropped 警告(分类 lyrelog),附带数量。
SDK 自身的问题endpoint 写错、密钥被拒绝或有行被拒绝时,每次启动会向统一日志记录一次,subsystem 为 com.lyrelog.sdk,debug 级别(在 Console 应用中打开 Include Debug Messages)。
上下文应用 id、版本、构建号、操作系统、设备型号(iPhone18,1)、区域设置、会话 id 和安装 id。
敏感信息名称等于或以 authorization、cookie、password、token、secret、apikey 以及共享列表中其余词结尾的键,其值会在任意深度、在任何截断之前变成 "[redacted]"。
限制长字符串在字符边界处截断,多出的属性计入 lyrelog_dropped_attrs,超过 64 KiB 的 payload 会被概括为 {"lyrelog_truncated": true, "bytes": N, "preview": "..."}。

用 redactedKeys 修改这个列表:你的列表会替换默认值,[] 则关闭脱敏。要在默认值上追加:

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

隐私清单和 App Store 隐私信息

这个包附带一份隐私清单(PrivacyInfo.xcprivacy),Xcode 会把它合并到你应用的隐私报告中:不跟踪、没有跟踪域名、使用文件时间戳 API 且理由为 C617.1(队列读取它自己文件的大小),以及它收集的数据(崩溃数据、性能数据、其他诊断数据、设备 id),这些数据不与用户关联,也不用于跟踪。

填写 App Store 隐私标签时,声明你的应用通过 Lyrelog 发送了哪些数据:

  • Diagnostics: Crash Data、Performance Data、Other Diagnostic Data(App Functionality)。
  • Identifiers > Device ID: 安装 id,一个随机 UUID,不是广告标识符,不会被备份,拒绝同意时会被删除(App Functionality)。除非你还调用了 setUser,否则不与用户关联。
  • Identifiers > User ID,与用户关联:仅当你调用 setUser 时。
  • Usage Data > Product Interaction: 如果你记录页面(screen_viewed)或点击。
  • 你的 attrs 或 payload 携带的其他任何数据(电子邮件、购买记录...),归入各自的类别。

服务器会添加发送地址所在的国家;地址本身不会保存。