Move SpanRunner outside SpanBuilderImpl

build.sbt

@@ -1,3 +1,5 @@
+import com.typesafe.tools.mima.core._
+
 ThisBuild / tlBaseVersion := "0.1"
 
 ThisBuild / organization := "org.typelevel"
@@ -179,6 +181,26 @@ lazy val `java-trace` = project
       "io.opentelemetry" % "opentelemetry-sdk-testing" % OpenTelemetryVersion % Test,
       "org.typelevel" %%% "cats-effect-testkit" % CatsEffectVersion % Test,
       "co.fs2" %% "fs2-core" % FS2Version % Test
+    ),
+    mimaBinaryIssueFilters ++= Seq(
+      ProblemFilters.exclude[MissingClassProblem](
+        "org.typelevel.otel4s.java.trace.SpanBuilderImpl$Runner"
+      ),
+      ProblemFilters.exclude[MissingClassProblem](
+        "org.typelevel.otel4s.java.trace.SpanBuilderImpl$Runner$"
+      ),
+      ProblemFilters.exclude[MissingClassProblem](
+        "org.typelevel.otel4s.java.trace.SpanBuilderImpl$TimestampSelect"
+      ),
+      ProblemFilters.exclude[MissingClassProblem](
+        "org.typelevel.otel4s.java.trace.SpanBuilderImpl$TimestampSelect$"
+      ),
+      ProblemFilters.exclude[MissingClassProblem](
+        "org.typelevel.otel4s.java.trace.SpanBuilderImpl$TimestampSelect$Delegate$"
+      ),
+      ProblemFilters.exclude[MissingClassProblem](
+        "org.typelevel.otel4s.java.trace.SpanBuilderImpl$TimestampSelect$Explicit$"
+      )
     )
   )
 

core/trace/src/main/scala/org/typelevel/otel4s/trace/Span.scala

@@ -75,6 +75,8 @@ trait Span[F[_]] extends SpanMacro[F] {
     *
     * Only the timing of the first end call for a given span will be recorded,
     * the subsequent calls will be ignored.
+    *
+    * The end timestamp is based on the `Clock[F].realTime`.
     */
   final def end: F[Unit] =
     backend.end

core/trace/src/main/scala/org/typelevel/otel4s/trace/SpanBuilder.scala

@@ -180,10 +180,7 @@ object SpanBuilder {
 
       def addAttributes(attributes: Attribute[_]*): Builder = this
 
-      def addLink(
-          spanContext: SpanContext,
-          attributes: Attribute[_]*
-      ): Builder = this
+      def addLink(ctx: SpanContext, attributes: Attribute[_]*): Builder = this
 
       def root: Builder = this
 
@@ -196,7 +193,7 @@ object SpanBuilder {
 
       def withStartTimestamp(timestamp: FiniteDuration): Builder = this
 
-      def build = new SpanOps[F] {
+      def build: SpanOps.Aux[F, Result] = new SpanOps[F] {
         type Result = Res
 
         def startUnmanaged(implicit ev: Result =:= Span[F]): F[Span[F]] =

core/trace/src/main/scala/org/typelevel/otel4s/trace/SpanOps.scala

@@ -25,6 +25,9 @@ trait SpanOps[F[_]] {
     * This strategy can be used when it's necessary to end a span outside of the
     * scope (e.g. async callback). Make sure the span is ended properly.
     *
+    * If the start timestamp is not configured explicitly in a builder, the
+    * `Clock[F].realTime` is used to determine the timestamp.
+    *
     * Leaked span:
     * {{{
     * val tracer: Tracer[F] = ???
@@ -55,9 +58,13 @@ trait SpanOps[F[_]] {
     * The finalization strategy is determined by [[SpanFinalizer.Strategy]]. By
     * default, the abnormal termination (error, cancelation) is recorded.
     *
+    * If the start timestamp is not configured explicitly in a builder, the
+    * `Clock[F].realTime` is used to determine the timestamp.
+    *
+    * `Clock[F].realTime` is always used as the end timestamp.
+    *
     * @see
     *   default finalization strategy [[SpanFinalizer.Strategy.reportAbnormal]]
-    *
     * @example
     *   {{{
     * val tracer: Tracer[F] = ???
@@ -69,8 +76,33 @@ trait SpanOps[F[_]] {
     */
   def use[A](f: Result => F[A]): F[A]
 
+  /** Starts a span and ends it immediately.
+    *
+    * A shortcut for:
+    * {{{
+    * val tracer: Tracer[F] = ???
+    * val ops: SpanOps.Aux[F, Span[F]] = tracer.spanBuilder("auto-span").build
+    * ops.use(_ => F.unit) <-> ops.use_
+    * }}}
+    *
+    * @see
+    *   See [[use]] for more details regarding lifecycle strategy
+    */
   def use_ : F[Unit]
 
+  /** Starts a span, runs `fa` and ends the span once `fa` terminates, fails or
+    * gets interrupted.
+    *
+    * A shortcut for:
+    * {{{
+    * val tracer: Tracer[F] = ???
+    * val ops: SpanOps.Aux[F, Span[F]] = tracer.spanBuilder("auto-span").build
+    * ops.use(_ => fa) <-> ops.surround(fa)
+    * }}}
+    *
+    * @see
+    *   See [[use]] for more details regarding lifecycle strategy
+    */
   def surround[A](fa: F[A]): F[A]
 }
 

java/trace/src/main/scala/org/typelevel/otel4s/java/trace/SpanBackendImpl.scala

@@ -19,6 +19,7 @@ package java
 package trace
 
 import cats.effect.Sync
+import cats.syntax.flatMap._
 import io.opentelemetry.api.trace.{Span => JSpan}
 import io.opentelemetry.api.trace.{StatusCode => JStatusCode}
 import org.typelevel.otel4s.Attribute
@@ -89,7 +90,7 @@ private[java] class SpanBackendImpl[F[_]: Sync](
     }
 
   private[otel4s] def end: F[Unit] =
-    Sync[F].delay(jSpan.end())
+    Sync[F].realTime.flatMap(now => end(now))
 
   private[otel4s] def end(timestamp: FiniteDuration): F[Unit] =
     Sync[F].delay(jSpan.end(timestamp.length, timestamp.unit))