Insights

Request profiling, performance metrics, and a built-in debug GUI.

Enabling insights

Insights is enabled per-route group by calling instrumentWithInsights() after installing the Kontainer. The insights config controls whether collection is active.

fun Route.installApiKontainer(app: App<MyConfig>, insights: InsightsConfig?) {
    installKontainer { call ->
        app.kontainers.create {
            with { call.currentUserProvider() }
            insights?.let { with { insights } }
        }
    }

    instrumentWithInsights(insights)
}

Mounting the GUI

Mount the built-in debug toolbar on your admin host. It provides a web UI for browsing recent requests, database queries, and timing breakdowns.

routing {
    host("admin.*".toRegex()) {
        installWwwKontainer(app, config.api.insights)

        // Mount insights GUI at /_/insights/
        init.use(InsightsGui::class) {
            mount()
        }
    }
}

What it collects

Insights uses per-request Kontainer scoping to collect data throughout a request's lifecycle. Each collector gathers one kind of data:

How it works

Each collector is a dynamic Kontainer service — a new instance is created for every request. Throughout the request lifecycle, collectors accumulate data. At the end of the request, the collected data is serialized into the API response as metadata.