rename explicit span API

src/core/collector.ml

@@ -31,15 +31,15 @@ module type S = sig
       to be efficient to implement in async contexts.
      @since NEXT_RELEASE *)
 
-  val enter_explicit_span :
-    surrounding:explicit_span option ->
+  val enter_manual_span :
+    parent:explicit_span option ->
     ?__FUNCTION__:string ->
     __FILE__:string ->
     __LINE__:int ->
     data:(string * user_data) list ->
     string ->
     explicit_span
-  (** Enter an explicit span. Surrounding scope is provided by [surrounding],
+  (** Enter an explicit span. Surrounding scope, if any, is provided by [parent],
       and this function can store as much metadata as it wants in the hmap
       in the {!explicit_span}'s [meta] field.
 
@@ -48,7 +48,7 @@ module type S = sig
       everything can be transmitted in the {!explicit_span}.
       @since NEXT_RELEASE *)
 
-  val exit_explicit_span : explicit_span -> unit
+  val exit_manual_span : explicit_span -> unit
   (** Exit an explicit span.
       @since NEXT_RELEASE *)
 

src/core/trace_core.ml

@@ -27,25 +27,32 @@ let[@inline] with_span ?__FUNCTION__ ~__FILE__ ~__LINE__ ?data name f =
     with_span_collector_ collector ?__FUNCTION__ ~__FILE__ ~__LINE__ ?data name
       f
 
-let enter_explicit_span_collector_ (module C : Collector.S) ~surrounding
+let enter_explicit_span_collector_ (module C : Collector.S) ~parent
     ?__FUNCTION__ ~__FILE__ ~__LINE__ ?(data = fun () -> []) name :
     explicit_span =
   let data = data () in
-  C.enter_explicit_span ~surrounding ?__FUNCTION__ ~__FILE__ ~__LINE__ ~data
-    name
+  C.enter_manual_span ~parent ?__FUNCTION__ ~__FILE__ ~__LINE__ ~data name
 
-let[@inline] enter_explicit_span ~surrounding ?__FUNCTION__ ~__FILE__ ~__LINE__
+let[@inline] enter_manual_sub_span ~parent ?__FUNCTION__ ~__FILE__ ~__LINE__
     ?data name : explicit_span =
   match A.get collector with
   | None -> Collector.dummy_explicit_span
   | Some coll ->
-    enter_explicit_span_collector_ coll ~surrounding ?__FUNCTION__ ~__FILE__
+    enter_explicit_span_collector_ coll ~parent:(Some parent) ?__FUNCTION__
+      ~__FILE__ ~__LINE__ ?data name
+
+let[@inline] enter_manual_toplevel_span ?__FUNCTION__ ~__FILE__ ~__LINE__ ?data
+    name : explicit_span =
+  match A.get collector with
+  | None -> Collector.dummy_explicit_span
+  | Some coll ->
+    enter_explicit_span_collector_ coll ~parent:None ?__FUNCTION__ ~__FILE__
       ~__LINE__ ?data name
 
-let[@inline] exit_explicit_span espan : unit =
+let[@inline] exit_manual_span espan : unit =
   match A.get collector with
   | None -> ()
-  | Some (module C) -> C.exit_explicit_span espan
+  | Some (module C) -> C.exit_manual_span espan
 
 let message_collector_ (module C : Collector.S) ?span ?(data = fun () -> []) msg
     : unit =

src/core/trace_core.mli

@@ -31,11 +31,11 @@ val with_span :
     work for synchronous, direct style code. Monadic concurrency, Effect-based
     fibers, etc. might not play well with this style of spans on some
     or all backends. If you use cooperative concurrency,
-    see {!enter_explicit_span}.
+    see {!enter_manual_span}.
 *)
 
-val enter_explicit_span :
-  surrounding:explicit_span option ->
+val enter_manual_sub_span :
+  parent:explicit_span ->
   ?__FUNCTION__:string ->
   __FILE__:string ->
   __LINE__:int ->
@@ -43,14 +43,28 @@ val enter_explicit_span :
   string ->
   explicit_span
 (** Like {!with_span} but the caller is responsible for
-      providing the [surrounding] context, and carry the resulting
-      {!explicit_span} to  the matching {!exit_explicit_span}. 
-      @since NEXT_RELEASE *)
+    providing the [parent] context, and carry the resulting
+    {!explicit_span} to  the matching {!exit_manual_span}. 
+    @since NEXT_RELEASE *)
 
-val exit_explicit_span : explicit_span -> unit
+val enter_manual_toplevel_span :
+  ?__FUNCTION__:string ->
+  __FILE__:string ->
+  __LINE__:int ->
+  ?data:(unit -> (string * user_data) list) ->
+  string ->
+  explicit_span
+(** Like {!with_span} but the caller is responsible for carrying this
+    [explicit_span] around until it's exited with {!exit_manual_span}.
+    The span can be used as a parent in {!enter_manual_sub_span}.
+    @since NEXT_RELEASE *)
+
+val exit_manual_span : explicit_span -> unit
 (** Exit an explicit span. This can be on another thread, in a
     fiber or lightweight thread, etc. and will be supported by backends
     nonetheless.
+    The span can be obtained via {!enter_manual_sub_span} or
+    {!enter_manual_toplevel_span}.
     @since NEXT_RELEASE *)
 
 val message :

src/tef/trace_tef.ml

@@ -342,11 +342,11 @@ let collector ~out () : collector =
 
       Fun.protect ~finally (fun () -> f span)
 
-    let enter_explicit_span ~(surrounding : explicit_span option)
-        ?__FUNCTION__:_ ~__FILE__:_ ~__LINE__:_ ~data name : explicit_span =
+    let enter_manual_span ~(parent : explicit_span option) ?__FUNCTION__:_
+        ~__FILE__:_ ~__LINE__:_ ~data name : explicit_span =
       (* get the id, or make a new one *)
       let id =
-        match surrounding with
+        match parent with
         | Some m -> Meta_map.find_exn key_async_id m.meta
         | None -> A.fetch_and_add span_id_gen_ 1
       in
@@ -359,7 +359,7 @@ let collector ~out () : collector =
           Meta_map.(empty |> add key_async_id id |> add key_async_name name);
       }
 
-    let exit_explicit_span (es : explicit_span) : unit =
+    let exit_manual_span (es : explicit_span) : unit =
       let id = Meta_map.find_exn key_async_id es.meta in
       let name = Meta_map.find_exn key_async_name es.meta in
       let time_us = now_us () in

test/t1.ml

@@ -7,8 +7,7 @@ let run () =
   for _i = 1 to 50 do
     Trace.with_span ~__FILE__ ~__LINE__ "outer.loop" @@ fun _sp ->
     let pseudo_async_sp =
-      Trace.enter_explicit_span ~surrounding:None ~__FILE__ ~__LINE__
-        "fake_sleep"
+      Trace.enter_manual_toplevel_span ~__FILE__ ~__LINE__ "fake_sleep"
     in
 
     for _j = 2 to 5 do
@@ -21,14 +20,14 @@ let run () =
       if _j = 2 then (
         (* fake micro sleep *)
         let _sp =
-          Trace.enter_explicit_span ~surrounding:(Some pseudo_async_sp)
-            ~__FILE__ ~__LINE__ "sub-sleep"
+          Trace.enter_manual_sub_span ~parent:pseudo_async_sp ~__FILE__
+            ~__LINE__ "sub-sleep"
         in
         Thread.delay 0.005;
-        Trace.exit_explicit_span _sp
+        Trace.exit_manual_span _sp
       ) else if _j = 3 then
         (* pretend some task finished. Note that this is not well scoped wrt other spans. *)
-        Trace.exit_explicit_span pseudo_async_sp
+        Trace.exit_manual_span pseudo_async_sp
     done
   done