mirror of
https://github.com/ocaml-tracing/ocaml-trace.git
synced 2026-03-09 12:23:32 -04:00
125 lines
3.8 KiB
OCaml
125 lines
3.8 KiB
OCaml
(** Trace. *)
|
|
|
|
include module type of Types
|
|
module Collector = Collector
|
|
module Meta_map = Meta_map
|
|
|
|
(** {2 Tracing} *)
|
|
|
|
val enabled : unit -> bool
|
|
(** Is there a collector?
|
|
|
|
This is fast, so that the traced program can check it before creating
|
|
any span or message *)
|
|
|
|
val with_span :
|
|
?__FUNCTION__:string ->
|
|
__FILE__:string ->
|
|
__LINE__:int ->
|
|
?data:(unit -> (string * user_data) list) ->
|
|
string ->
|
|
(span -> 'a) ->
|
|
'a
|
|
(** [with_span ~__FILE__ ~__LINE__ name f] enters a new span [sp],
|
|
and calls [f sp].
|
|
[sp] might be a dummy span if no collector is installed.
|
|
When [f sp] returns or raises, the span [sp] is exited.
|
|
|
|
This is the recommended way to instrument most code.
|
|
|
|
{b NOTE} an important restriction is that this is only supposed to
|
|
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_manual_span}.
|
|
*)
|
|
|
|
val enter_manual_sub_span :
|
|
parent:explicit_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
|
|
providing the [parent] context, and carry the resulting
|
|
{!explicit_span} to the matching {!exit_manual_span}.
|
|
@since NEXT_RELEASE *)
|
|
|
|
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 :
|
|
?span:span -> ?data:(unit -> (string * user_data) list) -> string -> unit
|
|
(** [message msg] logs a message [msg] (if a collector is installed).
|
|
Additional metadata can be provided.
|
|
@param span the surrounding span, if any. This might be ignored by the collector. *)
|
|
|
|
val messagef :
|
|
?span:span ->
|
|
?data:(unit -> (string * user_data) list) ->
|
|
((('a, Format.formatter, unit, unit) format4 -> 'a) -> unit) ->
|
|
unit
|
|
(** [messagef (fun k->k"hello %s %d!" "world" 42)] is like
|
|
[message "hello world 42!"] but only computes the string formatting
|
|
if a collector is installed. *)
|
|
|
|
val set_thread_name : string -> unit
|
|
(** Give a name to the current thread.
|
|
This might be used by the collector
|
|
to display traces in a more informative way. *)
|
|
|
|
val set_process_name : string -> unit
|
|
(** Give a name to the current process.
|
|
This might be used by the collector
|
|
to display traces in a more informative way. *)
|
|
|
|
val counter_int : string -> int -> unit
|
|
(** Emit a counter of type [int]. Counters represent the evolution of some quantity
|
|
over time. *)
|
|
|
|
val counter_float : string -> float -> unit
|
|
(** Emit a counter of type [float]. See {!counter_int} for more details. *)
|
|
|
|
(** {2 Collector} *)
|
|
|
|
type collector = (module Collector.S)
|
|
(** An event collector.
|
|
|
|
See {!Collector} for more details. *)
|
|
|
|
val setup_collector : collector -> unit
|
|
(** [setup_collector c] installs [c] as the current collector.
|
|
@raise Invalid_argument if there already is an established
|
|
collector. *)
|
|
|
|
val shutdown : unit -> unit
|
|
(** [shutdown ()] shutdowns the current collector, if one was installed,
|
|
and waits for it to terminate before returning. *)
|
|
|
|
(**/**)
|
|
|
|
(* no guarantee of stability *)
|
|
module Internal_ : sig
|
|
module Atomic_ = Atomic_
|
|
end
|
|
|
|
(**/**)
|