Skip to main content
Version: 4.2

@Monitor

@Monitor marks a class or a function for tracing. At build time, the Koin Compiler Plugin wraps each monitored function in a Kotzilla SDK trace call, so its execution time and errors show up in the Kotzilla platform. This page covers what the annotation does with and without the Kotzilla SDK. It assumes the Koin Compiler Plugin is set up.

Built-in monitoring without Kotzilla​

Koin's built-in way to see what happens at runtime is the logger. It prints module loading and instance creation to the console or Logcat. See Logging.

@Monitor adds nothing on its own. Without the Kotzilla SDK on the compile classpath, the Compiler Plugin leaves monitored functions unchanged and reports one warning per compilation:

KOIN-M001: @Monitor: Kotzilla SDK not found on classpath - monitoring disabled

The code compiles and runs as if the annotation were not there. You can keep @Monitor in shared code and only add the SDK in the builds you want to trace.

Annotating a class or a function​

@Monitor is in org.koin.core.annotation, next to the other Koin annotations. Put it on a class to trace all its public functions, or on a single function:

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() { ... }
}

The annotation works the same whatever style declares the class: Compiler Plugin DSL, annotations or Classic DSL. ViewModels can be monitored too:

@Monitor
class DetailViewModel(private val repository: Repository) : ViewModel() {
    fun loadData(id: String): StateFlow<Data> = repository.getData(id)
}

What the Compiler Plugin generates​

With the Kotzilla SDK on the classpath, the Compiler Plugin rewrites the body of each monitored function. findUser from the UserService class compiles as if you had written:

fun findUser(id: String): User? =
    KotzillaCore.getDefaultInstance().trace("UserService.findUser") {
        userRepository.findById(id)
    }

Rules:

  • Label: ClassName.functionName, or the function name for a top-level function.
  • Suspend functions: wrapped with suspendTrace instead of trace.
  • Class-level @Monitor: only public functions are traced. Private, protected and internal functions, constructors and default property accessors are not.
  • No proxy, no allOpen: the body is rewritten in place. The class stays final and Koin creates it as usual.

During the build, the plugin reports each monitored class:

@Monitor: UserService - tracing enabled (2 functions)

This message is a warning by default. If your build uses allWarningsAsErrors, set logSeverity = "info" in the koinCompiler { } block: see Compiler Plugin Options.

With the Kotzilla SDK​

@Monitor needs the Kotzilla SDK twice:

  • At build time: the class io.kotzilla.sdk.KotzillaCore must be on the compile classpath. The io.kotzilla:kotzilla-sdk dependency brings it, through io.kotzilla:kotzilla-core.
  • At runtime: the SDK must be started in your Koin configuration so that traces are recorded and sent.

Both are part of the standard Kotzilla setup described in Production Monitoring. Once the SDK runs, each call to a monitored function is recorded with its duration and, if it throws, its error. You see them in the Kotzilla console.

warning

The generated code calls KotzillaCore.getDefaultInstance(). Start the Kotzilla SDK at app startup, before any monitored function can run.

With Koin Annotations (KSP)​

With the KSP processor (koin-ksp-compiler, Koin Annotations 2.2.0 and later), @Monitor works differently. KSP can't rewrite a function body, so it generates a subclass named <ClassName>Proxy that overrides each public function with the trace call, and the Koin definition uses this proxy. Two consequences:

  • Open classes: the monitored class must be open. Configure the allOpen Gradle plugin with annotation("org.koin.core.annotation.Monitor").
  • Definitions only: only classes that are Koin definitions are proxied.

The Compiler Plugin replaces this mechanism. See Migrating from KSP to the Compiler Plugin.

Limits​

  • No transitive tracing: only the annotated class or function is traced. Dependencies injected into a monitored class are not, unless they carry @Monitor too.
  • No local data: without the Kotzilla SDK nothing is recorded. For local debugging, use the Koin logger.
  • Overhead: every monitored call goes through a trace call. Annotate the functions you want to measure, not every class.