From 50b4691ab695f92cba530b0e8b7657c13e2cdfd0 Mon Sep 17 00:00:00 2001 From: Simon Cruanes Date: Thu, 3 Aug 2023 14:54:46 -0400 Subject: [PATCH] rename explicit span API --- src/core/collector.ml | 8 ++++---- src/core/trace_core.ml | 21 ++++++++++++++------- src/core/trace_core.mli | 28 +++++++++++++++++++++------- src/tef/trace_tef.ml | 8 ++++---- test/t1.ml | 11 +++++------ 5 files changed, 48 insertions(+), 28 deletions(-) diff --git a/src/core/collector.ml b/src/core/collector.ml index f17be5d..a0b772d 100644 --- a/src/core/collector.ml +++ b/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 *) diff --git a/src/core/trace_core.ml b/src/core/trace_core.ml index ce22888..1984dfe 100644 --- a/src/core/trace_core.ml +++ b/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 = diff --git a/src/core/trace_core.mli b/src/core/trace_core.mli index 4b31642..d630081 100644 --- a/src/core/trace_core.mli +++ b/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 : diff --git a/src/tef/trace_tef.ml b/src/tef/trace_tef.ml index b06be27..756d577 100644 --- a/src/tef/trace_tef.ml +++ b/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 diff --git a/test/t1.ml b/test/t1.ml index c908fb8..1fd80c6 100644 --- a/test/t1.ml +++ b/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