kandra-core/io.kandra.core/KandraMetrics

KandraMetrics

Callback interface for recording query execution metrics.

Implement this to bridge Kandra into any metrics backend (Micrometer, Dropwizard, etc.). Wire it via io.kandra.ktor.KandraConfig.metrics in the Kandra Ktor plugin.

install(Kandra) {
    metrics {
        enabled = true
        recorder = KandraMetrics { table, op, durationMs ->
            meterRegistry.timer("kandra.query", "table", table, "operation", op)
                .record(durationMs, TimeUnit.MILLISECONDS)
        }
    }
}

Functions

record

abstract fun record(tableName: String, operation: String, durationMs: Long)

Called after every successful query execution (both blocking and suspend paths).

open fun record(tableName: String, operation: String, durationMs: Long, attempts: Int)

Same as record, but also reports how many attempts the query took to succeed (a query that only succeeded on its 3rd attempt still round-tripped 3 times — record alone can't distinguish that from a query that succeeded on the first try). Defaults to delegating to record so existing implementations (including SAM lambdas built against the single-abstract-method record) keep compiling and behaving exactly as before; override this overload instead if you want attempt counts.

recordFailure

open fun recordFailure(tableName: String, operation: String, durationMs: Long, attempts: Int, exceptionType: String)

Called when a query ultimately fails and no successful result was ever produced — covers retry exhaustion, an immediate non-retryable exception (wrong type for io.kandra.runtime.RetryConfig.retryOn, or a non-idempotent statement), and rejection because Kandra is shutting down. Has a no-op default so existing KandraMetrics implementations keep compiling unchanged — this interface is public and pluggable, so adding this hook must not be a breaking change.