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

Android

为你的 Android 应用提供结构化日志,支持 Kotlin 和 Java。除 Kotlin 标准库外没有任何依赖。

手机和平板,使用 Kotlin 或 Java

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

Lyrelog.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_crashedcriticalerror_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 recording

PENDING 会把事件保留在设备上而不发送。除非已获得同意,否则什么都不会上传,包括之前启动遗留下来的内容。以 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 launch

flush 和 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);在项目中完成设置即可:

  1. 在项目设置的 Verified events from your Android apps 部分,添加你的包名,以及每个为发送事件的构建签名的证书的 SHA-256 指纹:Play 的应用签名密钥(Play Console 中的 Test and release、App integrity),以及你自己签名的构建所用的证书(./gradlew signingReport 显示的那个)。
  2. 应用这边就只有这些。要关闭它:
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必填项目的采集密钥
endpointhttps://ingest.lyrelog.com基础 URL;粘贴进来的 /v1/... 路径会被去掉。只能用 https,http 仅限 localhost 和模拟器的 10.0.2.2
consentConsent.GRANTEDPENDING、GRANTED 或 DENIED
minimumLevelLevel.DEBUG低于该级别的事件永远不会写入磁盘
flushIntervalMillis15 s有 Activity 处于 started 状态时,上传器多久运行一次
maxBatchBytes512 KiB批次达到任一限制时即关闭(不超过 4 MiB)
maxBatchEvents500最多 2,000
maxDiskBytes20 MB磁盘队列的上限,最旧的先丢弃
maxEventAgeMillis7 天队列中更旧的事件会被丢弃
sessionTimeoutMillis30 min空闲多久后开始新会话
environment自动检测任何合法名称,或 null
platformandroid任何合法名称,或 null
appVersion应用的 versionName作为 resource.app_version 发送
redactedKeysnull:即 DEFAULT_REDACTED_KEYS需要脱敏的键名;你的列表会替换默认值,空列表则关闭脱敏
captureCrashestrue记录未捕获的异常,在下次启动时发送
attachScreentrue给事件打上当前页面的标签
automaticScreensfalse为每个 Activity 记录 screen_viewed,以类名命名
attesttrue用 Key Attestation 证明应用身份,在项目列出其包名和证书后,事件到达时即为已验证
mirrorToLogcatfalse同时把每个事件打印到 logcat(tag 为 Lyrelog)
storageDirectorynoBackupFilesDir/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)。服务器会添加发送地址所在的国家;地址本身不会保存。