Module `Trace_core`Source

Main tracing interface.

This interface is intended to be lightweight and usable in both libraries and applications. It has very low overhead if no Collector.t is installed.

Sourcetype span = ..

A span. Its representation is defined by the current collector.

Sourcetype parent =

| P_unknown
(*
Parent is not specified at this point
*)
| P_none
(*
We know the current span has no parent
*)
| P_some of span
(*
We know the parent of the current span
*)

Information about a span's parent span, if any.

since 0.11

Sourcetype user_data = [

| `Int of int
| `String of string
| `Bool of bool
| `Float of float
| `None

]

User defined data, generally passed as key/value pairs to whatever collector is installed (if any).

Sourcetype explicit_span = span

deprecated use span

Sourcetype explicit_span_ctx = span

deprecated use span

Sourcetype extension_parameter = ..

An extension parameter, used to carry information for spans/messages/metrics that can be backend-specific or just not envisioned by trace.

since 0.11

Sourcetype metric = ..

A metric, can be of many types. See Core_ext for some builtin metrics.

since 0.11

Sourcemodule Collector : sig ... end

A global collector.

Sourcemodule Level : sig ... end

Tracing levels.

Sourcemodule Ambient_span_provider : sig ... end

Access/set the current span from some ambient context.

Tracing

Sourceval enabled : unit -> bool

Is there a collector?

This is fast, so that the traced program can check it before creating any span or message.

Sourceval get_default_level : unit -> Level.t

Current default level for spans.

since 0.7

Sourceval set_default_level : Level.t -> unit

Set level used for spans that do not specify it. The default default value is Level.Trace.

since 0.7

Source

val with_span : 
  ?level:Level.t ->
  ?__FUNCTION__:string ->
  __FILE__:string ->
  __LINE__:int ->
  ?parent:span option ->
  ?params:extension_parameter list ->
  ?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.

parameter level
optional level for this span. since 0.7. Default is set via set_default_level.

parameter parent
the span's parent, if any. since 0.11.

parameter params
extension parameters, used to communicate additional information to the collector. It might be collector-specific. since 0.11.

Depending on the collector, this might clash with some forms of cooperative concurrency in which with_span (fun span -> …) might contain a yield point. Effect-based fibers, etc. might not play well with this style of spans on some or all backends. If you use cooperative concurrency, a safer alternative can be enter_span.

Source

val enter_span : 
  ?level:Level.t ->
  ?__FUNCTION__:string ->
  __FILE__:string ->
  __LINE__:int ->
  ?flavor:[ `Sync | `Async ] ->
  ?parent:span option ->
  ?params:extension_parameter list ->
  ?data:(unit -> (string * user_data) list) ->
  string ->
  span

Enter a span manually. This means the caller is responsible for exiting the span exactly once on every path that exits the current scope. The context must be passed to the exit function as is.

parameter level
optional level for this span. since 0.7. Default is set via set_default_level.

parameter parent
the span's parent, if any. since 0.11.

parameter params
see with_span.

Sourceval exit_span : span -> unit

Exit a span manually. Spans must be nested correctly (ie form a stack or tree).

For some collectors, enter_span and exit_span must run on the same thread (e.g. Tracy). For some others, it doesn't matter.

Sourceval add_data_to_span : span -> (string * user_data) list -> unit

Add structured data to the given active span (see with_span). Behavior is not specified if the span has been exited.

since 0.4

Source

val message : 
  ?level:Level.t ->
  ?span:span ->
  ?params:extension_parameter list ->
  ?data:(unit -> (string * user_data) list) ->
  string ->
  unit

message msg logs a message msg (if a collector is installed). Additional metadata can be provided.

parameter level
optional level for this span. since 0.7. Default is set via set_default_level.

parameter span
the surrounding span, if any. This might be ignored by the collector.

parameter params
extension parameters, used to communicate additional information to the collector. It might be collector-specific. since 0.11.

Source

val messagef : 
  ?level:Level.t ->
  ?span:span ->
  ?params:extension_parameter list ->
  ?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.

See message for a description of the other arguments.

Sourceval 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.

Uses Core_ext.Extension_set_thread_name since 0.11

Sourceval 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.

Uses Core_ext.Extension_set_process_name since 0.11

Source

val metric : 
  ?level:Level.t ->
  ?params:extension_parameter list ->
  ?data:(unit -> (string * user_data) list) ->
  string ->
  metric ->
  unit

Emit a metric. Metrics are an extensible type, each collector might support a different subset.

since 0.11

Source

val counter_int : 
  ?level:Level.t ->
  ?params:extension_parameter list ->
  ?data:(unit -> (string * user_data) list) ->
  string ->
  int ->
  unit

Emit a counter of type int via metric. Counters represent the evolution of some quantity over time.

parameter level
optional level for this span. since 0.7. Default is set via set_default_level.

parameter data
metadata for this metric (since 0.4)

Source

val counter_float : 
  ?level:Level.t ->
  ?params:extension_parameter list ->
  ?data:(unit -> (string * user_data) list) ->
  string ->
  float ->
  unit

Emit a counter of type float via metric. See counter_int for more details.

parameter level
optional level for this span. since 0.7. Default is set via set_default_level.

parameter data
metadata for this metric (since 0.4)

Sourceval current_span : unit -> span option

Access the current span from some ambient scope, if supported. This is only supported if a Ambient_span_provider has been set up.

since 0.12

Sourceval with_current_span_set_to : span -> (span -> 'a) -> 'a

with_current_span_set_to span f sets the span as current span, enters f span, and restores the previous current span (if any).

This is only supported if a Ambient_span_provider has been set up, otherwise it is a no-op.

Automatically called by with_span.

since 0.12

Collector

Sourcetype collector = Collector.t

An event collector. See Collector for more details.

Sourceval setup_collector : collector -> unit

setup_collector c installs c as the current collector.

raises Invalid_argument
if there already is an established collector.

Sourceval get_current_level : unit -> Level.t

Get current level. This is only meaningful if a collector was set up with setup_collector.

since 0.7

Sourceval 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.

since 0.7

Sourceval shutdown : unit -> unit

shutdown () shutdowns the current collector, if one was installed, and waits for it to terminate before returning.

Sourceval with_setup_collector : Collector.t -> (unit -> 'a) -> 'a

with_setup_collector c f installs c, calls f(), and shutdowns c once f() is done.

since 0.11

ambient span provider

Sourceval set_ambient_context_provider : Ambient_span_provider.t -> unit

Install a provider for current_span and with_current_span_set_to. The default provider does nothing (ie current_span () is always None).

since 0.12

Extensions

Sourcetype extension_event = ..

Extension event

since 0.8

Sourceval extension_event : ?level:Level.t -> extension_event -> unit

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.

parameter level
filtering level, since 0.11

since 0.8

Core extensions

Sourcemodule Core_ext : sig ... end

A few core extensions.

Deprecated

Source

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_span

deprecated use enter_span

Source

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

deprecated
since 0.10, use enter_span

Source

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

deprecated
since 0.10 use enter_span

Sourceval exit_manual_span : explicit_span -> unit

deprecated
since 0.10 use exit_span

Source

val add_data_to_manual_span : 
  explicit_span ->
  (string * user_data) list ->
  unit

deprecated
since 0.10 use add_data_to_span

Install

dune-project
Dependency

Authors

Maintainers

Sources

doc/trace.core/Trace_core/index.html

Module `Trace_core`Source

Tracing

Collector

ambient span provider

Extensions

Core extensions

Deprecated

package trace

Install

dune-project Dependency

Authors

Maintainers

Sources

doc/trace.core/Trace_core/index.html

Module Trace_coreSource

Tracing

Collector

ambient span provider

Extensions

Core extensions

Deprecated

dune-project
Dependency

Module `Trace_core`Source