How to do inner spans manually

[tobias-]

I'm trying to make a simple example for how to do "inner" spans in Kotlin when using the javaagent.

I'm used to NewRelic, where their terminology calls it segments().

If I understand it correctly this will do an inner span in Java. From here
Snippet #1

    Span innerSpan = GlobalOpenTelemetry
        .getTracer("innerspanner")
        .spanBuilder("potentially slow block #1))
        // Parent will default to using already existing Span
        .startSpan()
    try (Scope scope = innerSpan.makeCurrent()) {
        // Potentially slow block
    } finally {
        innerSpan.end()
    }
    // Span will be restored from ThreadLocal on scope.close()?

AFAIK the above albeit verbose would work, but what confuses me is this line about it not working for Kotlin coroutines. I'm assuming the reason is a construct like the following?
Snippet #2

suspend fun method() {
    ... (same as above)
    innerSpan.makeCurrent().use {
        launch {
            // Potentially slow block
        }.join()
        // continuation is possibly in another Thread
    }
    // Span restored to the new (wrong?) Threads ThreadLocal on scope.close()? Is that incorrect?
}

and instead something like the following would work?
Snippet #3

suspend fun methodX() {
    ... (same as above)
    withContext(innerSpan.asContextElement()) {
        launch {
            // Potentially slow block
        }
        // continuing in other Thread
    }
    // Span restored to the new Threads ThreadLocal on scope.close()?
}

But what would I use if methodX isn't a suspend method? In that case I should use Snippet #2, right?

Second question is how @WithSpan works/doesn't work with kotlin-coroutines?

-- edit:

Thus far I've got the following methods. Would these work properly?

private val tracer = GlobalOpenTelemetry.getTracer("foobar")

fun <T> withSpan(spanName: String, block: () -> T): T {
    val span = tracer.spanBuilder(spanName)
        .startSpan()
    return try {
        span.makeCurrent()
            .use {
                block()
            }
    } finally {
        span.end()
    }
}


suspend fun <T> withSpanCtx(spanName: String, block: suspend () -> T): T {
    val span = tracer.spanBuilder(spanName)
        .startSpan()
    return try {
        withContext(span.asContextElement()) {
            block()
        }
    } finally {
        span.end()
    }
}

-- fixed the code to include span.end()

[jkwatson]

There are a lot of questions in here, @tobias- . I'm not a kotlin expert at all, so let me ask you... does it work properly?

If not, have you tried using the kotlin extension functions as suggested in the javadoc you referenced?

@WithSpan will only work with the auto-instrumentation agent, so that sounds like a question for their discussions.

[tobias-]

No, it does not work at all 😆 . 9h ago, I didn't know enough to be able to say why it didn't work, but it's very clear that I couldn't interact with the agents configuration in my very naive way (via GlobalOpenTelemetry), so I'll have to redirect my questions there. Thanks for your help.

[jkwatson]

ah, if you're using the agent, then yes, I would definitely recommend starting a discussion over in the instrumentation project on this topic. 👍

[anuraaga]

Hey @tobias- good to see you here :) As far as the Kotlin usage you mentioned, your understanding sounds spot-on, in a suspending function you need to use withContext due to the thread issues you mention, but in a non-suspending function, makeCurrent.use is appropriate (and the only thing that compiles heh). Let us know if there's better wording in the documentation to clarify this.

[anuraaga]

Ah and @WithSpan, I suspect can only work for non-suspending functions. That being said, I wouldn't be surprised if the agent tried to do something broken if it was applied to a suspending function, we'll need to check that.

[tobias-]

Hey @tobias- good to see you here :)

Good to see you here too =).

As far as the Kotlin usage you mentioned, your understanding sounds spot-on, in a suspending function you need to use withContext due to the thread issues you mention,

I'm not sure at all what happens here, it really depends on how the instrumentation handles the thread local and where it's stored.

but in a non-suspending function, makeCurrent.use is appropriate (and the only thing that compiles heh).

Yes, I noticed the same thing when I wrote the code =)

Let us know if there's better wording in the documentation to clarify this.

As I still don't understand it 100%, I can't suggest any changes. I've updated the methods to include the span.end() as per what @jkwatson said in open-telemetry/opentelemetry-java-instrumentation#1945. @anuraaga Could you please verify that I've used the span.end() and withContext {} etc correctly? I would be all for including methods with a similar signature in some place, especially for people not using the instrumentation (if there are any?).

Ah and @WithSpan, I suspect can only work for non-suspending functions. That being said, I wouldn't be surprised if the agent tried to do something broken if it was applied to a suspending function, we'll need to check that.

The good news is that the projects we're going to be using this on will most likely contain many edge-cases, so expect bug reports/PRs with failing test cases.