Swift
为你的 iOS、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-outLyrelog.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_crashed | critical | 异常、信号、终止原因、发生时的版本和设备、你应用中的栈顶帧,以及 payload 中最多 60 个栈帧 |
app_hung | error | 卡顿了多久 |
cpu_overuse | warning | |
disk_write_overuse | warning | |
slow_launch | warning |
同一份报告交付两次只会保存一次。栈帧是各个二进制文件内的偏移量,而不是符号:需要函数名时,用 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、visionOS | tvOS | macOS | watchOS | |
|---|---|---|---|---|
platform | ios、visionos | tvos | macos | apple |
| 应用进入后台时发送 | 是 | 是 | 否 | 否 |
| 崩溃和卡顿(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 的设备,即使一切都已设置好,发送的也始终是未验证事件:采集密钥是公开的,任何持有它的人都可能发出同样的事件。已验证事件证明的是哪个应用发送了它,而不是它的内容属实。
谁验证什么,以及每日配额,见已验证事件。
配置
| 选项 | 默认值 | 含义 |
|---|---|---|
endpoint | https://ingest.lyrelog.com | 基础 URL;粘贴进来的 /v1/... 路径会被去掉。只能用 https,http 仅限 localhost |
apiKey | 必填 | 项目的采集密钥 |
consent | .granted | .pending、.granted 或 .denied |
minimumLevel | .debug | 低于该级别的事件永远不会写入磁盘 |
mirrorToOSLog | false | 同时把每个事件打印到统一日志(Console 应用、Xcode) |
uploadInterval | 15 s | 前台时上传器多久唤醒一次 |
pauseUploadsInLowPowerMode | true | 暂停定期上传;进入后台时仍然会发送 |
maxBatchBytes | 512 KiB | 批次达到任一限制时即关闭(取值范围 64 KiB 到 4 MiB) |
maxBatchEvents | 500 | 最多 2,000 |
maxDiskBytes | 20 MB | 磁盘队列的上限,最旧的先丢弃 |
maxEventAge | 7 天 | 队列中更旧的事件会被丢弃 |
sessionTimeout | 30 min | 空闲多久后开始新会话 |
storageDirectory | Library/Caches/lyrelog | 队列存放的位置 |
captureDiagnostics | true | MetricKit 的崩溃、卡顿和资源过度使用报告 |
attachScreen | true | 给事件打上当前页面的标签 |
environment | 自动检测 | 任何合法名称,或 nil |
platform | 操作系统 | 任何合法名称,或 nil |
appAttest | true | 在支持的设备上用 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携带的其他任何数据(电子邮件、购买记录...),归入各自的类别。
服务器会添加发送地址所在的国家;地址本身不会保存。