Enabling Tracing

Our SDK supports collecting distributed traces via OpenCensus. To this end you need to configure the server side used to collect the relevant data (provide a "Zipkin via TLS" endpoint with Basic Auth reachable from Internet, e.g. by Jaeger tracing component) and to explicitly enable tracing on MC level. This needs to happen after the Start event has been processed.

So, right after receiving the result for your Start event (i.e. either a StartActivationUserIdAndCodeOnly event or a StartLogin event) is a good occasion to configure and possibly enable tracing. To this end, send a Configuration event which sets

• the exporterURL of the server collecting the trace data,
• the credentials (Basic Auth "userName" and "password") needed to access it and
• the list of trusted TLS server certificates in PEM format. See Trust Store Configuration for details on which certificates to put into the trust store.

Then, send an EnableOpenCensusTracing event (which takes a boolean parameter) to enable or disable the tracing. Note that neither the Configuration event nor the EnableOpenCensusTracing event trigger a response event, so all you need to do is to just send those two events.

Every EventFrameworkEvent has the methods setTraceContext and getTraceContext. You can create your own TraceContext object and set it in a particular event via setTraceContext. You can use getTraceContext to get some existing TraceContext and reuse it for other event calls belonging to the same flow.

iOS/Swift

For Swift, the following snippet can be used to enable tracing:

Enable Tracing (Swift)

func configureOpenCensusTracing(openCensusConfig: OpenCensusConfig) {
    let event = KSMConfigurationEvent(exporterUrl: openCensusConfig.exporterUrl,
                                      userName: openCensusConfig.userName,
                                      password: openCensusConfig.password,
                                      serverCertificate: openCensusConfig.cert)
    masterControllerAdapter.sendEvent2MasterController(event)
}

func enableOpenCensusTracing(enable: Bool){
    let event = KSMEnableOpenCensusTracingEvent(tracingEnabled: enable)
    masterControllerAdapter.sendEvent2MasterController(event)
}

Android/Kotlin

For Kotlin, we have created a dedicated method in the MCHandler class of our example app to trigger this event. Below is the code snippet.

Enable Tracing (Kotlin)

fun triggerConfigurationEvent(
	exporterUrl: String?,
	username: String?,
	password: String?,
	serverCertificate: ByteArray?
) {
	mcEventHandler?.postEvent(
        ConfigurationEvent(
            exporterUrl,
            username,
            password,
            serverCertificate
        )
    )?.then {
        // ConfigurationEvent does not have a response event
        triggerEnableOpenCensusTracingEvent(true)
    }
}

fun triggerEnableOpenCensusTracingEvent(tracingEnabled: Boolean) {
    mcEventHandler?.postEvent((EnableOpenCensusTracingEvent(tracingEnabled)))
    // EnableOpenCensusTracingEvent does not have a response event
}