trace: add @span macro

[iRevive]

An experimental implementation of the typelevel/otel4s#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 @span will be wrapped into a span:

@span
def findUser(
  @attribute userId: Long, 
  @attribute("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:

@span("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. @attribute 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).

[iRevive]

@NthPortal I moved the PR to the new repo. I also renamed @withSpan to @span. Let's see how it goes.

[iRevive]

typelevel/otel4s#675 (review)

[iRevive]

@NthPortal I guess we can add @compileTimeOnly annotation there, but then I need to change the expand logic slightly.

I will check.