Flutter
为你在 iOS 和 Android 上的 Flutter 应用提供结构化日志,基于 Lyrelog 原生 SDK。
Flutter SDK 是 Dart 包 lyrelog,一个支持 iOS 16 和 Android 7.0(API 24)及更高版本的插件,用 Flutter 3.50 构建。它是原生 SDK 之上的一层轻量 Dart 封装,iOS 上是 Swift SDK,Android 上是 Android SDK,因此磁盘队列、原生崩溃、后台发送、会话、同意和已验证事件的行为都与原生 SDK 一致。在此之上,它还会上报没人捕获的 Dart 错误,并根据你的 navigator 为页面命名。
内部预览:这个包还没有发布。在发布之前,flutter pub add lyrelog 什么也找不到:它不在 pub.dev 上,仓库是私有的,也还没有任何 release。
安装
flutter pub add lyrelog或者在 pubspec.yaml 中:
dependencies:
lyrelog: ^0.1.0iOS 配置
- 这个插件是一个 Swift 包,所以你的应用会用 Swift Package Manager 构建它,而 Flutter 默认就使用 Swift Package Manager。没有 CocoaPods 版本。
- 把应用的最低版本设为 iOS 16:在 Xcode 中选择 Runner target,General,Minimum Deployments(
IPHONEOS_DEPLOYMENT_TARGET = 16.0)。Flutter 的默认值更低,构建会停止并给出相应提示。
Android 配置
- Flutter 的默认设置即可满足要求:compileSdk 36 和 Kotlin 2.2 或更新版本。
minSdk可以保持为 24。
这个库会在你应用的 manifest 中添加 INTERNET 权限。
启动
只启动一次,越早越好:放在 main 中、runApp 之前。运行期间的第二次调用会被忽略。start 会自己调用 WidgetsFlutterBinding.ensureInitialized(),所以可以放在最前面,也不需要等待它完成:在 start 之后记录的内容会在它之后到达原生 SDK。在 start 之前记录的事件会被忽略,但在 start 之前调用的 setUser 和 setConsent 会被保留,并在启动时生效。
import 'package:flutter/widgets.dart';
import 'package:lyrelog/lyrelog.dart';
void main() {
Lyrelog.start(const LyrelogConfiguration(
apiKey: 'lyr_ing_...', // ingest-only: it can append events, never read them
));
runApp(const MyApp());
}事件发送到 https://ingest.lyrelog.com。只有要发送到其他地方时才需要传 endpoint。它是基础 URL(粘贴进来的 .../v1/events:batch 路径会被去掉),并且必须是 https;普通 http 只适用于 localhost、127.0.0.1 或 ::1,以及 Android 模拟器上的 10.0.2.2(见开发和测试中)。如果是其他 endpoint,什么都不会发送,事件会留在设备上。
记录事件
每个级别一个函数:trace、debug、info、notice、warning、error、critical,或者带 LogLevel 参数的 log(level, message, ...)。
Lyrelog.info('checkout_done', attrs: {'items': 3, 'latency_ms': ms});
Lyrelog.error('payment_declined', category: 'checkout',
attrs: {'code': 51}, payload: {'response': raw});属性是一个 Map<String, Object?>:字符串、数字、布尔值、null、列表以及最多 4 层的嵌套 map。DateTime 会作为 ISO 8601 文本发送,Duration 作为毫秒数,枚举作为它的名称,其他任何值则作为它的 toString()。payload 可以是上述任意类型的值,用来放那些只有打开单个事件时才会看的细节。
按分类使用 logger
logger 会在每个事件上打上它的 category,就像日志的 tag。它有所有级别,外加 log 和 captureError。创建和持有它的开销都很小,调用时会写入当时正在运行的 SDK。
final sync = Lyrelog.logger('sync');
sync.warning('sync_conflict', attrs: {'records': 2});用户
Lyrelog.setUser(account.id); // attached to every following event
Lyrelog.setUser(null); // on sign-outawait Lyrelog.sessionId() 返回当前的会话 id,例如可以显示在客服支持页面上。
用户 id 不会在两次启动之间保存:每次启动时,一旦知道用户是谁,就再调用一次 setUser。
页面
告诉 Lyrelog 用户当前在哪个页面。Lyrelog 会记录 screen_viewed(分类 navigation),带上前一个页面,以及在该页面停留的秒数,并给之后的每个事件打上 screen 属性。
把 LyrelogNavigatorObserver 加到应用的 navigator 上,每个来到栈顶的页面路由都会被当作一个页面,以其路由名命名:
MaterialApp(
navigatorObservers: [LyrelogNavigatorObserver()],
routes: {
'/': (_) => const HomePage(),
'/settings': (_) => const SettingsPage(),
},
)它适用于任何 Navigator,所以也适用于接受 observer 的路由库(使用 go_router 时为 GoRouter(observers: [LyrelogNavigatorObserver()], ...))。返回到某个页面时会再记录一次,因为它又成了当前页面。对话框、底部弹出面板和菜单不会改变当前页面,没有名字的路由会被跳过。这两点都可以修改:
LyrelogNavigatorObserver(
nameExtractor: (settings) => settings.name?.replaceFirst('/', ''), // null or '' skips the route
routeFilter: (route) => route is PageRoute, // which routes are screens
)或者自己调用:
Lyrelog.screen('Settings');该事件携带 screen、previous_screen 和 seconds_on_previous。用相同的名字再次调用 screen 不会记录任何内容。screen 可以为 screen_viewed 事件传入额外的 attrs。用 attachScreen: false 可以关闭这种标记。
你捕获的错误
try {
await store.purchase(product);
} catch (e, s) {
Lyrelog.captureError(e, stackTrace: s, category: 'store');
}它发送的是每个 SDK 都会发送的 exception 事件:级别为 error,带有属性 error_type(运行时类型)和 error_message(它的 toString()),payload 中包含错误描述以及调用栈中最多 60 个栈帧。不传 stackTrace 时,如果是 Error 且自带调用栈,就使用它自己的栈帧。attrs 用于添加你自己的属性;level 用于修改级别。每个 logger 也都有 captureError。
错误和崩溃
没人捕获的 Dart 错误
start 会自动上报它们(captureErrors,默认开启),作为带有 handled: false 的 exception 事件,mechanism 说明 Flutter 是在哪里把它们交出来的:
mechanism | 来源 | payload 中还包含 |
|---|---|---|
flutter_error | FlutterError.onError:构建、布局或绘制 widget 时的错误,以及手势回调中的错误 | library(widgets library)和 context(building MyWidget) |
platform_dispatcher | PlatformDispatcher.instance.onError:异步代码、定时器以及没人 await 的 future 中的错误 |
原有的 handler 会继续运行,在 Lyrelog 的之后执行,而 PlatformDispatcher.onError 的返回值与之前那个 handler 的返回值相同(如果之前没有,Flutter 仍会打印该错误)。如果你要设置自己的 handler,请在 start 之前设置,或者在其中调用 captureError。
这类错误每分钟最多发送 10 个,同一个错误(类型、消息和栈顶帧都相同)每 10 秒最多发送一次,所以每一帧都重复出现的布局错误只会发送一个事件。Flutter 标记为 silent 的错误(它在 release 构建中也不会报告,例如图片加载失败)会被略过。
Dart 错误不会让 Flutter 应用终止,所以它们是 exception 事件,永远不会是 app_crashed。
如果你的应用运行在自己的 zone 中,用同样的方式上报 zone 的错误:
runZonedGuarded(() => runApp(const MyApp()), (error, stack) {
Lyrelog.captureError(error, stackTrace: stack, handled: false, mechanism: 'zone');
});原生崩溃
应用本身的崩溃来自原生 SDK(captureNativeCrashes,默认开启)。它们在下次启动时发送,时间是它们发生的时间,位于 diagnostics 分类:
| 平台 | 事件 | 来源 |
|---|---|---|
| iOS | app_crashed(critical)、app_hung(error)、cpu_overuse、disk_write_overuse、slow_launch(warning) | MetricKit,与 Swift 页面所述相同 |
| Android | app_crashed(critical),带有 handled: false 和 mechanism: uncaught_exception | 未捕获的 JVM 异常,与 Android 页面所述相同 |
在 Android 上,原生(C 或 C++)崩溃和 ANR 不会上报。
混淆构建
使用 flutter build --obfuscate --split-debug-info=<dir> 时,error_type 中的类型名和栈帧都会被混淆。请保留构建生成的符号文件,并用它们对栈帧运行 flutter symbolize 来还原。
环境和平台
原生 SDK 在启动时选择环境:
- iOS:debug 构建、模拟器上的任何构建,或嵌入了 provisioning profile 的构建(development 和 ad hoc 签名)为
development;TestFlight 构建为testflight;其他情况为production。之后再采用 StoreKit 的回应,与 Swift 页面所述相同。 - Android:应用可调试时(所有 debug 构建)为
development,其他情况为production。
你自己用 flutter run 运行的构建发送的是 development,而控制台默认打开 production:在顶部栏选择 development 才能看到它们。
平台就是操作系统,ios 或 android,所以一个项目可以同时容纳两者,控制台也可以按平台筛选。两者都可以在配置中覆盖:
LyrelogConfiguration(
apiKey: key,
environment: isInternalTester ? 'internal' : null, // null = detected
platform: null,
)任何名字都可以:小写字母、数字、- 和 _,最多 32 个字符。其他文本会被转换成合法的名字(Staging EU 变成 staging-eu)。
同意
Lyrelog.start(LyrelogConfiguration(apiKey: key, consent: Consent.pending));
// later, when the person chooses:
Lyrelog.setConsent(Consent.granted); // sends, including what was kept while pending
Lyrelog.setConsent(Consent.denied); // deletes everything and stops recordingConsent.pending 会把事件保留在设备上而不发送。除非已获得同意,否则什么都不会上传,包括之前启动遗留下来的内容。以 Consent.denied 启动时,会删除之前启动遗留在队列中的所有内容以及安装 id,并且不记录任何内容。在 start 之前调用的 setConsent 优先于配置中的 consent。
同意状态不会在两次启动之间保存:请自己保存用户的选择,并在每次调用 start 时传入。
完整的应用示例
用保存的同意状态启动,在用户登录时设置用户,并通过 navigator 为页面命名:
import 'package:flutter/material.dart';
import 'package:lyrelog/lyrelog.dart';
import 'package:shared_preferences/shared_preferences.dart';
Future<void> main() async {
WidgetsFlutterBinding.ensureInitialized();
final prefs = await SharedPreferences.getInstance();
final consent = switch (prefs.getString('diagnostics')) {
'granted' => Consent.granted,
'denied' => Consent.denied,
_ => Consent.pending,
};
Lyrelog.start(LyrelogConfiguration(apiKey: 'lyr_ing_...', consent: consent));
runApp(const MyApp());
}
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) => MaterialApp(
navigatorObservers: [LyrelogNavigatorObserver()],
routes: {
'/': (_) => const HomePage(),
'/sign-in': (_) => SignInPage(onSignedIn: signedIn),
},
);
}
void signedIn(Account account) {
Lyrelog.setUser(account.id);
Lyrelog.info('signed_in', category: 'auth');
}
Future<void> choose(bool allowed) async {
final prefs = await SharedPreferences.getInstance();
await prefs.setString('diagnostics', allowed ? 'granted' : 'denied');
Lyrelog.setConsent(allowed ? Consent.granted : Consent.denied);
}立即发送(flush)和停止
进入后台时已经会自动发送:iOS 上在后台任务中发送,Android 上在应用的 Activity 停止时发送。所以你很少需要手动立即发送。
await Lyrelog.flush(); // write everything to disk and send, waiting up to 5 seconds
await Lyrelog.stop(); // send what's queued (up to 2 seconds), then stopflush 在时限内完成时返回 true(timeout: 可以修改等待时间),并且会遵守服务器要求的 Retry-After:不会提前发送。调用 stop 之后,可以再次调用 start。
开发和测试中
在 widget 测试和单元测试中,不要调用 Lyrelog.start:在 start 之前记录的任何内容都会被忽略,所以其余代码照常运行,无需改动。在插件不支持的平台(Web、桌面)上,所有调用都不做任何事,也从不抛出异常。
开发时,mirrorToConsole: true 还会把每个事件打印到原生日志:iOS 上是 Xcode 的 console,Android 上是 logcat(tag 为 Lyrelog)。
debug 构建发送的环境是 development。要发送到运行在你电脑上的 endpoint:
- iOS 模拟器:使用
http://127.0.0.1加上端口。模拟器与你的电脑共用网络,也不需要为它添加 App Transport Security 例外。 - Android 模拟器:使用
http://10.0.2.2加上端口(在模拟器看来,10.0.2.2就是你的电脑),并且只在 debug 构建中这样做:- 允许向
10.0.2.2发送明文 http。 除非应用明确允许,否则 Android 会阻止它:在 debug 构建(android/app/src/debug)中添加一份 network security config,只对这一个地址允许明文流量。 - 在 Android 17 上,target 为 API 37 的应用还需要
ACCESS_LOCAL_NETWORK才能访问10.0.2.2这样的私有地址;没有它,连接只会超时。在 debug manifest(android/app/src/debug/AndroidManifest.xml)中声明该权限并授予它:adb shell pm grant <your.app> android.permission.ACCESS_LOCAL_NETWORK。
- 允许向
用 --dart-define-from-file 把密钥放在源代码之外,例如
flutter run --dart-define-from-file=lyrelog.local.json 配合
String.fromEnvironment('LYRELOG_KEY'),并让 git 忽略那个文件。
这些只用于本地开发。托管的采集服务是一个公网 https 地址,以上这些都不需要。
已验证事件
已验证事件是别人伪造不了的事件:即使有人从应用或网页里复制了公开的采集密钥,也发不出这样的事件。它能证明什么、不能证明什么,见已验证事件。
原生 SDK 会在真实设备上验证应用(attest,默认开启),你的 Dart 代码无需任何改动。为应用发布的每个平台分别完成设置:
- iOS,使用 Apple 的 App Attest(
verified_by为app_attest):- 在 Xcode 中为 Runner target 添加 App Attest capability(Signing & Capabilities),即 entitlement
com.apple.developer.devicecheck.appattest-environment。App Store 和 TestFlight 构建请设为production;不设置时 Apple 使用开发环境。 - 在项目设置的 Verified events from your Apple apps 部分,添加你的 App ID,即 Team ID、一个点号和 bundle id(
ABCDE12345.com.example.app)。
- 在 Xcode 中为 Runner target 添加 App Attest capability(Signing & Capabilities),即 entitlement
- Android,使用 Key Attestation(
verified_by为key_attestation):在项目设置的 Verified events from your Android apps 部分,添加你的包名,以及每个为发送事件的构建签名的证书的 SHA-256 指纹:Play 的应用签名密钥(Play Console 中的 Test and release、App integrity),以及你自己签名的构建所用的证书(在应用的android文件夹中运行./gradlew signingReport显示的那个)。
要在两个平台上都关闭它:
Lyrelog.start(const LyrelogConfiguration(apiKey: 'lyr_ing_...', attest: false));发送不会等待它:在应用拿到 token 之前,以及任何环节出错时,事件都以未验证的形式发送。某个平台还没在项目中设置好时,SDK 会在本次启动期间停止尝试。
- iOS 模拟器和 Android 模拟器永远无法通过验证。
- 被服务器拒绝的设备(已 root 的手机、已解锁的 bootloader、项目未列出的证书)会发送未验证事件;Android 会在一天后再试。
- 拒绝同意会在两个平台上删除已做过 attestation 的密钥的记录。
在把项目设置为只接受来自 ios 或 android 的已验证事件之前,请先在事件浏览器中确认你真实用户的事件到达时是已验证的:来自旧版本、iOS 模拟器、Android 模拟器和被拒绝设备的事件会因 425 而被挡住。永远不要把服务器密钥(lyr_srv_...)放进应用:应用中的任何内容都可以被读取。
要确认是否生效,打开事件浏览器:打开一个事件,在 Context 下的 Sender 一行会显示:Verified, App Attest、Verified, Key Attestation 或 Not verified, public key。
配置
| 选项 | 默认值 | 含义 |
|---|---|---|
apiKey | 必填 | 项目的采集密钥 |
endpoint | https://ingest.lyrelog.com | 基础 URL;粘贴进来的 /v1/... 路径会被去掉。只能用 https,http 仅限 localhost 和 Android 模拟器的 10.0.2.2 |
consent | Consent.granted | pending、granted 或 denied |
minimumLevel | LogLevel.debug | 低于该级别的事件在进入设备队列之前就会被丢弃 |
flushInterval | 15 s | 前台时上传器多久运行一次 |
maxBatchBytes | 512 KiB | 批次达到任一限制时即关闭(不超过 4 MiB) |
maxBatchEvents | 500 | 最多 2,000 |
maxDiskBytes | 20 MB | 磁盘队列的上限,最旧的先丢弃 |
maxEventAge | 7 天 | 队列中更旧的事件会被丢弃 |
sessionTimeout | 30 min | 空闲多久后开始新会话 |
environment | 自动检测 | 任何合法名称,或 null |
platform | 操作系统 | 任何合法名称,或 null |
redactedKeys | null:即 defaultRedactedKeys | 需要脱敏的键名;你的列表会替换默认值,空列表则关闭脱敏 |
captureErrors | true | 上报没人捕获的 Dart 错误 |
captureNativeCrashes | true | iOS:MetricKit 的崩溃、卡顿和资源过度使用报告。Android:未捕获的 JVM 异常。在下次启动时发送 |
attachScreen | true | 给事件打上当前页面的标签 |
attest | true | 项目设置好后,用 App Attest 或 Key Attestation 验证事件 |
mirrorToConsole | false | 同时把每个事件打印到原生日志(Xcode 的 console、logcat) |
pauseUploadsInLowPowerMode | true | 仅限 iOS:暂停定期上传;进入后台时仍然会发送 |
投递和限制
投递由原生 SDK 负责,与 Swift 或 Kotlin 应用中完全相同:
| iOS | Android | |
|---|---|---|
| 从不阻塞 | 调用只把事件交给原生 SDK 就返回;由一个后台写入器把它写入磁盘,并且从不等待网络。 | 相同。 |
| 进程被杀和离线时不丢失 | 队列位于 Library/Caches,上限为 20 MB 和 7 天。设备空间不足时,系统可能会清理 Caches,等待中的事件也会随之丢失。 | 队列位于 noBackupFilesDir/lyrelog,上限为 20 MB 和 7 天,永远不会被备份,所以恢复后的手机不会重发另一台设备的事件。 |
| 何时发送 | 前台时每 15 s 发送一次(低电量模式下暂停),应用进入后台时在后台任务中发送。 | 应用的 Activity 处于 started 状态时每 15 s 发送一次,进入后台时再发送一次。在后台时不会按定时器运行:剩下的事件会在下次启动或应用下次回到前台时发出。 |
| 批量发送 | 每个请求最多 500 个事件或 512 KiB,gzip 压缩。编码后超过 1 MiB 的事件会被丢弃并计数。 | 相同。 |
| 重试 | 从 1 s 开始翻倍,最长 5 min,采用 full jitter,遵守 Retry-After。其他任何 4xx 会丢弃批次,3xx(重定向,从不跟随)也会丢弃批次,已撤销的密钥(401、403)会在下次启动前停止发送,但保留事件。如果某个批次一直失败而其他批次都能发送成功,它会被移到队尾,之后被丢弃。 | 相同。 |
| 月度配额 | Free 组织用完当月事件数后,服务器返回 429。事件会留在磁盘队列中,等服务器再次接收时发出,但仍受 20 MB 和 7 天的上限约束。在统一日志中记录一条警告(subsystem 为 com.lyrelog.sdk)。 | 相同,警告记录在 logcat 中(tag 为 Lyrelog)。 |
| 丢弃有迹可查 | 因上限而丢失的事件会汇总成一条 lyrelog_events_dropped 警告(分类 lyrelog),附带数量。 | 相同。 |
| SDK 自身的问题 | endpoint 写错、密钥被拒绝或有行被拒绝时,每次启动会向统一日志记录一次,subsystem 为 com.lyrelog.sdk,debug 级别。 | 相同,记录在 logcat 中,tag 为 Lyrelog,debug 级别。 |
| 上下文 | 应用 id、版本、构建号、操作系统、设备型号(iPhone18,1)、区域设置、平台 ios、会话 id(空闲 30 min 后更新)和安装 id。sdk 为 lyrelog-flutter/0.1.0 lyrelog-swift/0.1.0。 | 应用 id(包名)、版本名、版本号、Android 版本、设备(Google Pixel 9)、区域设置、平台 android、会话 id 和安装 id。sdk 为 lyrelog-flutter/0.1.0 lyrelog-android/0.1.0。 |
| 敏感信息 | 名称等于或以 authorization、cookie、password、token、secret、apikey 以及共享列表中其余词结尾的键,其值会在任意深度、在任何截断之前变成 "[redacted]"。 | 相同。 |
| 限制 | 长字符串在字符边界处截断,多出的属性计入 lyrelog_dropped_attrs,超过 64 KiB 的 payload 会被概括为 {"lyrelog_truncated": true, "bytes": N, "preview": "..."}。 | 相同。 |
用 redactedKeys 修改脱敏列表:你的列表会替换默认值,空列表则关闭脱敏。要在默认值上追加:
Lyrelog.start(const LyrelogConfiguration(
apiKey: 'lyr_ing_...',
redactedKeys: [...LyrelogConfiguration.defaultRedactedKeys, 'pin'],
));App Store 隐私信息和 Play 数据安全
Swift SDK 的隐私清单(PrivacyInfo.xcprivacy)随应用一起发布,Xcode 会把它合并到应用的隐私报告中,与 Swift 页面所述相同。
填写 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)或点击。
填写 Play Console 的数据安全表单时:
- App info and performance: Crash logs、Diagnostics(App functionality;如果你这样使用,还有 Analytics)。收集,不共享。
- Device or other IDs: 安装 id,同上。
- App activity > App interactions: 如果你记录页面或点击。
在这两个平台上,你的 attrs 或 payload 携带的其他任何数据(电子邮件、购买记录...)都归入各自的类别。数据在传输中加密(https)。服务器会添加发送地址所在的国家;地址本身不会保存。