Add ability to perform basic custom instrumentation with Transaction and Spans

[buenaflor]

This would allow developers to create custom transactions and spans in their code to capture information about their application's performance and behavior.

At the very least support:

• Transaction
• Span
• startTransaction()
• startChild()
• getSpan()
• tracesSampleRate option
• tracesSampler option

Align implementation with:

• https://docs.sentry.io/platforms/java/performance/instrumentation/custom-instrumentation/
• https://docs.sentry.io/platforms/apple/guides/ios/performance/instrumentation/custom-instrumentation/

[Legion2]

Please also provide withTrace and withSpan kotlin extensions which make it easy to instrument code with an concise and kotin idomatic syntax. These extensions should also support kotlin coroutines and propagate context in coroutines correctly. I started an implementation my self, here is what I did sofar:

data class SpanContext(val span: Span) : AbstractCoroutineContextElement(SpanContext) {
    companion object Key : CoroutineContext.Key<SpanContext>
}

fun CoroutineContext.currentSpan(): Span {
    return get(SpanContext)?.span ?: throw IllegalStateException("No active Span in context")
}

suspend fun <T> withTrace(
    name: String,
    spanName: String,
    block: suspend CoroutineScope.() -> T
): T {
    val trace = startTrace(name, spanName)
    return withSpan(trace, block)
}

suspend fun <T> withSpan(name: String, block: suspend CoroutineScope.() -> T): T {
    val span = currentCoroutineContext().currentSpan()
    val childSpan = span.startChild(name)
    return withSpan(childSpan, block)
}

suspend fun <T> withSpan(span: Span, block: suspend CoroutineScope.() -> T): T {
    return try {
        withContext(SpanContext(span), block)
    } catch (e: Throwable) {
        if (e is CancellationException) {
            span.setStatus("cancelled")
        } else {
            span.setThrowable(e)
            span.setStatus("error")
        }
        throw e
    } finally {
        span.finish()
    }
}

This allows to add the context to the coroutine context, which ensures it is propagates in suspend code with structured concurrency. This means the child span must no be propagated manually. The extension functions allow to instrument code as follows:

suspend fun getData(): String {
  return withSpan("getData") {
    delay(1000)
    "foo"
  }
}

[buenaflor]

For anyone looking into custom instrumentation here is a small/basic snippet you could use for now

// in commonMain

interface SharedSentrySpan {
    fun startChild(operation: String): SharedSentrySpan
    fun finish()
}

expect fun startTransaction(name: String, operation: String): SharedSentrySpan

// in androidMain

class SentrySpanAdapter(private val span: io.sentry.ISpan): SharedSentrySpan {
    override fun startChild(operation: String): SharedSentrySpan {
        return SentrySpanAdapter(span.startChild(operation))
    }

    override fun finish() {
        span.finish()
    }
}

actual fun startTransaction(name: String, operation: String): SharedSentrySpan {
    return SentrySpanAdapter(io.sentry.Sentry.startTransaction(name, operation))
}

// in iosMain

class SentrySpanAdapter(private val span: cocoapods.Sentry.SentrySpanProtocol): SharedSentrySpan {
    override fun startChild(operation: String): SharedSentrySpan {
        return SentrySpanAdapter(span.startChildWithOperation(operation))
    }

    override fun finish() {
        span.finish()
    }
}

actual fun startTransaction(name: String, operation: String): SharedSentrySpan {
    return SentrySpanAdapter(cocoapods.Sentry.SentrySDK.startTransactionWithName(name, operation))
}