package trace

  1. Overview
  2. Docs

Module Trace_coreSource

Trace.

Sourcetype span = int64

A span identifier.

The meaning of the identifier depends on the collector.

Sourcetype user_data = [
  1. | `Int of int
  2. | `String of string
  3. | `Bool of bool
  4. | `None
]

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

Sourcemodule Collector : sig ... end

A global collector.

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 enter_span : ?__FUNCTION__:string -> __FILE__:string -> __LINE__:int -> ?data:(unit -> (string * user_data) list) -> string -> span

Enter a span. A span is a delimited period of time with a start instant ("enter") and stop instant ("exit"), associated with some metadata about the code entering/exiting some piece of code.

In particular the entrypoint comes with the location of the code (you can use __FILE__ and __LINE__ directly in OCaml), a mandatory name, and some optional metadata in a JSON-like representation.

Sourceval exit_span : span -> unit

Exit the span.

This should be called exactly once per span (even in case of exception). Once this is called, a timestamp might be recorded, and the span is considered finished and can't be used anymore

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

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

  • parameter span

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

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

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.

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.

Sourceval counter_int : string -> int -> unit

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

Sourceval counter_float : string -> float -> unit

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

Collector

Sourcetype collector = (module Collector.S)

An event collector.

See Collector for more details.

Sourceval setup_collector : collector -> unit

setup_collector c installs c as the current collector.

Sourceval shutdown : unit -> unit

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