[Do not merge] Trace API playground

[iRevive]

This branch contains various experiments with OpenTelemetry tracing.

To simply the review process I made two different PRs:

1. Define API Define tracing API #36
2. Implementation Implement tracing API #37

Currently, the state is stored in IOLocal. This approach has several drawbacks:

• Counter-intuitive behavior with interruptScope and IOLocals fs2#2842
• IO.race doesn't propagate winner's IOLocal context cats-effect#3100

The checklist from #11

• Provide access to spanId and traceId from Trace[F]
• Allow creating a new root span from Trace[F]
• Allow running an effect without tracing
• Proper tracing of a Resource
• Ability to trace fs2.Stream
• Memory pressure when Trace is not used
• Richer API

[iRevive]

Examples:

examples/src/main/scala/com/example/tracing/JaegerTracing.scala

Resource span

tracer
  .resourceSpan("resource-span")(makeImageLookup(tracer))
  .use { case Span.Res(lookup) =>
    lookup.exists("my-image")
  }

Stream span

Stream
  .resource(tracer.resourceSpan("stream-span")(Resource.unit))
  .flatMap(_ => Stream.emits(Seq(1, 2, 3)))
  .evalMap(r => tracer.span(s"span-$r").surround(IO.unit))
  .compile
  .drain

Stream span is not ideal, but at least it works out of the box and does not require the fs2 dependency.

[iRevive]

The change set is quite big and it's hard to review it.
I can try to split it into smaller pieces. Two different PRs come to mind:

1. Solely API definitions
2. Implementation and tests

[janstenpickle]

I realise this is WIP so not sure if you plan to change this or if the Otel spec has changed, but these are usually represented as byte arrays; e.g TraceId and SpanId in t4c. It would be good to be able to access these directly rather than just the string representation.

Apologies if I've jumped the gun and you're going to change these, or I've missed something and they're represented elsewhere!

[iRevive]

It's a draft version and my gut feeling says there will be a lot of changes :)
It would be interesting for me to hear your opinion about the current API.

Open Telemetry has the following info in span context:

String getTraceId();
byte[] getTraceIdBytes();
String getSpanId();
byte[] getSpanIdBytes();
boolean isSampled();
TraceFlags getTraceFlags();
TraceState getTraceState();
boolean isValid();
boolean isRemote();

I believe we can incorporate the majority of attributes.

[armanbilge]

I'd be happy to see scodec-bits ByteVector used for byte arrays :) it's a stable dependency used in fs2-core and beyond.

[janstenpickle]

ah yeah, that makes sense. What we do in t4c is have Show instances for TraceId which makes those a bit more FP'y.

Also I made the the isSampled return an ADT that can turn into a boolean, purely because everyone (including myself) kept getting confused as to what true meant when it came to sampling!

In terms of the trace context in t4c it more closely follows the W3C standard, so in terms of structure probably doesn't align very well with the Otel spec.

[iRevive]

It would be nice to make it configurable. i.e. https://github.com/trace4cats/trace4cats/blob/master/modules/kernel/src/main/scala/trace4cats/kernel/ErrorHandler.scala

[iRevive]

OpenTelemetry requires it to be a realTime rather than monotonic

[iRevive]

I'm closing this PR since it's not relevant anymore.