@Monitor
@Monitor 用于将类或函数标记以进行跟踪。在构建期,Koin 编译器插件会将每个受监控的函数包装在 Kotzilla SDK 跟踪调用中,从而使其执行时间和错误显示在 Kotzilla 平台中。本页面介绍了该注解在有无 Kotzilla SDK 时的作用。前提是已配置好 Koin 编译器插件。
无 Kotzilla 时的内置监控
Koin 在运行时查看运行状态的内置方式是记录器。它会将模块加载和实例创建输出到控制台或 Logcat。请参阅日志记录。
@Monitor 本身不会添加任何内容。如果编译类路径中没有 Kotzilla SDK,编译器插件会保持受监控的函数不变,并在每次编译时报告一条警告:
KOIN-M001: @Monitor: Kotzilla SDK not found on classpath - monitoring disabled代码的编译和运行方式与未添加该注解时完全相同。你可以将 @Monitor 保留在共享代码中,并仅在需要跟踪的构建中添加 SDK。
为类或函数添加注解
@Monitor 位于 org.koin.core.annotation 中,与其他 Koin 注解并列。将其放在类上可跟踪其所有 public 函数,或者将其直接放在单个函数上:
import org.koin.core.annotation.Monitor
@Monitor
class UserService(private val userRepository: UserRepository) {
fun findUser(id: String): User? = userRepository.findById(id)
suspend fun createUser(userData: UserData): User = userRepository.save(userData)
private fun audit(user: User) { ... } // private: 不会被跟踪
}
class SyncService(private val api: ApiService) {
@Monitor
suspend fun sync() { ... }
}无论通过何种风格声明类(注解或任何 DSL 形式,如编译器插件、构造函数或经典 DSL),该注解的工作方式都相同。ViewModel 也可以被监控:
@Monitor
class DetailViewModel(private val repository: Repository) : ViewModel() {
fun loadData(id: String): StateFlow<Data> = repository.getData(id)
}编译器插件生成的内容
当类路径中存在 Kotzilla SDK 时,编译器插件会重写每个受监控函数的主体。UserService 类中的 findUser 编译后的效果如同你编写了以下代码:
fun findUser(id: String): User? =
KotzillaCore.getDefaultInstance().trace("UserService.findUser") {
userRepository.findById(id)
}规则:
- 标签:
ClassName.functionName,顶层函数则为函数名称。 - 挂起函数:使用
suspendTrace而非trace进行包装。 - 类级
@Monitor:仅跟踪 public 函数。private、protected 和 internal 函数、构造函数以及默认属性访问器均不会被跟踪。 - 无需代理,无需
allOpen:直接在原地重写函数体。类仍保持为 final,Koin 照常创建它。
在构建期间,插件会报告每个受监控的类:
@Monitor: UserService - tracing enabled (2 functions)该消息默认是一条警告。如果你的构建使用了 allWarningsAsErrors,请在 koinCompiler { } 代码块中设置 logSeverity = "info":请参阅编译器插件选项。
配合 Kotzilla SDK 使用
@Monitor 在两个阶段需要 Kotzilla SDK:
- 构建期:类
io.kotzilla.sdk.KotzillaCore必须位于编译类路径上。通过io.kotzilla:kotzilla-core引入的io.kotzilla:kotzilla-sdk依赖项会提供该类。 - 运行时:必须在 Koin 配置中启动 SDK,以便记录并发送跟踪。
两者均属于生产监控中所述的标准 Kotzilla 配置的一部分。SDK 运行后,对受监控函数的每次调用都会记录其耗时以及抛出的错误(如果有)。你可以在 Kotzilla 控制台中查看它们。
WARNING
生成的代码会调用 KotzillaCore.getDefaultInstance()。请在应用启动时、任何受监控函数运行之前启动 Kotzilla SDK。
配合 Koin Annotations (KSP) 使用
使用 KSP 处理器(koin-ksp-compiler,Koin Annotations 2.2.0 及更高版本)时,@Monitor 的工作方式有所不同。KSP 无法重写函数体,因此它会生成一个名为 <ClassName>Proxy 的子类,通过跟踪调用重写每个 public 函数,并且 Koin 定义会使用此代理。这会带来两个后果:
- Open 类:受监控的类必须为 open。使用
annotation("org.koin.core.annotation.Monitor")配置allOpenGradle 插件。 - 仅限定义:仅属于 Koin 定义的类才会被代理。
编译器插件取代了这一机制。请参阅从 KSP 迁移到编译器插件。
局限性
- 无传递跟踪:仅跟踪带有注解的类或函数。注入到受监控类中的依赖项不会被跟踪,除非它们也带有
@Monitor。 - 无本地数据:没有 Kotzilla SDK 则不会记录任何内容。对于本地调试,请使用 Koin 记录器。
- 开销:每个受监控的调用都会经过一次跟踪调用。建议仅对需要度量的函数添加注解,而不是对每个类都添加。
