core-trace-experimental: add @withSpan macro

[iRevive]

An experimental implementation of the #550.
OpenTelemetry Java offers similar functionality using reflections and AOP https://opentelemetry.io/docs/languages/java/automatic/annotations/.

Before we start

The functionality exists in a separate otel4s-core-trace-experimental module.

How it works

The body of a method annotated with @withSpan will be wrapped into a span:

@withSpan
def findUser(
  @spanAttribute userId: Long, 
  @spanAttribute("user.hash") hash: String
): F[User] = ???

// expands into

def findUser(
    userId: Long, 
    hash: String
): F[User] = 
  Tracer[F].span(
    "findUser", 
    Attribute("userId", userId), Attribute("user.hash", hash)
  ).surround(???)

The macro works with variables too:

@withSpan("custom name")
val findUser: IO[User] = ???

// expands into

val findUser: IO[User] = 
  Tracer[IO].span("custom_name").surround(???)

Summary

Pros

1. Separate tracing from the business layer
2. Relatively easy to add tracing to the existing methods
3. Generates boilerplate for you: the name of the span and attributes can be derived automatically
4. Since the result type remains the same, IDEs should be fine

Cons

1. It's macros
2. @spanAttribute contributes to the visual noise
3. Spring-like

Questions

1) Why @withSpan and @spanAttribute instead of @span and @attribute?

If I recall correctly, problems can arise in case-insensitive systems because we already have Span and Attribute.

However, if that is not the case, I would prefer @span and @attribute.

2) Should the macro capture source information?

We can easily add source attributes to the span, such as Attribute("source.file", "some/path/Service.scala") and Attribute("source.line", 123L).

[bcarter97]

Since KeySelect is sealed there's no way to define a spanAttribute for an unsupported type, normally we'd create an Attribute manually like

case class Foo(value: String)
val attribute = Attribute("foo.value", foo.value)

This means we can't use the macro at all if we require one attribute that is unsupported. Would it be sensible to expose some way of contramapping an existing KeySelect?

[bcarter97]

Though thinking about it still won't be possible without some other function from value => key type 😢

[iRevive]

Valid points. The macro wouldn't work with newtypes/type aliases.

I guess we can provide some utility methods to lift arbitrary types into the Attribute.

[NthPortal]

sorry it's taken me so long to have a look at this; I'll try to give a proper review this coming week

[NthPortal]

I'm not really familiar enough with macros (annotation or otherwise) to give the implementations a confident approval, but the tests look correct and quite thorough to me. Nice work!

I don't quite understand the concern about case-insensitive name collision; they're in separate directories, so I'm not clear on how it would be a problem, and would personally prefer the shorter/simpler names

[NthPortal]

should this be marked @compileTimeOnly as well?

[iRevive]

Closing in favor of typelevel/otel4s-experimental#1.