@Monitor
@Monitor 標記一個類別或函式以進行追蹤。在建置時,Koin 編譯器外掛程式會將每個被監控的函式包裝在 Kotzilla SDK 的追蹤呼叫中,因此其執行時間與錯誤會顯示在 Kotzilla 平台上。本頁面介紹該註解在有與沒有 Kotzilla SDK 時的作用。本文假設已設定 Koin 編譯器外掛程式。
無 Kotzilla 的內建監控
Koin 在執行期查看發生什麼事的內建方式是記錄器。它會將模組載入與執行個體建立輸出至主控台或 Logcat。請參閱記錄。
@Monitor 本身不會增加任何內容。如果編譯 classpath 上沒有 Kotzilla SDK,編譯器外掛程式會保持被監控的函式不變,並在每次編譯時回報一個警告:
KOIN-M001: @Monitor: Kotzilla SDK not found on classpath - monitoring disabled程式碼會像沒有該註解一樣編譯並執行。你可以將 @Monitor 保留在共享程式碼中,僅在想要追蹤的組建中新增該 SDK。
為類別或函式加上註解
@Monitor 位於 org.koin.core.annotation 中,與其他 Koin 註解並列。將其放置於類別上可追蹤其所有公用函式,或放置於單一函式上:
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: not traced
}
class SyncService(private val api: ApiService) {
@Monitor
suspend fun sync() { ... }
}無論使用何種風格宣告類別,該註解的運作方式都相同:註解或任何 DSL 形式(編譯器外掛程式、Constructor DSL 或 Classic DSL)。ViewModel 也可以被監控:
@Monitor
class DetailViewModel(private val repository: Repository) : ViewModel() {
fun loadData(id: String): StateFlow<Data> = repository.getData(id)
}編譯器外掛程式產生的內容
當 classpath 上有 Kotzilla SDK 時,編譯器外掛程式會重寫每個被監控函式的本體。UserService 類別中的 findUser 編譯時就如同你這樣撰寫:
fun findUser(id: String): User? =
KotzillaCore.getDefaultInstance().trace("UserService.findUser") {
userRepository.findById(id)
}規則:
- 標籤:
ClassName.functionName,若是頂層函式則為函式名稱。 - Suspend 函式:使用
suspendTrace而非trace進行包裝。 - 類別層級的
@Monitor:僅追蹤公用函式。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類別必須位於編譯 classpath 上。io.kotzilla:kotzilla-sdk相依性透過io.kotzilla:kotzilla-core引入此類別。 - 在執行期:SDK 必須在你的 Koin 配置中啟動,以便記錄並傳送追蹤。
兩者皆為正式環境監控中所述標準 Kotzilla 設定的一部分。一旦 SDK 執行,對被監控函式的每次呼叫都會記錄其執行時間,且若擲出例外,則會記錄其錯誤。你可以在 Kotzilla 主控台中檢視它們。
WARNING
產生的程式碼會呼叫 KotzillaCore.getDefaultInstance()。請在應用程式啟動時啟動 Kotzilla SDK,必須在任何被監控函式執行之前。
搭配 Koin Annotations (KSP)
使用 KSP 處理器(koin-ksp-compiler,Koin Annotations 2.2.0 及更高版本)時,@Monitor 的運作方式有所不同。KSP 無法重寫函式本體,因此它會產生一個名為 <ClassName>Proxy 的子類別,以追蹤呼叫覆寫每個公用函式,且 Koin 定義會使用此代理。這會帶來兩個影響:
- Open 類別:被監控的類別必須是 open。請使用
annotation("org.koin.core.annotation.Monitor")設定allOpenGradle 外掛程式。 - 僅限定義:只有作為 Koin 定義的類別才會被代理。
編譯器外掛程式取代了這個機制。請參閱從 KSP 遷移至編譯器外掛程式。
限制
- 無傳遞性追蹤:僅追蹤帶有註解的類別或函式。注入至被監控類別中的相依性不會被追蹤,除非它們也帶有
@Monitor。 - 無本機資料:沒有 Kotzilla SDK 就不會記錄任何內容。若要進行本機偵錯,請使用 Koin 記錄器。
- 開銷:每個被監控的呼叫都會經過追蹤呼叫。請為想要度量的函式加上註解,而非每個類別。
