@span annotation using macro-annotations

[swapdonkey]

Hi,
Otel4s is looking very promising. A nice feature would be using a @span macro-annotation which would wrap functions in a span. Also a @attribute for function parameters would also be beneficial. Do you think this would be possible with the current implementation?

[iRevive]

I'm not a big fan of macro annotations, but this idea sounds interesting.

@span
def doWork(@attribute("user.id") userId: String): F[Unit] = ???

@span(name = "customSpanName")
def internal: F[Unit] = ???

should be transformed into:

def doWork(userId: String): F[Unit] = 
  Tracer[F].span("doWork", Attribute("user.id", userId)).use { _ => ??? }
  
def internal: F[Unit] =
  Tracer[F].span("customSpanName").use { _ => ??? }

---

The idea fits the 'experimental' category. I guess we can have otel4s-core-{x}-experimental modules for such experimental functionality, for example: otel4s-core-trace-experimental and otel4s-core-metrics-experimental.

Once we consider the functionality stable, we can move it to the core module.

[iRevive]

@rossabaker

Would an experimental module be explicitly exempt from binary compatibility guarantees?

yes, that was the idea. The otel4s-core, otel4s-sdk, otel4s-oteljava modules wouldn't depend on it, so it must be added explicitly as a dependency.

Perhaps to make things easier, we can have a separate repo with its own release cycle?

[rossabaker]

That's great, if you don't mind the administrative overhead. Turning off MiMa on that module and putting a loud warning in the docs is also fine. We just wouldn't want this feature causing churn downstream.

[iRevive]

@rossabaker I don't mind. I can create a repo within the Typelevel org, right? Would the otel4s-experimental name fit?

[rossabaker]

Sorry for the delay. I get hundreds of crap notifications a day and can't keep up with the important ones.

I created the repo and added the otel4s team as a maintainer.

[iRevive]

Thanks!

[iRevive]

@NthPortal @mpilquist @rossabaker what's your opinion on this topic?

[NthPortal]

my thoughts are above, but for completeness, I'm in favour

[jatcwang]

I'm not a big fan of macro annotations in general. In this case in particular I don't feel the (IMO very small) convience is worth the cost.

At work we define an extension method on F[A] called markSpan to make it easy to start a new span like so:

(for
  _ <- doSomeWork1.markSpan("child1")
  _ <- doSomeWork2.markSpan("child2")
yield ()).markSpan("root")

Alternatively we can make markSpan a regular function too for those that prefer the span name to be front and center.

[swapdonkey]

I'm interested to know your reasons for why you prefer to not use macro annotations? We use this approach in a custom Open Tracing api ,which we're looking to replace with a OTEL Api hence looking at Otel4s. When we need to we'll use the tracer directly but where we don't need to the annotations keep a clean separation between the tracing and business logic.

[mpilquist]

I'm not fond of them either -- partially due to some now ancient history with Spring. I strongly prefer "first-class" language constructs over annotations that change runtime behavior (whether via AOP or via macro expansion).

No concerns over providing an optional macro api for those that prefer the annotation style.

[jatcwang]

Because my team haven't really found the lack of separation to be problematic in understanding the code. It's much easier to go-to-definition on a helper method and understand what's happening than a macro annoatation.

I find them inflexible and doesn't really compose well because it's not really code. Given that I haven't really had any issue understanding business logic code without annotations, the cost isn't worth it for me. But of course that's just my own experience :)

[zmccoy]

@mpilquist Sums up my opinion on this as well. I'd much prefer to deal with language constructs especially when this ends up permeating all teams at an org.

[bpholt]

With Natchez, I've been using cats-tagless to transform untraced algebras to traced algebras using its AOP mechanism. There's quite a bit more context in the readme of the supporting library we published. I haven't looked into how it will port to otel4s yet, but I'm hoping to do so soon now that things are stabilizing. Something like that might be another alternative.

[iRevive]

I made a draft implementation, please take a look: #675.

[iRevive]

@swapdonkey the functionality is available here - https://github.com/typelevel/otel4s-experimental.

build.sbt:

libraryDependencies ++= Seq(
  "org.typelevel" %%% "otel4s-experimental-trace" % "0.2.0"
)

code:

import org.typelevel.otel4s.experimental.{attribute, span}

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

[swapdonkey]

Many thanks @iRevive we'll try it out