Skip to main content

Kotzilla SDK API

This page describes Kotzilla SDK API and provides examples of how to use it to track events, manage session data, and capture performance metrics in your application.

info

This page assumes the Kotzilla SDK is already initialized in your project via monitoring(). If you have not set up the SDK yet, see the setup guides for your app type.

Delayed SDK Start (e.g. Feature Flag)​

If you need to delay the Kotzilla SDK start (for example, to wait for a feature flag evaluation before enabling monitoring), call monitoring() on the KoinApplication instance after the startKoin block:

override fun onCreate() {
    super.onCreate()

    val koinApp = startKoin {
        androidContext(this@MyApplication)
        modules(appModule)
    }

    // Start Kotzilla SDK after Koin is configured
    koinApp.monitoring()
}

Logging Messages​

You can add custom log messages to your app's timeline to provide additional context and track important events using the log function. This is useful for capturing information about specific actions or states in your app.

  • Function: KotzillaSDK.log(message: String)

Example:

KotzillaSDK.log("a message ...")

This will add the message to your timeline, helping you track events in the app.

Capture exceptions​

To capture non-fatal exceptions and add them to your timeline for later debugging, use the logError function to log errors with exceptions.

  • Function: KotzillaSDK.logError(message: String, error: Throwable)

Example:

KotzillaSDK.logError("an error occurred", exception)

This will record both the message and exception, making it easier to debug issues that happen in production.

Trace code performance​

To measure the performance of specific code blocks, you can use the trace function. This allows you to benchmark the execution time of certain operations and track their performance within your app.

  • Function: KotzillaSDK.trace(name: String, block: () -> Unit)

Example:

KotzillaSDK.trace("my_code_block") {
    // My code to benchmark here ...
    myComponent.MyHeavyCall()
}

This will track the performance of the specified code block and record the execution time in your timeline.

Trace coroutine performance​

For suspend functions and coroutines, use the suspendTrace function to measure performance asynchronously.

  • Function: KotzillaSDK.suspendTrace(name: String, block: suspend () -> T): T

Example:

suspend fun loadData() = KotzillaSDK.suspendTrace("load_user_data") {
    // Suspend function call
    repository.fetchUserData()
}

This is particularly useful for tracking the performance of suspend functions, network calls, or database operations in coroutines.

Add session properties​

You can add custom properties to the current session to enrich the context of your app's data. This can include anything from user preferences to current app settings.

  • Function: KotzillaSDK.setProperties(vararg properties: Pair<String, Any>)

Example:

KotzillaSDK.setProperties(
    "my_string" to "a_string",
    "my_int" to 1,
    "my_double" to 1.0,
    "my_bool" to true,
)

This will add the provided properties to the session data, helping you track custom context during a user's session.

Set user Id properties​

To track sessions for specific users, you can set a unique user ID. This allows you to correlate the session data with a particular user, enabling more granular analysis.

  • Function: KotzillaSDK.setUserId(userId: String)

Example:

KotzillaSDK.setUserId("user_123")

This will associate the current session with the specified user ID and add it to the session data for tracking purposes.

Set app version code​

Since SDK 2.2.0, Android apps report the runtime versionCode automatically, separately from the version name, so app versions are unambiguous in the Console. Manual and non-Android integrations (KMP, CMP, SDK Library) can set it explicitly with setVersionCode(...), keeping the version code consistent with the version name across the Console.

Startup tracing​

Since SDK 2.3.0 Kotzilla captures app‑startup performance in two complementary ways.

Automatic startup metric​

The SDK automatically emits one startup event per launch, classifying it as cold (fresh process → first frame) or warm (background → foreground → first frame). It carries the startup duration, the launch source (launcher / deeplink / notification / unknown), and the type (cold / warm) — no code needed on your side. It fires only on a confirmed foreground UI launch (background/headless launches produce nothing).

note

The automatic startup metric is currently Android only. It is delivered when your Kotzilla environment advertises the startup event type — no action needed for managed environments.

Custom marks​

Use mark(...) to drop point‑in‑time markers on a startup track. The backend derives phase durations from adjacent marks on the same track, so you can measure your own startup phases.

  • Function: KotzillaCoreSDK.mark(label: String, track: String = "startup")
  • On Android you can also call KotzillaStartup.mark(...) before a live SDK instance exists (e.g. very early in Application).
KotzillaCoreSDK.mark("di_ready")
KotzillaCoreSDK.mark("first_frame")

// custom track:
KotzillaCoreSDK.mark("cache_warmed", track = "warmup")
No PII in marks

Never put secrets, user IDs, or other personal data in mark labels or track names — they are sent as‑is.

Since SDK 2.3.0 you can gate all telemetry behind explicit user consent with setConsent(...), getConsent(), and forgetMe(), enabled by kotzilla { consentRequired = true }. See the dedicated Privacy & user consent page for the full API and behaviour.