Verbosity of addAttributes vs. Natchez

[rossabaker]

I'm staring at a diff that looks like this:

-                  NatchezTrace[F].put(
-                    reasonKey -> "header validation failed",
-                    "header" -> header.value,
-                  )
+                  Tracer[F].currentSpanOrNoop.flatMap(_.addAttributes(
+                    Attribute(reasonKey, "header validation failed"),
+                    Attribute("header", header.value),
+                  ))

The philosophy has been to adhere to the Otel spec, which I think it good. But it's awfully low level. I'm wondering how early adopters are dealing with this.

• Staying at this low level?
• Using some helper I overlooked?
• Rolling their own helpers?

I think the minimalism is great in libraries: less surface area to cause breaking changes. I'm concerned about selling this API to app developers without a bit of sugar, though.

[iRevive]

At $work, the team almost always makes a wrapper over Tracer to provide a more expressive API.

I guess we can forward the majority of the Span methods (e.g., addAttributes, addEvent, recordException, etc.).

[rossabaker]

The two things that stick out as noisier in my example are:

• The need to flatMap
• Attribute vs. ->

Forwarding methods are trivial and don't leave much room for interpretation, but if two smart Scala developers tried to adapt varargs tuples to Attributes, I bet we'd get two incompatible solutions. I'm a little scared to include anything opinionated that isn't an Opinion Of The Specification.

[iRevive]

We can make a separate module to manage extensions there. e.g.: "org.typelevel" %%% "otel4s-syntax" % "x.y.z.".

package org.typelevel.otel4s.trace

object syntax {

  implicit class TracerOps[F[_]](private val tracer: Tracer[F]) extends AnyVal {
    def addAttributes(attributes: Attributes)(implicit F: FlatMap[F]): F[Unit] = 
      tracer.currentSpanOrNoop.flatMap(_.addAttributes(attributes))
  }

}

The core module will comply with the spec, and we can still offer some suggar. But keeping an import around could be annoying for a user.

[rossabaker]

I had a nice chat with @NthPortal yesterday, who reminded me of the benefits of defining AttributeKeys as constants and applying them. It's even a little more verbose than the tuple for one-off attributes, but it's a win for repeated attributes, and so many of them are already in the library we provide. I think perhaps the key here is just learning to think a little bit more about otel4s in its own right, and not thinking in terms of making it look like a word-for-word translation from Natchez.

[dimitarg]

Another source of verbosity I see, or rather decrease in ergonomics is the set of attribute key types is hardcoded (for spec / java interop reasons, I assume).

With natchez, given final case class MyId(value: Int), if I've provided a TraceableValue instance, I can say Trace[F].put("id" -> id), whereas in otel4s that's span.addAttribute(Attribute("id", id.value.toLong)). This becomes a nuisance for a codebase heavily utilising opaque newtypes / refinement types etc.

I guess this can be overcome if you introduce your own syntax as above, and your own conversion typeclass to be used by it, since it's not possible as it currently stands to implement contramap for AttributeKey itself.

Given what's discussed here. I think providing a syntax module for otel4s might be useful, even if it's an external / third-party project.

[iRevive]

Hey, I've explored a more flexible AttributeKey definition via a custom KeySelect. Here is a draft API:

object MyId {
  implicit val keySelectMyId: KeySelect[MyId] = KeySelect.Lift.instance(_.id.toLong)
}

val attribute: Attribute[Long] = Attribute("my.id", MyId(123))

I will make a PR once I polish a few more things.

[iRevive]

Another thing that I was playing with:

object MyId {
  implicit val keySelectMyId: KeySelect[MyId] = KeySelect.Lift.instance(_.id.toLong)
  implicit val makeMyId: Attribute.Make[MyId, Long] = Attribute.Make.instance("my.id")
}

Tracer[IO].span("name", MyId(123)).use(...) // implicit conversion to an attribute

[NthPortal]

how does val attribute: Attribute[Long] = Attribute("my.id", MyId(123)) know the return type parameter of Long?

[NthPortal]

@iRevive idk how similar this is to your current idea, but what if we had:

trait AttributeMaker[In, Out] { // name bikeshed-able, could be `Attribute.Make`
  def apply(value: In): Attribute[Out]
}
trait AttributeKey[A] extends AttributeMaker[A, A] {
  def comap[In](f: In => A): AttributeMaker[In, A] = // I think that's the right name?
    value => apply(f(value)) // I have no idea if `apply(f(_))` works, I'm not in an IDE
}

[iRevive]

@NthPortal here is a prototype: #912.
I was using an abstract type member to specify the projection type.

It works nicely in Scala 3 and has some issues in Scala 2. I gave up on it for now.