CallId

class CallId

Retrieves and generates if necessary a call id. A call id (or correlation id) could be retrieved_ from a call via CallId.Configuration.retrieve function. Multiple retrieve functions could be configured that will be invoked one by one until one of them return non-null value. If no value has been provided by retrievers then a generator could be applied to generate a new call id. Generators could be provided via CallId.Configuration.generate function. Similar to retrieve, multiple generators could be configured so they will be invoked one by one. Usually call id is passed via io.ktor.http.HttpHeaders.XRequestId so one could use CallId.Configuration.retrieveFromHeader function to retrieve call id from a header.

All retrieved or generated call ids are verified against CALL_ID_DEFAULT_DICTIONARY by default. Alternatively a custom dictionary or functional predicate could be provided via CallId.Configuration.verify that could pass a valid call id, discard an illegal call id or reject completely an ApplicationCall with HttpStatusCode.BadRequest if an RejectedCallIdException is thrown. Please note that this rejection functionality is not compatible with StatusPages for now and you cannot configure rejection response message.

Once a call id is retrieved or generated, it could be accessed via ApplicationCall.callId otherwise it will be always null. Also a call id could be replied with response by registering CallId.Configuration.reply or CallId.Configuration.replyToHeader so client will be able to know call id in case when it is generated.

Please note that call id feature is only intended for debugging and troubleshooting purposes to correlate client requests with logs in multitier/microservices architecture. So usually it is not guaranteed that call id is strictly random/unique. This is why you should NEVER rely on it’s uniqueness.

CallId feature will be installed to CallId.phase into ApplicationCallPipeline.

Types

Configuration

class Configuration

CallId feature’s configuration

Feature

companion object Feature : 
    ApplicationFeature<ApplicationCallPipeline, Configuration, CallId>

Installable feature for CallId

Companion Object Properties

key

Unique key that identifies a feature

phase

val phase: PipelinePhase

ApplicationCallPipeline’s phase which this feature will be installed to

Companion Object Functions

install

fun install(
    pipeline: ApplicationCallPipeline,
    configure: Configuration.() -> Unit
): CallId

Feature installation script