kiosk-ops-sdk/com.sarastarquant.kioskops.sdk.observability/CorrelationContext

CorrelationContext

Thread-local correlation context for distributed tracing and audit trail linkage.

Provides automatic correlation ID generation and propagation across SDK operations, enabling end-to-end request tracing through logs, spans, and audit events.

Compliance (ISO 27001 A.12.4): Enables comprehensive audit trail by linking related operations across service boundaries.

Thread Safety: Uses ThreadLocal storage. Context must be explicitly copied when crossing thread boundaries (e.g., coroutine dispatchers).

Since

0.4.0

Properties

correlationId

val correlationId: String

Current correlation ID. Auto-generated if not explicitly set. Format: 16 character lowercase hex string.

HEADER_CORRELATION_ID

const val HEADER_CORRELATION_ID: String

HEADER_TRACE_PARENT

const val HEADER_TRACE_PARENT: String

HEADER_TRACE_STATE

const val HEADER_TRACE_STATE: String

KEY_CORRELATION_ID

const val KEY_CORRELATION_ID: String

KEY_DEVICE_ID

const val KEY_DEVICE_ID: String

KEY_OPERATION_NAME

const val KEY_OPERATION_NAME: String

KEY_PARENT_SPAN_ID

const val KEY_PARENT_SPAN_ID: String

KEY_SESSION_ID

const val KEY_SESSION_ID: String

KEY_SPAN_ID

const val KEY_SPAN_ID: String

KEY_TRACE_ID

const val KEY_TRACE_ID: String

KEY_USER_ID

const val KEY_USER_ID: String

operationName

val operationName: String?

Operation name for the current context.

parentSpanId

val parentSpanId: String?

Parent span ID for nested spans, or null if root span.

spanId

val spanId: String?

Current OpenTelemetry span ID (16 hex chars), or null if not in a span.

traceId

val traceId: String?

Current OpenTelemetry trace ID (32 hex chars), or null if not in a trace context.

Functions

clear

fun clear()

Clear all context values for the current thread.

generateId

fun generateId(): String

Generate a new correlation ID (16 lowercase hex characters).

generateSpanId

fun generateSpanId(): String

Generate a new span ID (16 lowercase hex characters) following W3C Trace Context.

generateTraceId

fun generateTraceId(): String

Generate a new trace ID (32 lowercase hex characters) following W3C Trace Context.

get

fun get(key: String): String?

Get a context value by key.

remove

fun remove(key: String)

Remove a context value.

restore

fun restore(snapshot: Map<String, String>)

Restore context from a snapshot (e.g., when crossing thread boundaries).

set

fun set(key: String, value: String)

Set a context value.

snapshot

fun snapshot(): Map<String, String>

Get a snapshot of the current context for cross-thread propagation.

withAttributes

inline fun <T> withAttributes(attributes: Map<String, String>, block: () -> T): T

Execute a block with additional context attributes. Attributes are merged with existing context and removed after block completes.

withContext

inline fun <T> withContext(correlationId: String? = null, operationName: String? = null, block: () -> T): T

Execute a block with a new or specified correlation context. Previous context is restored after the block completes.