feat: telemetry coroutine extensions

[aajtodd]

Issue #

N/A

Description of changes

This PR expands the telemetry API with coroutine extensions that the actual generated SDK clients and runtime will mostly use.

• Adds a new ContextManager interface. This is used to bridge the gap between the external calling code/observability backend and the SDK notion of context which relies on coroutine context for API boundary propagation.
  • Consider this experimental for now as we figure out the best way to deal with some of the rubber meets the road issues around actually plugging in an observability backend like OTeL
• Adds coroutine extensions for logging, trace span creation, and propagation of Context, TelemetryProvider, etc.

Example Instrumentation

The following is a strawman example of what instrumenting an operation might look like. This will likely change and/or get abstracted to be less verbose/more reusable.

private suspend fun testOperation(provider: TelemetryProvider) {
    val tracer = provider.tracerProvider.getOrCreateTracer("S3")
    val currentContext = provider.contextManager.current()

    val telemetryCtx = TelemetryProviderContext(provider) + TelemetryContextElement(currentContext)
    val span = tracer.createSpan(
        "S3.GetObject",
        attributesOf {
            "rpc.method" to "GetObject"
            "rpc.service" to "S3"
        },
        SpanKind.CLIENT,
        currentContext,
    )

    withSpan(span, telemetryCtx) {
        span.setAttribute("rpc.system", "aws-api")
        testChild()
    }
}

private suspend fun testChild() {
    // FIXME - would require getting a tracer for child spans...
    // thats _ok_ but probably want to use an existing service client tracer instance if possible?
}

This leaves some open questions on how we want

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[sonarcloud]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
7 Code Smells

No Coverage information
0.0% Duplication

[ianbotsf]

Question: When getting a CancellationException, we'll skip setting the span status to ERROR but we'll still call recordException which will set the error attribute to true. Is this correct?

[aajtodd]

Nope good catch.

[aajtodd]

🤔 What should we do with a CancellationException? Should it result in any of the normal exception related attributes being set on a span? Should it record different attributes? Nothing at all?

I went looking for guidance but didn't find anything. I could see doing something like:

when (ex) {
    is CancellationException -> span.setAttribute("cancelled", true)
    else -> {
        span.setStatus(SpanStatus.ERROR)
        span.recordException(ex, true)
    }
}

Or just ignoring cancellation exceptions w.r.t span attributes.

[ianbotsf]

I suppose it depends on if we intend to complete canceled spans or not. Assuming we do intend to complete them, then I think marking something is important (your cancelled = true attribute is a good idea) but definitely not the exception...that's an implementation detail of the language/coroutines, not an indication of unexpected behavior in the code.

[aajtodd]

I'll fix this in next PR