Library
Module
Module type
Parameter
Class
Class type
Trace.
User defined data, generally passed as key/value pairs to whatever collector is installed (if any).
type explicit_span = {
span : span;
Identifier for this span. Several explicit spans might share the same identifier since we can differentiate between them via meta
.
mutable meta : Meta_map.t;
Metadata for this span (and its context). This can be used by collectors to carry collector-specific information from the beginning of the span, to the end of the span.
*)}
Explicit span, with collector-specific metadata
module Collector : sig ... end
A global collector.
module Meta_map : sig ... end
module Level : sig ... end
Tracing levels.
Is there a collector?
This is fast, so that the traced program can check it before creating any span or message.
val get_default_level : unit -> Level.t
Current default level for spans.
val set_default_level : Level.t -> unit
Set level used for spans that do not specify it. The default default value is Level.Trace
.
val with_span :
?level:Level.t ->
?__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.
val enter_span :
?level:Level.t ->
?__FUNCTION__:string ->
__FILE__:string ->
__LINE__:int ->
?data:(unit -> (string * user_data) list) ->
string ->
span
Enter a span manually.
val exit_span : span -> unit
Exit a span manually. This must run on the same thread as the corresponding enter_span
, and spans must nest correctly.
Add structured data to the given active span (see with_span
). Behavior is not specified if the span has been exited.
val enter_manual_sub_span :
parent:explicit_span ->
?flavor:[ `Sync | `Async ] ->
?level:Level.t ->
?__FUNCTION__:string ->
__FILE__:string ->
__LINE__:int ->
?data:(unit -> (string * user_data) list) ->
string ->
explicit_span
Like with_span
but the caller is responsible for obtaining the parent
span from their own caller, and carry the resulting explicit_span
to the matching exit_manual_span
.
val enter_manual_toplevel_span :
?flavor:[ `Sync | `Async ] ->
?level:Level.t ->
?__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
.
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
.
val add_data_to_manual_span :
explicit_span ->
(string * user_data) list ->
unit
add_data_explicit esp data
adds data
to the span esp
. The behavior is not specified is the span has been exited already.
val message :
?level:Level.t ->
?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.
val messagef :
?level:Level.t ->
?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.
Give a name to the current thread. This might be used by the collector to display traces in a more informative way.
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 :
?level:Level.t ->
?data:(unit -> (string * user_data) list) ->
string ->
int ->
unit
Emit a counter of type int
. Counters represent the evolution of some quantity over time.
val counter_float :
?level:Level.t ->
?data:(unit -> (string * user_data) list) ->
string ->
float ->
unit
Emit a counter of type float
. See counter_int
for more details.
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.
val get_current_level : unit -> Level.t
Get current level. This is only meaningful if a collector was set up with setup_collector
.
val set_current_level : Level.t -> unit
Set the current level of tracing. This only has a visible effect if a collector was installed with setup_collector
.