package trace
- Overview
- No Docs
You can search for identifiers within the package.
in-package search v0.2.0
Install
Dune Dependency
Authors
Maintainers
Sources
sha256=c5a43827bbd5521e779c8856e44f4c718dccda902d00a242b598516110ada04d
sha512=f19cb25a767ed428cb1d4a497312267524bfaaf9550caa5fc1e84809494f0b7eaf26030d95563c75dea66606fcbec1be7e34baa4cba86fc57d64bc5d5b98efd5
doc/trace.core/Trace_core/index.html
Module Trace_coreSource
Trace.
A span identifier.
The meaning of the identifier depends on the collector.
A bytestring representing a (possibly distributed) trace made of async spans. With opentelemetry this is 16 bytes.
User defined data, generally passed as key/value pairs to whatever collector is installed (if any).
A context, passed around for async traces.
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.trace_id : trace_id;(*The trace this belongs to
*)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. This is richer than explicit_span_ctx but not intended to be passed around (or sent across the wire), unlike explicit_span_ctx.
Tracing
Is there a collector?
This is fast, so that the traced program can check it before creating any span or message.
Set level used for spans that do not specify it. The default default value is Level.Trace.
Turn a span into a span context.
val with_span :
?level:Level.t ->
?__FUNCTION__:string ->
__FILE__:string ->
__LINE__:int ->
?data:(unit -> (string * user_data) list) ->
string ->
(span -> 'a) ->
'awith_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.
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_span :
?level:Level.t ->
?__FUNCTION__:string ->
__FILE__:string ->
__LINE__:int ->
?data:(unit -> (string * user_data) list) ->
string ->
spanEnter a span manually.
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_span :
parent:explicit_span_ctx option ->
?flavor:[ `Sync | `Async ] ->
?level:Level.t ->
?__FUNCTION__:string ->
__FILE__:string ->
__LINE__:int ->
?data:(unit -> (string * user_data) list) ->
string ->
explicit_spanLike 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.
NOTE this replaces enter_manual_sub_span and enter_manual_toplevel_span by just making parent an explicit option. It is breaking anyway because we now pass an explicit_span_ctx instead of a full explicit_span (the reason being that we might receive this explicit_span_ctx from another process or machine).
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_spanval enter_manual_toplevel_span :
?flavor:[ `Sync | `Async ] ->
?level:Level.t ->
?__FUNCTION__:string ->
__FILE__:string ->
__LINE__:int ->
?data:(unit -> (string * user_data) list) ->
string ->
explicit_spanExit 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.
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 ->
unitmessage 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) ->
unitmessagef (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 ->
unitEmit 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 ->
unitEmit a counter of type float. See counter_int for more details.
Collector
An event collector.
See Collector for more details.
Get current level. This is only meaningful if a collector was set up with setup_collector.
Set the current level of tracing. This only has a visible effect if a collector was installed with setup_collector.
shutdown () shutdowns the current collector, if one was installed, and waits for it to terminate before returning.
Extensions
Extension event
Trigger an extension event, whose meaning depends on the library that defines it. Some collectors will simply ignore it. This does nothing if no collector is setup.