kuilt-otel-logging/us.tractat.kuilt.otel.logging

Package-level declarations

Types

data class ActiveTrace(val traceId: ByteString, val spanId: ByteString, val sampled: Boolean)

The distributed-trace context active on the current call.

data class CaptureConfig(val minLevel: LogLevel = LogLevel.TRACE, val untracedPolicy: UntracedPolicy = UntracedPolicy.CAPTURE, val attributeMapper: (NormalizedLogEvent) -> Map<String, String> = ::defaultAttributeMapper)

Policy for the capture core: which events to keep and how to shape their attributes.

CaptureHealth

data class CaptureHealth(val droppedEvents: Long = 0)

An out-of-band health signal for the log-capture edge.

CoroutineContextTraceProvider

class CoroutineContextTraceProvider : TraceContextProvider

A TraceContextProvider backed by the coroutine-context trace an app sets with withActiveTrace — the dependency-light, commonMain source for platforms with no ambient tracer (wasmJs, iOS, macOS).

LogCapture

class LogCapture(exporter: WarpLogRecordExporter, config: CaptureConfig, clock: Clock, random: Random, traceContextProvider: TraceContextProvider? = null)

The shared, platform-independent capture core.

LogCaptureInstallation

class LogCaptureInstallation : AutoCloseable

A live log-capture installation — the LogCapture core plus the way to stop it.

LogLevel

enum LogLevel : Enum<LogLevel>

A platform-independent log level, carrying its OTLP severity mapping.

MutableTraceContextHolder

class MutableTraceContextHolder(initial: ActiveTrace? = null) : TraceContextProvider

A directly-settable TraceContextProvider — the escape hatch for apps or tests that cannot scope their tracing as coroutines (prefer withActiveTrace + CoroutineContextTraceProvider, which is the primary API).

NormalizedLogEvent

data class NormalizedLogEvent(val level: LogLevel, val loggerName: String, val message: String?, val attributes: Map<String, String> = emptyMap(), val activeTrace: ActiveTrace? = null, val resolvedAttributes: Map<String, String>? = null, val emittedEpochNanos: Long? = null)

A log event normalized to a platform-independent shape.

TraceContextProvider

fun interface TraceContextProvider

Supplies the trace context active on the current call, or null when none.

UntracedPolicy

enum UntracedPolicy : Enum<UntracedPolicy>

What to do with a log emitted outside any active trace.

Properties

CAPTURE_BATCH_MAX

const val CAPTURE_BATCH_MAX: Int = 256

The most events one drain turn hands to the exporter at once.

CAPTURE_QUEUE_CAPACITY

const val CAPTURE_QUEUE_CAPACITY: Int = 1024

How deep the capture queue is — the buffer between the application's synchronous logging call and the drain coroutine that exports each event.

EXCEPTION_MESSAGE_ATTRIBUTE

const val EXCEPTION_MESSAGE_ATTRIBUTE: String

Attribute key under which a capture edge may record an exception's message.

LOGGER_NAME_ATTRIBUTE

const val LOGGER_NAME_ATTRIBUTE: String

Attribute key under which defaultAttributeMapper records the logger name.

Functions

defaultAttributeMapper

fun defaultAttributeMapper(event: NormalizedLogEvent): Map<String, String>

The default CaptureConfig.attributeMapper: records the logger name under LOGGER_NAME_ATTRIBUTE, then the event's own attributes (which therefore win on key collision).

installLogCapture

fun installLogCapture(exporter: WarpLogRecordExporter, config: CaptureConfig, clock: Clock, random: Random, scope: CoroutineScope, traceContextProvider: TraceContextProvider? = null): LogCaptureInstallation

Install log capture — the single uniform entry point on every platform.

withActiveTrace

expect suspend fun <T> withActiveTrace(trace: ActiveTrace, block: suspend CoroutineScope.() -> T): T

Run block with trace as the active trace for the log lines it emits, then restore the previously-active trace. The whole point of native trace context: whoever starts a span wraps the work, and kuilt's sampling gate then stamps or drops those lines by that trace — on wasmJs, iOS and macOS, not only the JVM.