Module Trace_core

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.

type span = ..

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

type parent =
  1. | P_unknown
    (*

    Parent is not specified at this point

    *)
  2. | P_none
    (*

    We know the current span has no parent

    *)
  3. | P_some of span
    (*

    We know the parent of the current span

    *)

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

  • since 0.11
type user_data = [
  1. | `Int of int
  2. | `String of string
  3. | `Bool of bool
  4. | `Float of float
  5. | `None
]

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

type explicit_span = span
  • deprecated use span
type explicit_span_ctx = span
  • deprecated use span
type 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
type metric = ..

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

  • since 0.11
module Collector : sig ... end

A global collector.

module Level : sig ... end

Tracing levels.

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 get_default_level : unit -> Level.t

Current default level for spans.

  • since 0.7
val 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
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.

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.

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

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

val messagef : ?level:Level.t -> ?span:span -> ?params:extension_parameter list -> ?data:(unit -> (string * user_data) list) -> ((('a, Stdlib.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.

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.

Uses Core_ext.Extension_set_thread_name since 0.11

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.

Uses Core_ext.Extension_set_process_name since 0.11

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
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)

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)

Collector

type collector = Collector.t

An event collector. See Collector for more details.

val setup_collector : collector -> unit

setup_collector c installs c as the current collector.

  • raises Invalid_argument

    if there already is an established collector.

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

  • since 0.7
val shutdown : unit -> unit

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

val 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

Extensions

type extension_event = ..

Extension event

  • since 0.8
val 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

module Core_ext : sig ... end

A few core extensions.

Deprecated

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
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
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
val exit_manual_span : explicit_span -> unit
val add_data_to_manual_span : explicit_span -> (string * user_data) list -> unit