mirror of
https://github.com/ocaml-tracing/ocaml-trace.git
synced 2026-03-09 20:33:34 -04:00
e50175298b
These spans require the user to pass the surrounding span, if any, when entering a new span. They use the information inside (which is collector specific) to track what asynchronous task is currently being executed. Wrappers around `trace`, specific to an async library (e.g. Eio, lwt, Async, etc.) can then smooth this over by providing a `with_async_span` construct that uses some implicit contextual storage to carry the `surrounding` scope around.
71 lines
2.1 KiB
OCaml
71 lines
2.1 KiB
OCaml
(** A global collector.
|
|
|
|
The collector, if present, is responsible for collecting messages
|
|
and spans, and storing them, recording them, forward them, or
|
|
offering them to other services and processes.
|
|
*)
|
|
|
|
open Types
|
|
|
|
let dummy_span : span = Int64.min_int
|
|
|
|
let dummy_explicit_span : explicit_span =
|
|
{ span = dummy_span; meta = Meta_map.empty }
|
|
|
|
(** Signature for a collector.
|
|
|
|
This is only relevant to implementors of tracing backends; to instrument
|
|
your code you only need to look at the {!Trace} module. *)
|
|
module type S = sig
|
|
val enter_span :
|
|
?__FUNCTION__:string ->
|
|
__FILE__:string ->
|
|
__LINE__:int ->
|
|
data:(string * user_data) list ->
|
|
string ->
|
|
span
|
|
(** Enter a new span. *)
|
|
|
|
val exit_span : span -> unit
|
|
(** Exit given span. It can't be exited again. Spans must follow
|
|
a strict stack discipline on each thread. *)
|
|
|
|
val enter_explicit_span :
|
|
surrounding: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],
|
|
and this function can store as much metadata as it wants in the hmap
|
|
in the {!explicit_span}'s [meta] field.
|
|
|
|
This means that the collector doesn't need to implement contextual
|
|
storage mapping {!span} to scopes, metadata, etc. on its side;
|
|
everything can be transmitted in the {!explicit_span}.
|
|
@since NEXT_RELEASE *)
|
|
|
|
val exit_explicit_span : explicit_span -> unit
|
|
(** Exit an explicit span.
|
|
@since NEXT_RELEASE *)
|
|
|
|
val message : ?span:span -> data:(string * user_data) list -> string -> unit
|
|
(** Emit a message with associated metadata. *)
|
|
|
|
val name_thread : string -> unit
|
|
(** Give a name to the current thread. *)
|
|
|
|
val name_process : string -> unit
|
|
(** Give a name to the current process. *)
|
|
|
|
val counter_int : string -> int -> unit
|
|
(** Integer counter. *)
|
|
|
|
val counter_float : string -> float -> unit
|
|
(** Float counter. *)
|
|
|
|
val shutdown : unit -> unit
|
|
(** Shutdown collector, possibly waiting for it to finish sending data. *)
|
|
end
|