Android
为你的 Android 应用提供结构化日志,支持 Kotlin 和 Java。除 Kotlin 标准库外没有任何依赖。
Android SDK 需要 Android 7.0(API 24)或更高版本。它用 Kotlin 编写,除 Kotlin 标准库外没有任何依赖(不依赖 OkHttp、coroutines 或 AndroidX),而且每个函数都可以从 Java 调用。
内部预览:这个包还没有发布。在发布之前,Gradle 无法拉取
com.lyrelog:lyrelog-android:它不在 Maven Central 上,仓库是私有的,也还没有任何 release。
安装
从 Maven Central 安装,在你的应用模块的 build.gradle.kts 中:
dependencies {
implementation("com.lyrelog:lyrelog-android:0.1.0")
}这个库会在你应用的 manifest 中添加 INTERNET 权限。
启动
只启动一次,越早越好,放在你的 Application 的 onCreate 中。运行期间的第二次调用会被忽略。在 start 之前记录的事件同样会被忽略,但在 start 之前调用的 setUser 和 setConsent 会被保留,并在启动时生效。
import android.app.Application
import com.lyrelog.Configuration
import com.lyrelog.Lyrelog
class MyApp : Application() {
override fun onCreate() {
super.onCreate()
Lyrelog.start(this, Configuration(
apiKey = "lyr_ing_...", // ingest-only: it can append events, never read them
))
}
}如果你的应用还没有 Application,请在 manifest 中指定这个类(<application android:name=".MyApp" ...>)。
事件发送到 https://ingest.lyrelog.com。只有要发送到其他地方时才需要传 endpoint。它是基础 URL(粘贴进来的 .../v1/events:batch 路径会被去掉),并且必须是 https;普通 http 只适用于 localhost、127.0.0.1 或 ::1,以及模拟器上的 10.0.2.2(见开发和测试中)。如果是其他 endpoint,什么都不会发送,事件会留在设备上。
记录事件
每个级别一个函数:trace、debug、info、notice、warning、error、critical,或者带 Level 参数的 log(level, message, ...)。
Lyrelog.info("checkout_done", attrs = mapOf("items" to 3, "latency_ms" to ms))
Lyrelog.error("payment_declined", category = "checkout",
attrs = mapOf("code" to 51), payload = mapOf("response" to raw))属性是一个 Map<String, Any?>:字符串、数字、布尔值、null、列表(其中的元素会作为字符串发送)以及最多 4 层的嵌套 map。payload 可以是任意 map、列表或值,用来放那些只有打开单个事件时才会看的细节。
按分类使用 logger
logger 会在每个事件上打上它的 category,就像 Android 日志的 tag。它有所有级别,外加 log 和 captureError。创建和持有它的开销都很小,调用时会写入当时正在运行的 SDK。
val sync = Lyrelog.logger("sync")
sync.warning("sync_conflict", mapOf("records" to 2))用户
Lyrelog.setUser(playerId) // attached to every following event
Lyrelog.setUser(null) // on sign-outLyrelog.sessionId 返回当前的会话 id,例如可以显示在客服支持页面上。
用户 id 不会在两次启动之间保存:每次启动时,一旦知道用户是谁,就再调用一次 setUser。
页面
告诉 Lyrelog 用户当前在哪个页面。Lyrelog 会记录 screen_viewed(分类 navigation),带上前一个页面,以及在该页面停留的秒数,并给之后的每个事件打上 screen 属性。
override fun onResume() {
super.onResume()
Lyrelog.screen("Settings")
}在 Compose 中,当某个导航目的地显示时,在 LaunchedEffect 里调用它。该事件携带 screen、previous_screen 和 seconds_on_previous。用相同的名字再次调用 screen 不会记录任何内容。screen 可以为 screen_viewed 事件传入额外的 attrs。用 attachScreen = false 可以关闭这种标记。
automaticScreens = true 会为每个切换到前台的 Activity 自动完成这件事,以类名命名(SettingsActivity)。它默认关闭:Compose 和 fragment 应用在一个 Activity 中有很多页面,而你自己取的名字在控制台上更易读。
你捕获的错误
try {
store.purchase(product)
} catch (e: IOException) {
Lyrelog.captureError(e, category = "store")
}它发送的是每个 SDK 都会发送的 exception 事件:级别为 error,带有属性 error_type(类名)和 error_message,payload 中包含错误描述、最多 60 个栈帧、cause 链(最多 8 个,每个 20 个栈帧)以及被抑制的异常。attrs 用于添加你自己的属性;level 用于修改级别。每个 logger 也都有 captureError。
栈帧保持 VM 报告的原样。如果应用用 R8 做了混淆压缩,请用该构建的 mapping 文件运行 retrace,还原原始名称。
崩溃
未捕获的异常会立即在即将终止的线程上写入磁盘,同时写入的还有所有仍在写入途中的事件。然后它会被交给之前已有的 handler(系统的崩溃对话框,或者先安装了 handler 的其他崩溃报告工具)。此时不会发送任何内容:进程即将结束。
下次启动时会发送它,时间是它发生的时间,归入它所终结的那个会话,位于 diagnostics 分类,与 Swift SDK 的崩溃报告一样,这样两个平台的崩溃会并列显示在控制台中:
| 事件 | 级别 | 携带的内容 |
|---|---|---|
app_crashed | critical | error_type、error_message、handled: false、mechanism: uncaught_exception,以及包含线程、栈帧、cause 链和被抑制异常的 payload |
它默认开启;用 captureCrashes = false 关闭。原生崩溃和 ANR 不会上报。
环境和平台
启动时,SDK 会选择环境:应用可调试时(android:debuggable,所有 debug 构建)为 development,其他情况为 production。
你自己的 debug 构建发送的是 development,而控制台默认打开 production:在顶部栏选择 development 才能看到它们。
平台为 android。两者都可以在配置中覆盖:
Configuration(
apiKey = key,
environment = if (BuildConfig.FLAVOR == "beta") "beta" else null, // null = detected
platform = null,
)任何名字都可以:小写字母、数字、- 和 _,最多 32 个字符。其他文本会被转换成合法的名字(Staging EU 变成 staging-eu)。
同意
Lyrelog.start(this, Configuration(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 recordingPENDING 会把事件保留在设备上而不发送。除非已获得同意,否则什么都不会上传,包括之前启动遗留下来的内容。以 Consent.DENIED 启动时,会删除之前启动遗留在队列中的所有内容以及安装 id,并且不记录任何内容。在 start 之前调用的 setConsent 优先于 Configuration.consent。
同意状态不会在两次启动之间保存:请自己保存用户的选择,并在每次调用 start 时传入。
完整的应用示例
用保存的同意状态启动,在用户登录时设置用户,并给页面打标签:
import android.app.Application
import com.lyrelog.Configuration
import com.lyrelog.Consent
import com.lyrelog.Lyrelog
class MyApp : Application() {
override fun onCreate() {
super.onCreate()
val prefs = getSharedPreferences("settings", MODE_PRIVATE)
val consent = when (prefs.getString("diagnostics", null)) {
"granted" -> Consent.GRANTED
"denied" -> Consent.DENIED
else -> Consent.PENDING
}
Lyrelog.start(this, Configuration(apiKey = "lyr_ing_...", consent = consent))
}
}
class HomeActivity : AppCompatActivity() {
override fun onResume() {
super.onResume()
Lyrelog.screen("Home")
}
private fun signedIn(account: Account) {
Lyrelog.setUser(account.id)
Lyrelog.info("signed_in", category = "auth")
}
}
fun choose(context: Context, allowed: Boolean) {
context.getSharedPreferences("settings", Context.MODE_PRIVATE).edit()
.putString("diagnostics", if (allowed) "granted" else "denied").apply()
Lyrelog.setConsent(if (allowed) Consent.GRANTED else Consent.DENIED)
}立即发送(flush)和停止
进入后台时已经会自动发送(在最后一个 Activity 停止时;屏幕旋转不算),所以你很少需要手动立即发送。
Lyrelog.flushInBackground() // send now, without waiting
Lyrelog.flush() // write everything to disk and send, waiting up to 5 seconds
Lyrelog.stop() // send what's queued (up to 2 seconds), then stop
Lyrelog.stopNow() // stop at once; what was logged goes with the next launchflush 和 stop 会阻塞,所以永远不要在主线程上调用它们。flush 在时限内完成时返回 true,并且会遵守服务器要求的 Retry-After:不会提前发送。调用 stop 之后,可以再次调用 start。
开发和测试中
不要在单元测试中调用 Lyrelog.start:在 start 之前记录的任何内容都会被忽略,所以其余代码照常运行,无需改动。开发时,mirrorToLogcat = true 还会把每个事件打印到 logcat(tag 为 Lyrelog)。
debug 构建发送的环境是 development。要从模拟器发送到运行在你电脑上的 endpoint,请把 http://10.0.2.2 加上端口作为 endpoint(在模拟器看来,10.0.2.2 就是你的电脑),并且只在 debug 构建中这样做:
- 允许向
10.0.2.2发送明文 http。 除非应用明确允许,否则 Android 会阻止它:在 debug 构建中添加一份 network security config,只对这一个地址允许明文流量。 - 在 Android 17 上,target 为 API 37 的应用还需要
ACCESS_LOCAL_NETWORK才能访问10.0.2.2这样的私有地址;没有它,连接只会超时。在 debug manifest(src/debug/AndroidManifest.xml)中声明该权限并授予它:adb shell pm grant <your.app> android.permission.ACCESS_LOCAL_NETWORK。
这只用于本地开发。托管的采集服务是一个公网 https 地址,这两项都不需要。
已验证事件
已验证事件是别人伪造不了的事件:即使有人从应用或网页里复制了公开的采集密钥,也发不出这样的事件。它能证明什么、不能证明什么,见已验证事件。
Android 应用的事件通过 Key Attestation 验证:手机的安全硬件证明这些事件来自你自己的应用,用你的证书签名,运行在未被 root 或解锁的真实设备上。Lyrelog 在自己的服务器上完成校验;不涉及 Google 账号、Play Integrity 或 Google Cloud 项目。
它默认开启(Configuration 中的 attest);在项目中完成设置即可:
- 在项目设置的
Verified events from your Android apps 部分,添加你的包名,以及每个为发送事件的构建签名的证书的 SHA-256 指纹:Play 的应用签名密钥(Play Console 中的 Test and release、App integrity),以及你自己签名的构建所用的证书(
./gradlew signingReport显示的那个)。 - 应用这边就只有这些。要关闭它:
Lyrelog.start(this, Configuration(apiKey = "lyr_ing_...", attest = false))每次安装,SDK 会在手机的安全硬件(StrongBox 或可信执行环境)中生成一个密钥,并让设备为它做 attestation;从那以后,它的批次都会携带 token,到达时即为已验证(verified_by 为 key_attestation)。token 有效期为 24 小时,会在过期前于后台续期。发送从不等待这一过程:在应用拿到 token 之前,以及任何环节出错时,事件都以未验证的形式发送。
- 模拟器永远无法通过验证,SDK 在模拟器上也不会尝试。
- 在项目设置好 Android 应用之前,或者密钥被拒绝、设备无法做 attestation 时,SDK 会在本次启动中关闭 attestation,并在 logcat 中提示一次。
- 被服务器拒绝的设备(已 root 的手机、已解锁的 bootloader、项目未列出的证书)会在一天后再试。
- 拒绝同意会删除已做过 attestation 的密钥及其记录(
noBackupFilesDir/lyrelog/attest.json)。
在设置好之前,事件以未验证的形式到达,并计入单个地址的每日配额。在把项目设置为只接受来自 android 的已验证事件之前,请先在事件浏览器中确认你真实用户的事件到达时是已验证的:来自旧版本、模拟器和被拒绝设备的事件会因 425 而被挡住。
你自己的服务器用服务器密钥 lyr_srv_... 发送的事件是已验证的。永远不要把服务器密钥放进应用:APK 中的任何内容都可以被读取。
要确认是否生效,打开事件浏览器:打开一个事件,在 Context 下的 Sender 一行会显示:Verified, Key Attestation 或 Not verified, public key。
谁验证什么,以及每日配额,见已验证事件。
从 Java 调用
在 Java 中,Lyrelog 上的每个函数都是静态的,并为可选参数提供了重载:
Lyrelog.start(this, new Configuration("lyr_ing_..."));
Lyrelog.info("checkout_done");
Lyrelog.captureError(e, "store");Configuration 和 logger 的函数也有重载,所以末尾的参数可以省略(logger.warning("sync_conflict")、logger.warning("sync_conflict", attrs))。
配置
| 选项 | 默认值 | 含义 |
|---|---|---|
apiKey | 必填 | 项目的采集密钥 |
endpoint | https://ingest.lyrelog.com | 基础 URL;粘贴进来的 /v1/... 路径会被去掉。只能用 https,http 仅限 localhost 和模拟器的 10.0.2.2 |
consent | Consent.GRANTED | PENDING、GRANTED 或 DENIED |
minimumLevel | Level.DEBUG | 低于该级别的事件永远不会写入磁盘 |
flushIntervalMillis | 15 s | 有 Activity 处于 started 状态时,上传器多久运行一次 |
maxBatchBytes | 512 KiB | 批次达到任一限制时即关闭(不超过 4 MiB) |
maxBatchEvents | 500 | 最多 2,000 |
maxDiskBytes | 20 MB | 磁盘队列的上限,最旧的先丢弃 |
maxEventAgeMillis | 7 天 | 队列中更旧的事件会被丢弃 |
sessionTimeoutMillis | 30 min | 空闲多久后开始新会话 |
environment | 自动检测 | 任何合法名称,或 null |
platform | android | 任何合法名称,或 null |
appVersion | 应用的 versionName | 作为 resource.app_version 发送 |
redactedKeys | null:即 DEFAULT_REDACTED_KEYS | 需要脱敏的键名;你的列表会替换默认值,空列表则关闭脱敏 |
captureCrashes | true | 记录未捕获的异常,在下次启动时发送 |
attachScreen | true | 给事件打上当前页面的标签 |
automaticScreens | false | 为每个 Activity 记录 screen_viewed,以类名命名 |
attest | true | 用 Key Attestation 证明应用身份,在项目列出其包名和证书后,事件到达时即为已验证 |
mirrorToLogcat | false | 同时把每个事件打印到 logcat(tag 为 Lyrelog) |
storageDirectory | noBackupFilesDir/lyrelog | 队列存放的位置 |
投递和限制
| 从不阻塞 | 记录日志只复制事件就返回;由一个后台写入器把它写入磁盘,并且从不等待网络。 |
| 进程被杀和离线时不丢失 | 队列位于 noBackupFilesDir/lyrelog,上限为 20 MB 和 7 天。已经写入磁盘的内容在崩溃、进程被杀或离线数天后依然保留;仍在送往写入器途中的事件(毫秒级)会由崩溃 handler 写入,如果进程被直接杀掉则会丢失。这个文件夹永远不会被备份,所以恢复后的手机不会重发另一台设备的事件。 |
| 何时发送 | 有 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 天的上限约束。SDK 会向 logcat 记录一条警告,只有在此期间有批次被接受之后才会再次记录。 |
| 丢弃有迹可查 | 因上限而丢失的事件会汇总成一条 lyrelog_events_dropped 警告(分类 lyrelog),附带数量。 |
| SDK 自身的问题 | endpoint 写错、404、有行被拒绝或 endpoint 无响应时,每次启动会向 logcat 记录一次,tag 为 Lyrelog,debug 级别。 |
| 上下文 | 应用 id(包名)、版本名、版本号、android、Android 版本、设备(Google Pixel 9)、区域设置、环境、平台 android、会话 id(空闲 30 min 后更新)和安装 id。 |
| 敏感信息 | 名称等于或以 authorization、cookie、password、token、secret、apikey 以及共享列表中其余词结尾的键,其值会在任意深度、在任何截断之前变成 "[redacted]"。 |
| 限制 | 长字符串在字符边界处截断,多出的属性计入 lyrelog_dropped_attrs,超过 64 KiB 的 payload 会被概括为 {"lyrelog_truncated": true, "bytes": N, "preview": "..."}。 |
用 redactedKeys 修改这个列表:你的列表会替换默认值,空列表则关闭脱敏。要在默认值上追加:
Lyrelog.start(this, Configuration(
apiKey = "lyr_ing_...",
redactedKeys = Configuration.DEFAULT_REDACTED_KEYS + "pin",
))Play 数据安全
填写 Play Console 的数据安全表单时,声明你的应用通过 Lyrelog 发送了哪些数据:
- App info and performance: Crash logs、Diagnostics(App functionality;如果你这样使用,还有 Analytics)。收集,不共享。
- Device or other IDs: 安装 id,一个随机 UUID,不是广告标识符,不会被备份,拒绝同意时会被删除。除非你还调用了
setUser,否则不与用户关联。 - App activity > App interactions: 如果你记录页面(
screen_viewed)或点击。 - 你的
attrs或payload携带的其他任何数据(电子邮件、购买记录...),归入各自的类别。
数据在传输中加密(https)。服务器会添加发送地址所在的国家;地址本身不会保存。