From 9c26067efcda3264e6506a9156ce93ddba55c66b Mon Sep 17 00:00:00 2001 From: c-cube Date: Wed, 21 Jan 2026 01:25:53 +0000 Subject: [PATCH] deploy: 87d5a0228a9c8d11d2909761ed84953ec647e065 --- .../Trace_fuchsia/Buf_pool/index.html | 2 +- .../Collector_fuchsia/index.html | 7 + .../Subscriber/Callbacks/index.html | 57 -------- .../Trace_fuchsia/Subscriber/index.html | 7 - .../Writer/Event/Async_begin/index.html | 2 +- .../Writer/Event/Async_end/index.html | 2 +- trace-fuchsia/Trace_fuchsia/index.html | 2 +- .../index.html | 2 + .../Trace_fuchsia__Subscriber/index.html | 2 - trace-fuchsia/Trace_fuchsia__Types/index.html | 2 + .../Collector_tef/Buf_pool/index.html | 2 + trace-tef/Trace_tef/Collector_tef/index.html | 7 + trace-tef/Trace_tef/Exporter/index.html | 2 +- .../Trace_tef/Subscriber/Buf_pool/index.html | 2 - .../Trace_tef/Subscriber/Callbacks/index.html | 57 -------- trace-tef/Trace_tef/Subscriber/index.html | 7 - trace-tef/Trace_tef/Types/index.html | 2 + trace-tef/Trace_tef/Writer/index.html | 10 +- trace-tef/Trace_tef/index.html | 7 +- .../Trace_tef__Collector_tef}/index.html | 2 +- .../Trace_tef__Types}/index.html | 2 +- trace-tef/Trace_tef_tldrs/index.html | 2 +- trace/Trace/index.html | 65 +++++---- .../Trace_core/Collector/Callbacks/index.html | 138 ++++++++++++++++++ trace/Trace_core/Collector/index.html | 2 +- .../Collector/module-type-S/index.html | 95 ------------ trace/Trace_core/Core_ext/index.html | 2 + trace/Trace_core/Meta_map/Key/index.html | 2 - trace/Trace_core/Meta_map/M/index.html | 6 - trace/Trace_core/Meta_map/index.html | 2 - .../Meta_map/module-type-KEY_IMPL/index.html | 2 - trace/Trace_core/index.html | 65 +++++---- .../index.html | 2 +- trace/Trace_debug/Track_spans/index.html | 5 + trace/Trace_debug/index.html | 2 + trace/Trace_debug__Track_spans/index.html | 2 + trace/Trace_event/Event/index.html | 2 - .../Subscriber/Callbacks/index.html | 57 -------- trace/Trace_event/Subscriber/index.html | 3 - trace/Trace_event/index.html | 2 - trace/Trace_event__Event/index.html | 2 - .../Trace_private_util/Domain_util/index.html | 2 - trace/Trace_private_util/index.html | 2 - .../index.html | 2 - trace/Trace_simple/Simple_span/index.html | 2 + trace/Trace_simple/index.html | 2 + .../index.html | 2 +- .../Callbacks/Dummy/index.html | 38 ----- trace/Trace_subscriber/Callbacks/index.html | 10 -- .../Callbacks/module-type-S/index.html | 57 -------- .../Span_generator/index.html | 2 - trace/Trace_subscriber/Span_tbl/index.html | 2 - trace/Trace_subscriber/Subscriber/index.html | 2 - .../Trace_id_8B_generator/index.html | 2 - trace/Trace_subscriber/index.html | 2 - trace/Trace_subscriber__Subscriber/index.html | 2 - trace/Trace_util/Domain_util/index.html | 2 + trace/Trace_util/Mock_/Inner/index.html | 2 + trace/Trace_util/Mock_/index.html | 2 + trace/Trace_util/Multi_collector/index.html | 5 + .../Rpool/index.html | 2 +- trace/Trace_util/Span_id64/Gen/index.html | 2 + .../Span_id64/Trace_id_generator/index.html | 2 + trace/Trace_util/Span_id64/index.html | 2 + trace/Trace_util/Thread_util/index.html | 2 + trace/Trace_util/Time_util/index.html | 2 + trace/Trace_util/Trace_id64/Gen/index.html | 2 + trace/Trace_util/Trace_id64/index.html | 2 + trace/Trace_util/Unix_util/index.html | 2 + trace/Trace_util/index.html | 2 + .../index.html | 2 +- trace/Trace_util__Mock_/index.html | 2 + .../index.html | 2 +- trace/Trace_util__Rpool/index.html | 2 + .../Trace_util__Span_id64}/index.html | 2 +- .../Trace_util__Thread_util}/index.html | 2 +- trace/Trace_util__Time_util/index.html | 2 + trace/Trace_util__Trace_id64/index.html | 2 + trace/Trace_util__Unix_util/index.html | 2 + trace/index.html | 2 +- 80 files changed, 315 insertions(+), 508 deletions(-) create mode 100644 trace-fuchsia/Trace_fuchsia/Collector_fuchsia/index.html delete mode 100644 trace-fuchsia/Trace_fuchsia/Subscriber/Callbacks/index.html delete mode 100644 trace-fuchsia/Trace_fuchsia/Subscriber/index.html create mode 100644 trace-fuchsia/Trace_fuchsia__Collector_fuchsia/index.html delete mode 100644 trace-fuchsia/Trace_fuchsia__Subscriber/index.html create mode 100644 trace-fuchsia/Trace_fuchsia__Types/index.html create mode 100644 trace-tef/Trace_tef/Collector_tef/Buf_pool/index.html create mode 100644 trace-tef/Trace_tef/Collector_tef/index.html delete mode 100644 trace-tef/Trace_tef/Subscriber/Buf_pool/index.html delete mode 100644 trace-tef/Trace_tef/Subscriber/Callbacks/index.html delete mode 100644 trace-tef/Trace_tef/Subscriber/index.html create mode 100644 trace-tef/Trace_tef/Types/index.html rename {trace/Trace_subscriber__Span_tbl => trace-tef/Trace_tef__Collector_tef}/index.html (60%) rename {trace/Trace_subscriber__ => trace-tef/Trace_tef__Types}/index.html (59%) create mode 100644 trace/Trace_core/Collector/Callbacks/index.html delete mode 100644 trace/Trace_core/Collector/module-type-S/index.html create mode 100644 trace/Trace_core/Core_ext/index.html delete mode 100644 trace/Trace_core/Meta_map/Key/index.html delete mode 100644 trace/Trace_core/Meta_map/M/index.html delete mode 100644 trace/Trace_core/Meta_map/index.html delete mode 100644 trace/Trace_core/Meta_map/module-type-KEY_IMPL/index.html rename trace/{Trace_core__Meta_map => Trace_core__Core_ext}/index.html (75%) create mode 100644 trace/Trace_debug/Track_spans/index.html create mode 100644 trace/Trace_debug/index.html create mode 100644 trace/Trace_debug__Track_spans/index.html delete mode 100644 trace/Trace_event/Event/index.html delete mode 100644 trace/Trace_event/Subscriber/Callbacks/index.html delete mode 100644 trace/Trace_event/Subscriber/index.html delete mode 100644 trace/Trace_event/index.html delete mode 100644 trace/Trace_event__Event/index.html delete mode 100644 trace/Trace_private_util/Domain_util/index.html delete mode 100644 trace/Trace_private_util/index.html delete mode 100644 trace/Trace_private_util__Domain_util/index.html create mode 100644 trace/Trace_simple/Simple_span/index.html create mode 100644 trace/Trace_simple/index.html rename trace/{Trace_private_util__Rpool => Trace_simple__Simple_span}/index.html (68%) delete mode 100644 trace/Trace_subscriber/Callbacks/Dummy/index.html delete mode 100644 trace/Trace_subscriber/Callbacks/index.html delete mode 100644 trace/Trace_subscriber/Callbacks/module-type-S/index.html delete mode 100644 trace/Trace_subscriber/Span_generator/index.html delete mode 100644 trace/Trace_subscriber/Span_tbl/index.html delete mode 100644 trace/Trace_subscriber/Subscriber/index.html delete mode 100644 trace/Trace_subscriber/Trace_id_8B_generator/index.html delete mode 100644 trace/Trace_subscriber/index.html delete mode 100644 trace/Trace_subscriber__Subscriber/index.html create mode 100644 trace/Trace_util/Domain_util/index.html create mode 100644 trace/Trace_util/Mock_/Inner/index.html create mode 100644 trace/Trace_util/Mock_/index.html create mode 100644 trace/Trace_util/Multi_collector/index.html rename trace/{Trace_private_util => Trace_util}/Rpool/index.html (64%) create mode 100644 trace/Trace_util/Span_id64/Gen/index.html create mode 100644 trace/Trace_util/Span_id64/Trace_id_generator/index.html create mode 100644 trace/Trace_util/Span_id64/index.html create mode 100644 trace/Trace_util/Thread_util/index.html create mode 100644 trace/Trace_util/Time_util/index.html create mode 100644 trace/Trace_util/Trace_id64/Gen/index.html create mode 100644 trace/Trace_util/Trace_id64/index.html create mode 100644 trace/Trace_util/Unix_util/index.html create mode 100644 trace/Trace_util/index.html rename trace/{Trace_event__Subscriber => Trace_util__Domain_util}/index.html (68%) create mode 100644 trace/Trace_util__Mock_/index.html rename trace/{Trace_subscriber__Callbacks => Trace_util__Multi_collector}/index.html (68%) create mode 100644 trace/Trace_util__Rpool/index.html rename {trace-tef/Trace_tef__Emit_tef => trace/Trace_util__Span_id64}/index.html (59%) rename {trace-tef/Trace_tef__Subscriber => trace/Trace_util__Thread_util}/index.html (60%) create mode 100644 trace/Trace_util__Time_util/index.html create mode 100644 trace/Trace_util__Trace_id64/index.html create mode 100644 trace/Trace_util__Unix_util/index.html diff --git a/trace-fuchsia/Trace_fuchsia/Buf_pool/index.html b/trace-fuchsia/Trace_fuchsia/Buf_pool/index.html index 25738f5..c5ccd74 100644 --- a/trace-fuchsia/Trace_fuchsia/Buf_pool/index.html +++ b/trace-fuchsia/Trace_fuchsia/Buf_pool/index.html @@ -1,2 +1,2 @@ -Buf_pool (trace-fuchsia.Trace_fuchsia.Buf_pool)

Module Trace_fuchsia.Buf_pool

val create : ?max_size:int -> unit -> t
val alloc : 'a Trace_private_util.Rpool.t -> 'a
val recycle : Buf.t Trace_private_util.Rpool.t -> Buf.t -> unit
val with_ : t -> (Buf.t -> 'a) -> 'a
+Buf_pool (trace-fuchsia.Trace_fuchsia.Buf_pool)

Module Trace_fuchsia.Buf_pool

val create : ?max_size:int -> unit -> t
val alloc : 'a Trace_util.Rpool.t -> 'a
val recycle : Buf.t Trace_util.Rpool.t -> Buf.t -> unit
val with_ : t -> (Buf.t -> 'a) -> 'a
diff --git a/trace-fuchsia/Trace_fuchsia/Collector_fuchsia/index.html b/trace-fuchsia/Trace_fuchsia/Collector_fuchsia/index.html new file mode 100644 index 0000000..899061c --- /dev/null +++ b/trace-fuchsia/Trace_fuchsia/Collector_fuchsia/index.html @@ -0,0 +1,7 @@ + +Collector_fuchsia (trace-fuchsia.Trace_fuchsia.Collector_fuchsia)

Module Trace_fuchsia.Collector_fuchsia

type t

Main subscriber state.

val create : + ?buf_pool:Buf_pool.t -> + pid:int -> + exporter:Exporter.t -> + unit -> + t

Create a subscriber state.

val flush : t -> unit
val close : t -> unit
val active : t -> bool
val collector : t -> Trace_core.Collector.t

Subscriber that writes json into this writer

diff --git a/trace-fuchsia/Trace_fuchsia/Subscriber/Callbacks/index.html b/trace-fuchsia/Trace_fuchsia/Subscriber/Callbacks/index.html deleted file mode 100644 index 2f8c8d3..0000000 --- a/trace-fuchsia/Trace_fuchsia/Subscriber/Callbacks/index.html +++ /dev/null @@ -1,57 +0,0 @@ - -Callbacks (trace-fuchsia.Trace_fuchsia.Subscriber.Callbacks)

Module Subscriber.Callbacks

type st = t

Type of the state passed to every callback.

val on_init : st -> time_ns:int64 -> unit

Called when the subscriber is initialized in a collector

val new_span : st -> Trace_core.span

How to generate a new span?

  • since NEXT_RELEASE
val new_trace_id : st -> Trace_core.trace_id

How to generate a new trace ID?

  • since NEXT_RELEASE
val on_shutdown : st -> time_ns:int64 -> unit

Called when the collector is shutdown

val on_name_thread : st -> time_ns:int64 -> tid:int -> name:string -> unit

Current thread is being named

val on_name_process : st -> time_ns:int64 -> tid:int -> name:string -> unit

Current process is being named

val on_enter_span : - st -> - __FUNCTION__:string option -> - __FILE__:string -> - __LINE__:int -> - time_ns:int64 -> - tid:int -> - data:(string * Trace_core.user_data) list -> - name:string -> - Trace_core.span -> - unit

Enter a regular (sync) span

val on_exit_span : st -> time_ns:int64 -> tid:int -> Trace_core.span -> unit

Exit a span. This and on_enter_span must follow strict stack discipline

val on_add_data : - st -> - data:(string * Trace_core.user_data) list -> - Trace_core.span -> - unit

Add data to a regular span (which must be active)

val on_message : - st -> - time_ns:int64 -> - tid:int -> - span:Trace_core.span option -> - data:(string * Trace_core.user_data) list -> - string -> - unit

Emit a log message

val on_counter : - st -> - time_ns:int64 -> - tid:int -> - data:(string * Trace_core.user_data) list -> - name:string -> - float -> - unit

Emit the current value of a counter

val on_enter_manual_span : - st -> - __FUNCTION__:string option -> - __FILE__:string -> - __LINE__:int -> - time_ns:int64 -> - tid:int -> - parent:Trace_core.span option -> - data:(string * Trace_core.user_data) list -> - name:string -> - flavor:Trace_core.span_flavor option -> - trace_id:Trace_core.trace_id -> - Trace_core.span -> - unit

Enter a manual (possibly async) span

val on_exit_manual_span : - st -> - time_ns:int64 -> - tid:int -> - name:string -> - data:(string * Trace_core.user_data) list -> - flavor:Trace_core.span_flavor option -> - trace_id:Trace_core.trace_id -> - Trace_core.span -> - unit

Exit a manual span

val on_extension_event : - st -> - time_ns:int64 -> - tid:int -> - Trace_core.extension_event -> - unit

Extension event

  • since 0.8
diff --git a/trace-fuchsia/Trace_fuchsia/Subscriber/index.html b/trace-fuchsia/Trace_fuchsia/Subscriber/index.html deleted file mode 100644 index 63042d0..0000000 --- a/trace-fuchsia/Trace_fuchsia/Subscriber/index.html +++ /dev/null @@ -1,7 +0,0 @@ - -Subscriber (trace-fuchsia.Trace_fuchsia.Subscriber)

Module Trace_fuchsia.Subscriber

type t

Main subscriber state.

val create : - ?buf_pool:Buf_pool.t -> - pid:int -> - exporter:Exporter.t -> - unit -> - t

Create a subscriber state.

val flush : t -> unit
val close : t -> unit
val active : t -> bool
val subscriber : t -> Trace_subscriber.t

Subscriber that writes json into this writer

diff --git a/trace-fuchsia/Trace_fuchsia/Writer/Event/Async_begin/index.html b/trace-fuchsia/Trace_fuchsia/Writer/Event/Async_begin/index.html index 352886b..ed6c66f 100644 --- a/trace-fuchsia/Trace_fuchsia/Writer/Event/Async_begin/index.html +++ b/trace-fuchsia/Trace_fuchsia/Writer/Event/Async_begin/index.html @@ -9,7 +9,7 @@ name:string -> t_ref:Thread_ref.t -> time_ns:int64 -> - async_id:Trace_core.trace_id -> + async_id:int64 -> args:Arguments.t -> unit -> unit diff --git a/trace-fuchsia/Trace_fuchsia/Writer/Event/Async_end/index.html b/trace-fuchsia/Trace_fuchsia/Writer/Event/Async_end/index.html index 4d4bef1..75b7342 100644 --- a/trace-fuchsia/Trace_fuchsia/Writer/Event/Async_end/index.html +++ b/trace-fuchsia/Trace_fuchsia/Writer/Event/Async_end/index.html @@ -9,7 +9,7 @@ name:string -> t_ref:Thread_ref.t -> time_ns:int64 -> - async_id:Trace_core.trace_id -> + async_id:int64 -> args:Arguments.t -> unit -> unit diff --git a/trace-fuchsia/Trace_fuchsia/index.html b/trace-fuchsia/Trace_fuchsia/index.html index 844ffb9..9395144 100644 --- a/trace-fuchsia/Trace_fuchsia/index.html +++ b/trace-fuchsia/Trace_fuchsia/index.html @@ -1,2 +1,2 @@ -Trace_fuchsia (trace-fuchsia.Trace_fuchsia)

Module Trace_fuchsia

Fuchsia trace collector.

This provides a collector for traces that emits data into a file using the compact binary Fuchsia trace format. This reduces the tracing overhead compared to trace-tef, at the expense of simplicity.

module Buf : sig ... end
module Buf_chain : sig ... end

A set of buffers in use, and a set of ready buffers

module Buf_pool : sig ... end
module Exporter : sig ... end

An exporter, takes buffers with fuchsia events, and writes them somewhere

module Subscriber : sig ... end
module Writer : sig ... end

Write fuchsia events into buffers.

type output = [
  1. | `File of string
  2. | `Exporter of Exporter.t
]
val subscriber : out:[< output ] -> unit -> Trace_subscriber.t
val collector : out:[< output ] -> unit -> Trace_core.collector

Make a collector that writes into the given output. See setup for more details.

val setup : ?out:[ output | `Env ] -> unit -> unit

setup () installs the collector depending on out.

  • parameter out

    can take different values:

    • regular output value to specify where events go
    • `Env will enable tracing if the environment variable "TRACE" is set.
  • If it's set to "1", then the file is "trace.fxt".
  • Otherwise, if it's set to a non empty string, the value is taken to be the file path into which to write.
val with_setup : ?out:[< output | `Env Env ] -> unit -> (unit -> 'a) -> 'a

with_setup () f (optionally) sets a collector up, calls f(), and makes sure to shutdown before exiting.

+Trace_fuchsia (trace-fuchsia.Trace_fuchsia)

Module Trace_fuchsia

Fuchsia trace collector.

This provides a collector for traces that emits data into a file using the compact binary Fuchsia trace format. This reduces the tracing overhead compared to trace-tef, at the expense of simplicity.

module Buf : sig ... end
module Buf_chain : sig ... end

A set of buffers in use, and a set of ready buffers

module Buf_pool : sig ... end
module Exporter : sig ... end

An exporter, takes buffers with fuchsia events, and writes them somewhere

module Collector_fuchsia : sig ... end
module Writer : sig ... end

Write fuchsia events into buffers.

type output = [
  1. | `File of string
  2. | `Exporter of Exporter.t
]
val collector : out:[< output ] -> unit -> Trace_core.collector

Make a collector that writes into the given output. See setup for more details.

val setup : ?out:[ output | `Env ] -> unit -> unit

setup () installs the collector depending on out.

  • parameter out

    can take different values:

    • regular output value to specify where events go
    • `Env will enable tracing if the environment variable "TRACE" is set.
  • If it's set to "1", then the file is "trace.fxt".
  • Otherwise, if it's set to a non empty string, the value is taken to be the file path into which to write.
val with_setup : ?out:[< output | `Env Env ] -> unit -> (unit -> 'a) -> 'a

with_setup () f (optionally) sets a collector up, calls f(), and makes sure to shutdown before exiting.

diff --git a/trace-fuchsia/Trace_fuchsia__Collector_fuchsia/index.html b/trace-fuchsia/Trace_fuchsia__Collector_fuchsia/index.html new file mode 100644 index 0000000..854c87e --- /dev/null +++ b/trace-fuchsia/Trace_fuchsia__Collector_fuchsia/index.html @@ -0,0 +1,2 @@ + +Trace_fuchsia__Collector_fuchsia (trace-fuchsia.Trace_fuchsia__Collector_fuchsia)

Module Trace_fuchsia__Collector_fuchsia

This module is hidden.

diff --git a/trace-fuchsia/Trace_fuchsia__Subscriber/index.html b/trace-fuchsia/Trace_fuchsia__Subscriber/index.html deleted file mode 100644 index 8817abb..0000000 --- a/trace-fuchsia/Trace_fuchsia__Subscriber/index.html +++ /dev/null @@ -1,2 +0,0 @@ - -Trace_fuchsia__Subscriber (trace-fuchsia.Trace_fuchsia__Subscriber)

Module Trace_fuchsia__Subscriber

This module is hidden.

diff --git a/trace-fuchsia/Trace_fuchsia__Types/index.html b/trace-fuchsia/Trace_fuchsia__Types/index.html new file mode 100644 index 0000000..bb433c5 --- /dev/null +++ b/trace-fuchsia/Trace_fuchsia__Types/index.html @@ -0,0 +1,2 @@ + +Trace_fuchsia__Types (trace-fuchsia.Trace_fuchsia__Types)

Module Trace_fuchsia__Types

This module is hidden.

diff --git a/trace-tef/Trace_tef/Collector_tef/Buf_pool/index.html b/trace-tef/Trace_tef/Collector_tef/Buf_pool/index.html new file mode 100644 index 0000000..a92baae --- /dev/null +++ b/trace-tef/Trace_tef/Collector_tef/Buf_pool/index.html @@ -0,0 +1,2 @@ + +Buf_pool (trace-tef.Trace_tef.Collector_tef.Buf_pool)

Module Collector_tef.Buf_pool

type t
val create : ?max_size:int -> ?buf_size:int -> unit -> t
diff --git a/trace-tef/Trace_tef/Collector_tef/index.html b/trace-tef/Trace_tef/Collector_tef/index.html new file mode 100644 index 0000000..ddfe117 --- /dev/null +++ b/trace-tef/Trace_tef/Collector_tef/index.html @@ -0,0 +1,7 @@ + +Collector_tef (trace-tef.Trace_tef.Collector_tef)

Module Trace_tef.Collector_tef

module Buf_pool : sig ... end
type t

Main state.

val create : + ?buf_pool:Buf_pool.t -> + pid:int -> + exporter:Exporter.t -> + unit -> + t

Create a fresh state.

val flush : t -> unit
val close : t -> unit
val active : t -> bool
val callbacks_collector : t Trace_core.Collector.Callbacks.t

Callbacks used for the subscriber

val collector : t -> Trace_core.Collector.t

Subscriber that writes json into this writer

diff --git a/trace-tef/Trace_tef/Exporter/index.html b/trace-tef/Trace_tef/Exporter/index.html index 8b14eab..59a83d3 100644 --- a/trace-tef/Trace_tef/Exporter/index.html +++ b/trace-tef/Trace_tef/Exporter/index.html @@ -1,2 +1,2 @@ -Exporter (trace-tef.Trace_tef.Exporter)

Module Trace_tef.Exporter

An exporter, takes JSON objects and writes them somewhere

type t = {
  1. on_json : Stdlib.Buffer.t -> unit;
    (*

    Takes a buffer and writes it somewhere. The buffer is only valid during this call and must not be stored.

    *)
  2. flush : unit -> unit;
    (*

    Force write

    *)
  3. close : unit -> unit;
    (*

    Close underlying resources

    *)
}

An exporter, takes JSON objects and writes them somewhere.

This should be thread-safe if used in a threaded environment.

val of_out_channel : close_channel:bool -> jsonl:bool -> out_channel -> t

Export to the channel

  • parameter jsonl

    if true, export as a JSON object per line, otherwise export as a single big JSON array.

  • parameter close_channel

    if true, closing the exporter will close the channel

val of_buffer : jsonl:bool -> Stdlib.Buffer.t -> t
+Exporter (trace-tef.Trace_tef.Exporter)

Module Trace_tef.Exporter

An exporter, takes JSON objects and writes them somewhere

type t = {
  1. on_json : Stdlib.Buffer.t -> unit;
    (*

    Takes a buffer and writes it somewhere. The buffer is only valid during this call and must not be stored.

    *)
  2. flush : unit -> unit;
    (*

    Force write

    *)
  3. close : unit -> unit;
    (*

    Close underlying resources

    *)
}

An exporter, takes JSON objects and writes them somewhere.

This should be thread-safe if used in a threaded environment.

val of_out_channel : close_channel:bool -> jsonl:bool -> out_channel -> t

Export to the channel

  • parameter jsonl

    if true, export as a JSON object per line, otherwise export as a single big JSON array.

  • parameter close_channel

    if true, closing the exporter will close the channel

val of_buffer : jsonl:bool -> Stdlib.Buffer.t -> t

Emit into the buffer

diff --git a/trace-tef/Trace_tef/Subscriber/Buf_pool/index.html b/trace-tef/Trace_tef/Subscriber/Buf_pool/index.html deleted file mode 100644 index d5de86b..0000000 --- a/trace-tef/Trace_tef/Subscriber/Buf_pool/index.html +++ /dev/null @@ -1,2 +0,0 @@ - -Buf_pool (trace-tef.Trace_tef.Subscriber.Buf_pool)

Module Subscriber.Buf_pool

type t
val create : ?max_size:int -> ?buf_size:int -> unit -> t
diff --git a/trace-tef/Trace_tef/Subscriber/Callbacks/index.html b/trace-tef/Trace_tef/Subscriber/Callbacks/index.html deleted file mode 100644 index c16b5b9..0000000 --- a/trace-tef/Trace_tef/Subscriber/Callbacks/index.html +++ /dev/null @@ -1,57 +0,0 @@ - -Callbacks (trace-tef.Trace_tef.Subscriber.Callbacks)

Module Subscriber.Callbacks

type st = t

Type of the state passed to every callback.

val on_init : st -> time_ns:int64 -> unit

Called when the subscriber is initialized in a collector

val new_span : st -> Trace_core.span

How to generate a new span?

  • since NEXT_RELEASE
val new_trace_id : st -> Trace_core.trace_id

How to generate a new trace ID?

  • since NEXT_RELEASE
val on_shutdown : st -> time_ns:int64 -> unit

Called when the collector is shutdown

val on_name_thread : st -> time_ns:int64 -> tid:int -> name:string -> unit

Current thread is being named

val on_name_process : st -> time_ns:int64 -> tid:int -> name:string -> unit

Current process is being named

val on_enter_span : - st -> - __FUNCTION__:string option -> - __FILE__:string -> - __LINE__:int -> - time_ns:int64 -> - tid:int -> - data:(string * Trace_core.user_data) list -> - name:string -> - Trace_core.span -> - unit

Enter a regular (sync) span

val on_exit_span : st -> time_ns:int64 -> tid:int -> Trace_core.span -> unit

Exit a span. This and on_enter_span must follow strict stack discipline

val on_add_data : - st -> - data:(string * Trace_core.user_data) list -> - Trace_core.span -> - unit

Add data to a regular span (which must be active)

val on_message : - st -> - time_ns:int64 -> - tid:int -> - span:Trace_core.span option -> - data:(string * Trace_core.user_data) list -> - string -> - unit

Emit a log message

val on_counter : - st -> - time_ns:int64 -> - tid:int -> - data:(string * Trace_core.user_data) list -> - name:string -> - float -> - unit

Emit the current value of a counter

val on_enter_manual_span : - st -> - __FUNCTION__:string option -> - __FILE__:string -> - __LINE__:int -> - time_ns:int64 -> - tid:int -> - parent:Trace_core.span option -> - data:(string * Trace_core.user_data) list -> - name:string -> - flavor:Trace_core.span_flavor option -> - trace_id:Trace_core.trace_id -> - Trace_core.span -> - unit

Enter a manual (possibly async) span

val on_exit_manual_span : - st -> - time_ns:int64 -> - tid:int -> - name:string -> - data:(string * Trace_core.user_data) list -> - flavor:Trace_core.span_flavor option -> - trace_id:Trace_core.trace_id -> - Trace_core.span -> - unit

Exit a manual span

val on_extension_event : - st -> - time_ns:int64 -> - tid:int -> - Trace_core.extension_event -> - unit

Extension event

  • since 0.8
diff --git a/trace-tef/Trace_tef/Subscriber/index.html b/trace-tef/Trace_tef/Subscriber/index.html deleted file mode 100644 index b95bfbf..0000000 --- a/trace-tef/Trace_tef/Subscriber/index.html +++ /dev/null @@ -1,7 +0,0 @@ - -Subscriber (trace-tef.Trace_tef.Subscriber)

Module Trace_tef.Subscriber

module Buf_pool : sig ... end
type t

Main subscriber state.

val create : - ?buf_pool:Buf_pool.t -> - pid:int -> - exporter:Exporter.t -> - unit -> - t

Create a subscriber state.

val flush : t -> unit
val close : t -> unit
val active : t -> bool
val subscriber : t -> Trace_subscriber.t

Subscriber that writes json into this writer

diff --git a/trace-tef/Trace_tef/Types/index.html b/trace-tef/Trace_tef/Types/index.html new file mode 100644 index 0000000..cf3ad80 --- /dev/null +++ b/trace-tef/Trace_tef/Types/index.html @@ -0,0 +1,2 @@ + +Types (trace-tef.Trace_tef.Types)

Module Trace_tef.Types

module Trace_id = Trace_util.Trace_id64
type trace_id = Trace_id.t
type Trace_core.span +=
  1. | Span_tef_sync of {
    1. pid : int;
    2. tid : int;
    3. name : string;
    4. start_us : float;
    5. mutable args : (string * Trace_core.user_data) list;
    }
  2. | Span_tef_async of {
    1. pid : int;
    2. tid : int;
    3. name : string;
    4. trace_id : trace_id;
    5. mutable args : (string * Trace_core.user_data) list;
    }
diff --git a/trace-tef/Trace_tef/Writer/index.html b/trace-tef/Trace_tef/Writer/index.html index d363d6b..964d54f 100644 --- a/trace-tef/Trace_tef/Writer/index.html +++ b/trace-tef/Trace_tef/Writer/index.html @@ -7,22 +7,20 @@ end_:float -> args:(string * Trace_core.user_data) list -> Stdlib.Buffer.t -> - unit
val emit_manual_begin : + unit
val emit_begin_async : pid:int -> tid:int -> name:string -> - id:Trace_core.span -> + trace_id:Types.trace_id -> ts:float -> args:(string * Trace_core.user_data) list -> - flavor:Trace_core.span_flavor option -> Stdlib.Buffer.t -> - unit
val emit_manual_end : + unit
val emit_end_async : pid:int -> tid:int -> name:string -> - id:Trace_core.span -> + trace_id:Types.trace_id -> ts:float -> - flavor:Trace_core.span_flavor option -> args:(string * Trace_core.user_data) list -> Stdlib.Buffer.t -> unit
val emit_instant_event : diff --git a/trace-tef/Trace_tef/index.html b/trace-tef/Trace_tef/index.html index 897a171..232b919 100644 --- a/trace-tef/Trace_tef/index.html +++ b/trace-tef/Trace_tef/index.html @@ -1,2 +1,7 @@ -Trace_tef (trace-tef.Trace_tef)

Module Trace_tef

module Subscriber : sig ... end
module Exporter : sig ... end

An exporter, takes JSON objects and writes them somewhere

module Writer : sig ... end

Write JSON events to a buffer.

type output = [
  1. | `Stdout
  2. | `Stderr
  3. | `File of string
]

Output for tracing.

  • `Stdout will enable tracing and print events on stdout
  • `Stderr will enable tracing and print events on stderr
  • `File "foo" will enable tracing and print events into file named "foo"
val subscriber : out:[< output ] -> unit -> Trace_subscriber.t

A subscriber emitting TEF traces into out.

  • since 0.8
val collector : out:[< output ] -> unit -> Trace_core.collector

Make a collector that writes into the given output. See setup for more details.

val setup : ?out:[ output | `Env ] -> unit -> unit

setup () installs the collector depending on out.

  • parameter out

    can take different values:

    • regular output value to specify where events go
    • `Env will enable tracing if the environment variable "TRACE" is set.
  • If it's set to "1", then the file is "trace.json".
  • If it's set to "stdout", then logging happens on stdout (since 0.2)
  • If it's set to "stderr", then logging happens on stdout (since 0.2)
  • Otherwise, if it's set to a non empty string, the value is taken to be the file path into which to write.
val with_setup : ?out:[ output | `Env ] -> unit -> (unit -> 'a) -> 'a

with_setup () f (optionally) sets a collector up, calls f(), and makes sure to shutdown before exiting. since 0.2 a () argument was added.

+Trace_tef (trace-tef.Trace_tef)

Module Trace_tef

module Collector_tef : sig ... end
module Exporter : sig ... end

An exporter, takes JSON objects and writes them somewhere

module Writer : sig ... end

Write JSON events to a buffer.

module Types : sig ... end
type output = [
  1. | `Stdout
  2. | `Stderr
  3. | `File of string
]

Output for tracing.

  • `Stdout will enable tracing and print events on stdout
  • `Stderr will enable tracing and print events on stderr
  • `File "foo" will enable tracing and print events into file named "foo"
val collector : out:[< output ] -> unit -> Trace_core.collector

Make a collector that writes into the given output. See setup for more details.

val setup : ?debug:bool -> ?out:[ output | `Env ] -> unit -> unit

setup () installs the collector depending on out.

  • parameter out

    can take different values:

    • regular output value to specify where events go
    • `Env will enable tracing if the environment variable "TRACE" is set.
  • If it's set to "1", then the file is "trace.json".
  • If it's set to "stdout", then logging happens on stdout (since 0.2)
  • If it's set to "stderr", then logging happens on stdout (since 0.2)
  • Otherwise, if it's set to a non empty string, the value is taken to be the file path into which to write.
  • parameter debug

    if true, use Trace_debug. Default false.

val with_setup : + ?debug:bool -> + ?out:[ output | `Env ] -> + unit -> + (unit -> 'a) -> + 'a

with_setup () f (optionally) sets a collector up, calls f(), and makes sure to shutdown before exiting. since 0.2 a () argument was added.

diff --git a/trace/Trace_subscriber__Span_tbl/index.html b/trace-tef/Trace_tef__Collector_tef/index.html similarity index 60% rename from trace/Trace_subscriber__Span_tbl/index.html rename to trace-tef/Trace_tef__Collector_tef/index.html index a7e9f10..fc9ae21 100644 --- a/trace/Trace_subscriber__Span_tbl/index.html +++ b/trace-tef/Trace_tef__Collector_tef/index.html @@ -1,2 +1,2 @@ -Trace_subscriber__Span_tbl (trace.Trace_subscriber__Span_tbl)

Module Trace_subscriber__Span_tbl

This module is hidden.

+Trace_tef__Collector_tef (trace-tef.Trace_tef__Collector_tef)

Module Trace_tef__Collector_tef

This module is hidden.

diff --git a/trace/Trace_subscriber__/index.html b/trace-tef/Trace_tef__Types/index.html similarity index 59% rename from trace/Trace_subscriber__/index.html rename to trace-tef/Trace_tef__Types/index.html index 912524f..3d1867a 100644 --- a/trace/Trace_subscriber__/index.html +++ b/trace-tef/Trace_tef__Types/index.html @@ -1,2 +1,2 @@ -Trace_subscriber__ (trace.Trace_subscriber__)

Module Trace_subscriber__

This module is hidden.

+Trace_tef__Types (trace-tef.Trace_tef__Types)

Module Trace_tef__Types

This module is hidden.

diff --git a/trace-tef/Trace_tef_tldrs/index.html b/trace-tef/Trace_tef_tldrs/index.html index 8e749f8..e1b0fe4 100644 --- a/trace-tef/Trace_tef_tldrs/index.html +++ b/trace-tef/Trace_tef_tldrs/index.html @@ -1,2 +1,2 @@ -Trace_tef_tldrs (trace-tef.Trace_tef_tldrs)

Module Trace_tef_tldrs

Emit traces by talking to the tldrs daemon

val collector : out:[ `File of string ] -> unit -> Trace_core.collector

Make a collector that writes into the given output. See setup for more details.

val subscriber : out:[ `File of string ] -> unit -> Trace_subscriber.t

Make a subscriber that writes into the given output.

  • since 0.8
type output = [
  1. | `File of string
]

Output for tracing.

  • `File "foo" will enable tracing and print events into file named "foo". The file is only written at exit.
val setup : ?out:[ output | `Env ] -> unit -> unit

setup () installs the collector depending on out.

  • parameter out

    can take different values:

    • regular output value to specify where events go
    • `Env will enable tracing if the environment variable "TRACE" is set.
  • If it's set to "1", then the file is "trace.json".
  • If it's set to "stdout", then logging happens on stdout (since 0.2)
  • If it's set to "stderr", then logging happens on stdout (since 0.2)
  • Otherwise, if it's set to a non empty string, the value is taken to be the file path into which to write.
val with_setup : ?out:[ output | `Env ] -> unit -> (unit -> 'a) -> 'a

with_setup () f (optionally) sets a collector up, calls f(), and makes sure to shutdown before exiting.

+Trace_tef_tldrs (trace-tef.Trace_tef_tldrs)

Module Trace_tef_tldrs

Emit traces by talking to the tldrs daemon

val collector : out:[ `File of string ] -> unit -> Trace_core.collector

Make a collector that writes into the given output. See setup for more details.

type output = [
  1. | `File of string
]

Output for tracing.

  • `File "foo" will enable tracing and print events into file named "foo". The file is only written at exit.
val setup : ?out:[ output | `Env ] -> unit -> unit

setup () installs the collector depending on out.

  • parameter out

    can take different values:

    • regular output value to specify where events go
    • `Env will enable tracing if the environment variable "TRACE" is set.
  • If it's set to "1", then the file is "trace.json".
  • If it's set to "stdout", then logging happens on stdout (since 0.2)
  • If it's set to "stderr", then logging happens on stdout (since 0.2)
  • Otherwise, if it's set to a non empty string, the value is taken to be the file path into which to write.
val with_setup : ?out:[ output | `Env ] -> unit -> (unit -> 'a) -> 'a

with_setup () f (optionally) sets a collector up, calls f(), and makes sure to shutdown before exiting.

diff --git a/trace/Trace/index.html b/trace/Trace/index.html index 2752bf6..79fc206 100644 --- a/trace/Trace/index.html +++ b/trace/Trace/index.html @@ -1,29 +1,58 @@ -Trace (trace.Trace)

Module Trace

include module type of struct include Trace_core end
type span = int64

A span identifier.

The meaning of the identifier depends on the collector.

type trace_id = string

A bytestring representing a (possibly distributed) trace made of async spans. With opentelemetry this is 16 bytes.

  • since 0.10
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 span_flavor = [
  1. | `Sync
  2. | `Async
]

Some information about the span.

  • since NEXT_RELEASE
type explicit_span_ctx = Trace_core.explicit_span_ctx = {
  1. span : span;
    (*

    The current span

    *)
  2. trace_id : trace_id;
    (*

    The trace this belongs to

    *)
}

A context, passed around for async traces.

  • since 0.10
type explicit_span = Trace_core.explicit_span = {
  1. span : span;
    (*

    Identifier for this span. Several explicit spans might share the same identifier since we can differentiate between them via meta.

    *)
  2. trace_id : trace_id;
    (*

    The trace this belongs to

    *)
  3. mutable meta : Trace_core.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.

module Collector = Trace_core.Collector
module Meta_map = Trace_core.Meta_map
module Level = Trace_core.Level

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 ctx_of_span : explicit_span -> explicit_span_ctx

Turn a span into a span context.

  • since 0.10
val with_span : +Trace (trace.Trace)

Module Trace

include module type of struct include Trace_core end
type span = Trace_core.span = ..

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

type parent = Trace_core.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 NEXT_RELEASE
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 = Trace_core.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 NEXT_RELEASE
module Collector = Trace_core.Collector
module Level = Trace_core.Level

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.

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 : + '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 NEXT_RELEASE.

  • parameter params

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

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.

  • parameter level

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

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.

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 enter_manual_span : + 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 NEXT_RELEASE.

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

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 NEXT_RELEASE

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 NEXT_RELEASE

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

Extensions

type extension_event = ..

Extension event

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

  • since 0.8

Core extensions

module Core_ext = Trace_core.Core_ext

Deprecated

val enter_manual_span : parent:explicit_span_ctx option -> - ?flavor:span_flavor -> + ?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.

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

  • parameter flavor

    a description of the span that can be used by the Collector.S to decide how to represent the span. Typically, `Sync spans start and stop on one thread, and are nested purely by their timestamp; and `Async spans can overlap, migrate between threads, etc. (as happens in Lwt, Eio, Async, etc.) which impacts how the collector might represent them.

  • parameter level

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

  • since 0.10
val enter_manual_sub_span : + explicit_span
  • deprecated use enter_span
val enter_manual_sub_span : parent:explicit_span -> ?flavor:[ `Sync | `Async ] -> ?level:Level.t -> @@ -32,7 +61,7 @@ __LINE__:int -> ?data:(unit -> (string * user_data) list) -> string -> - explicit_span
val enter_manual_toplevel_span : + explicit_span
val enter_manual_toplevel_span : ?flavor:[ `Sync | `Async ] -> ?level:Level.t -> ?__FUNCTION__:string -> @@ -40,27 +69,7 @@ __LINE__:int -> ?data:(unit -> (string * user_data) list) -> string -> - explicit_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.

  • since 0.3
val add_data_to_manual_span : + explicit_span
val exit_manual_span : explicit_span -> unit
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.

  • since 0.4
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.

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

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

  • parameter level

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

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.

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.

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.

  • 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 -> - ?data:(unit -> (string * user_data) list) -> - string -> - float -> - unit

Emit a counter of type float. 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 = (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.

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

Extensions

type extension_event = ..

Extension event

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

  • since 0.8
+ unit
diff --git a/trace/Trace_core/Collector/Callbacks/index.html b/trace/Trace_core/Collector/Callbacks/index.html new file mode 100644 index 0000000..f788522 --- /dev/null +++ b/trace/Trace_core/Collector/Callbacks/index.html @@ -0,0 +1,138 @@ + +Callbacks (trace.Trace_core.Collector.Callbacks)

Module Collector.Callbacks

type 'st t = {
  1. enter_span : 'st -> + __FUNCTION__:string option -> + __FILE__:string -> + __LINE__:int -> + params:Trace_core__.Types.extension_parameter list -> + data: + (string + * [ `Int of int + | `String of string + | `Bool of bool + | `Float of float + | `None ]) + list -> + parent:Trace_core__.Types.parent -> + string -> + Trace_core__.Types.span;
    (*

    Enter a span

    *)
  2. exit_span : 'st -> Trace_core__.Types.span -> unit;
    (*

    Exit a span. Must be called exactly once per span. Additional constraints on nesting, threads, etc. vary per collector.

    *)
  3. add_data_to_span : 'st -> + Trace_core__.Types.span -> + (string + * [ `Int of int + | `String of string + | `Bool of bool + | `Float of float + | `None ]) + list -> + unit;
  4. message : 'st -> + params:Trace_core__.Types.extension_parameter list -> + data: + (string + * [ `Int of int + | `String of string + | `Bool of bool + | `Float of float + | `None ]) + list -> + span:Trace_core__.Types.span option -> + string -> + unit;
    (*

    Emit a message or log

    *)
  5. counter_int : 'st -> + params:Trace_core__.Types.extension_parameter list -> + data: + (string + * [ `Int of int + | `String of string + | `Bool of bool + | `Float of float + | `None ]) + list -> + string -> + int -> + unit;
    (*

    Integer counter.

    *)
  6. counter_float : 'st -> + params:Trace_core__.Types.extension_parameter list -> + data: + (string + * [ `Int of int + | `String of string + | `Bool of bool + | `Float of float + | `None ]) + list -> + string -> + float -> + unit;
  7. extension : 'st -> Trace_core__.Types.extension_event -> unit;
    (*

    Collector-specific extension

    *)
  8. init : 'st -> unit;
    (*

    Called on initialization

    *)
  9. shutdown : 'st -> unit;
    (*

    Shutdown collector, possibly waiting for it to finish sending data.

    *)
}

Callbacks taking a state 'st

val make : + enter_span: + ('a -> + __FUNCTION__:string option -> + __FILE__:string -> + __LINE__:int -> + params:Trace_core__.Types.extension_parameter list -> + data: + (string + * [ `Int of int + | `String of string + | `Bool of bool + | `Float of float + | `None ]) + list -> + parent:Trace_core__.Types.parent -> + string -> + Trace_core__.Types.span) -> + exit_span:('a -> Trace_core__.Types.span -> unit) -> + add_data_to_span: + ('a -> + Trace_core__.Types.span -> + (string + * [ `Int of int + | `String of string + | `Bool of bool + | `Float of float + | `None ]) + list -> + unit) -> + message: + ('a -> + params:Trace_core__.Types.extension_parameter list -> + data: + (string + * [ `Int of int + | `String of string + | `Bool of bool + | `Float of float + | `None ]) + list -> + span:Trace_core__.Types.span option -> + string -> + unit) -> + counter_int: + ('a -> + params:Trace_core__.Types.extension_parameter list -> + data: + (string + * [ `Int of int + | `String of string + | `Bool of bool + | `Float of float + | `None ]) + list -> + string -> + int -> + unit) -> + counter_float: + ('a -> + params:Trace_core__.Types.extension_parameter list -> + data: + (string + * [ `Int of int + | `String of string + | `Bool of bool + | `Float of float + | `None ]) + list -> + string -> + float -> + unit) -> + ?extension:('a -> Trace_core__.Types.extension_event -> unit) -> + ?init:('a -> unit) -> + ?shutdown:('a -> unit) -> + unit -> + 'a t

Helper to create backends in a future-proof way

diff --git a/trace/Trace_core/Collector/index.html b/trace/Trace_core/Collector/index.html index f60f411..109c0ef 100644 --- a/trace/Trace_core/Collector/index.html +++ b/trace/Trace_core/Collector/index.html @@ -1,2 +1,2 @@ -Collector (trace.Trace_core.Collector)

Module Trace_core.Collector

A global collector.

The collector, if present, is responsible for collecting messages and spans, and storing them, recording them, forward them, or offering them to other services and processes.

val dummy_span : int64
val dummy_trace_id : string
val dummy_explicit_span : Trace_core__.Types.explicit_span
val dummy_explicit_span_ctx : Trace_core__.Types.explicit_span_ctx
module type S = sig ... end

Signature for a collector.

+Collector (trace.Trace_core.Collector)

Module Trace_core.Collector

A global collector.

The collector, if present, is responsible for collecting messages and spans, and storing them, recording them, forward them, or offering them to other services and processes.

type Trace_core__.Types.span +=
  1. | Span_dummy
val dummy_span : Trace_core__.Types.span

A fake span that never emits data. All collectors should handle this span by doing nothing.

module Callbacks : sig ... end
type t =
  1. | C_none
    (*

    No collector.

    *)
  2. | C_some : 'st * 'st Callbacks.t -> t
    (*

    Collector with a state and some callbacks.

    *)

Definition of a collector.

This is only relevant to implementors of tracing backends; to instrument your code you only need to look at the Trace module.

The definition changed since NEXT_RELEASE to a record of callbacks + a state

val is_some : t -> bool
diff --git a/trace/Trace_core/Collector/module-type-S/index.html b/trace/Trace_core/Collector/module-type-S/index.html deleted file mode 100644 index a0c527d..0000000 --- a/trace/Trace_core/Collector/module-type-S/index.html +++ /dev/null @@ -1,95 +0,0 @@ - -S (trace.Trace_core.Collector.S)

Module type Collector.S

Signature for a collector.

This is only relevant to implementors of tracing backends; to instrument your code you only need to look at the Trace module.

val with_span : - __FUNCTION__:string option -> - __FILE__:string -> - __LINE__:int -> - data: - (string - * [ `Int of int - | `String of string - | `Bool of bool - | `Float of float - | `None ]) - list -> - string -> - (int64 -> 'a) -> - 'a

Run the function in a new span.

  • since 0.3
val enter_span : - __FUNCTION__:string option -> - __FILE__:string -> - __LINE__:int -> - data: - (string - * [ `Int of int - | `String of string - | `Bool of bool - | `Float of float - | `None ]) - list -> - string -> - int64

Enter a new implicit span. For many uses cases, with_span will be easier to use.

  • since 0.6
val exit_span : int64 -> unit

Exit span. This should be called on the same thread as the corresponding enter_span, and nest properly with other calls to enter/exit_span and with_span.

  • since 0.6
val enter_manual_span : - parent:Trace_core__.Types.explicit_span_ctx option -> - flavor:[ `Sync | `Async ] option -> - __FUNCTION__:string option -> - __FILE__:string -> - __LINE__:int -> - data: - (string - * [ `Int of int - | `String of string - | `Bool of bool - | `Float of float - | `None ]) - list -> - string -> - Trace_core__.Types.explicit_span

Enter an explicit span. Surrounding scope, if any, is provided by parent, and this function can store as much metadata as it wants in the hmap in the explicit_span's meta field.

NOTE the parent argument is now an explicit_span_ctx and not an explicit_span since 0.10.

This means that the collector doesn't need to implement contextual storage mapping span to scopes, metadata, etc. on its side; everything can be transmitted in the explicit_span.

  • since 0.3
val exit_manual_span : Trace_core__.Types.explicit_span -> unit

Exit an explicit span.

  • since 0.3
val add_data_to_span : - int64 -> - (string - * [ `Int of int - | `String of string - | `Bool of bool - | `Float of float - | `None ]) - list -> - unit
  • since Adds data to the current span.

0.4

val add_data_to_manual_span : - Trace_core__.Types.explicit_span -> - (string - * [ `Int of int - | `String of string - | `Bool of bool - | `Float of float - | `None ]) - list -> - unit

Adds data to the given span.

  • since 0.4
val message : - ?span:int64 -> - data: - (string - * [ `Int of int - | `String of string - | `Bool of bool - | `Float of float - | `None ]) - list -> - string -> - unit

Emit a message with associated metadata.

val name_thread : string -> unit

Give a name to the current thread.

val name_process : string -> unit

Give a name to the current process.

val counter_int : - data: - (string - * [ `Int of int - | `String of string - | `Bool of bool - | `Float of float - | `None ]) - list -> - string -> - int -> - unit

Integer counter.

val counter_float : - data: - (string - * [ `Int of int - | `String of string - | `Bool of bool - | `Float of float - | `None ]) - list -> - string -> - float -> - unit

Float counter.

val extension_event : Trace_core__.Types.extension_event -> unit

Handle an extension event. A collector MUST simple ignore events it doesn't know, and return () silently.

  • since 0.8
val shutdown : unit -> unit

Shutdown collector, possibly waiting for it to finish sending data.

diff --git a/trace/Trace_core/Core_ext/index.html b/trace/Trace_core/Core_ext/index.html new file mode 100644 index 0000000..5b83378 --- /dev/null +++ b/trace/Trace_core/Core_ext/index.html @@ -0,0 +1,2 @@ + +Core_ext (trace.Trace_core.Core_ext)

Module Trace_core.Core_ext

A few core extensions.

  • since NEXT_RELEASE
type Trace_core__.Types.extension_event +=
  1. | Extension_set_thread_name of string
  2. | Extension_set_process_name of string

Additional extensions

type Trace_core__.Types.extension_parameter +=
  1. | Extension_span_flavor of [ `Async | `Sync ]
    (*

    Tell the backend if this is a sync or async span

    *)

Specialized parameters

diff --git a/trace/Trace_core/Meta_map/Key/index.html b/trace/Trace_core/Meta_map/Key/index.html deleted file mode 100644 index 07b4b85..0000000 --- a/trace/Trace_core/Meta_map/Key/index.html +++ /dev/null @@ -1,2 +0,0 @@ - -Key (trace.Trace_core.Meta_map.Key)

Module Meta_map.Key

type 'a t = (module KEY_IMPL with type t = 'a)
val _n : int ref
val create : unit -> (module KEY_IMPL with type t = 'k)
val id : (module KEY_IMPL with type t = 'k) -> int
val equal : 'a 'b. 'a t -> 'b t -> bool
diff --git a/trace/Trace_core/Meta_map/M/index.html b/trace/Trace_core/Meta_map/M/index.html deleted file mode 100644 index 261f354..0000000 --- a/trace/Trace_core/Meta_map/M/index.html +++ /dev/null @@ -1,6 +0,0 @@ - -M (trace.Trace_core.Meta_map.M)

Module Meta_map.M

type key = int
type !+'a t
val empty : 'a t
val add : key -> 'a -> 'a t -> 'a t
val add_to_list : key -> 'a -> 'a list t -> 'a list t
val update : key -> ('a option -> 'a option) -> 'a t -> 'a t
val singleton : key -> 'a -> 'a t
val remove : key -> 'a t -> 'a t
val merge : - (key -> 'a option -> 'b option -> 'c option) -> - 'a t -> - 'b t -> - 'c t
val union : (key -> 'a -> 'a -> 'a option) -> 'a t -> 'a t -> 'a t
val cardinal : 'a t -> int
val bindings : 'a t -> (key * 'a) list
val min_binding : 'a t -> key * 'a
val min_binding_opt : 'a t -> (key * 'a) option
val max_binding : 'a t -> key * 'a
val max_binding_opt : 'a t -> (key * 'a) option
val choose : 'a t -> key * 'a
val choose_opt : 'a t -> (key * 'a) option
val find : key -> 'a t -> 'a
val find_opt : key -> 'a t -> 'a option
val find_first : (key -> bool) -> 'a t -> key * 'a
val find_first_opt : (key -> bool) -> 'a t -> (key * 'a) option
val find_last : (key -> bool) -> 'a t -> key * 'a
val find_last_opt : (key -> bool) -> 'a t -> (key * 'a) option
val iter : (key -> 'a -> unit) -> 'a t -> unit
val fold : (key -> 'a -> 'acc -> 'acc) -> 'a t -> 'acc -> 'acc
val map : ('a -> 'b) -> 'a t -> 'b t
val mapi : (key -> 'a -> 'b) -> 'a t -> 'b t
val filter : (key -> 'a -> bool) -> 'a t -> 'a t
val filter_map : (key -> 'a -> 'b option) -> 'a t -> 'b t
val partition : (key -> 'a -> bool) -> 'a t -> 'a t * 'a t
val split : key -> 'a t -> 'a t * 'a option * 'a t
val is_empty : 'a t -> bool
val mem : key -> 'a t -> bool
val equal : ('a -> 'a -> bool) -> 'a t -> 'a t -> bool
val compare : ('a -> 'a -> int) -> 'a t -> 'a t -> int
val for_all : (key -> 'a -> bool) -> 'a t -> bool
val exists : (key -> 'a -> bool) -> 'a t -> bool
val to_list : 'a t -> (key * 'a) list
val of_list : (key * 'a) list -> 'a t
val to_seq : 'a t -> (key * 'a) Stdlib.Seq.t
val to_rev_seq : 'a t -> (key * 'a) Stdlib.Seq.t
val to_seq_from : key -> 'a t -> (key * 'a) Stdlib.Seq.t
val add_seq : (key * 'a) Stdlib.Seq.t -> 'a t -> 'a t
val of_seq : (key * 'a) Stdlib.Seq.t -> 'a t
diff --git a/trace/Trace_core/Meta_map/index.html b/trace/Trace_core/Meta_map/index.html deleted file mode 100644 index 50926fa..0000000 --- a/trace/Trace_core/Meta_map/index.html +++ /dev/null @@ -1,2 +0,0 @@ - -Meta_map (trace.Trace_core.Meta_map)

Module Trace_core.Meta_map

module type KEY_IMPL = sig ... end
module Key : sig ... end
type 'a key = 'a Key.t
type binding =
  1. | B : 'a Key.t * 'a -> binding
module M : sig ... end
type t = {
  1. m : exn_pair M.t;
}
val empty : t
val mem : (module KEY_IMPL with type t = 'a) -> t -> bool
val find_exn : 'a Key.t -> t -> 'a
val find : 'a Key.t -> t -> 'a option
val add : 'a Key.t -> 'a -> t -> t
val remove : 'a Key.t -> t -> t
val cardinal : t -> int
val length : t -> int
val iter : (binding -> unit) -> t -> unit
val to_list : t -> binding list
val add_list : t -> binding list -> t
diff --git a/trace/Trace_core/Meta_map/module-type-KEY_IMPL/index.html b/trace/Trace_core/Meta_map/module-type-KEY_IMPL/index.html deleted file mode 100644 index 2a58dfe..0000000 --- a/trace/Trace_core/Meta_map/module-type-KEY_IMPL/index.html +++ /dev/null @@ -1,2 +0,0 @@ - -KEY_IMPL (trace.Trace_core.Meta_map.KEY_IMPL)

Module type Meta_map.KEY_IMPL

type t
exception Store of t
val id : int
diff --git a/trace/Trace_core/index.html b/trace/Trace_core/index.html index f674433..ae5a83c 100644 --- a/trace/Trace_core/index.html +++ b/trace/Trace_core/index.html @@ -1,29 +1,58 @@ -Trace_core (trace.Trace_core)

Module Trace_core

Trace.

type span = int64

A span identifier.

The meaning of the identifier depends on the collector.

type trace_id = string

A bytestring representing a (possibly distributed) trace made of async spans. With opentelemetry this is 16 bytes.

  • since 0.10
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 span_flavor = [
  1. | `Sync
  2. | `Async
]

Some information about the span.

  • since NEXT_RELEASE
type explicit_span_ctx = {
  1. span : span;
    (*

    The current span

    *)
  2. trace_id : trace_id;
    (*

    The trace this belongs to

    *)
}

A context, passed around for async traces.

  • since 0.10
type explicit_span = {
  1. span : span;
    (*

    Identifier for this span. Several explicit spans might share the same identifier since we can differentiate between them via meta.

    *)
  2. trace_id : trace_id;
    (*

    The trace this belongs to

    *)
  3. 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.

module Collector : sig ... end

A global collector.

module Meta_map : sig ... end
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 ctx_of_span : explicit_span -> explicit_span_ctx

Turn a span into a span context.

  • since 0.10
val with_span : +Trace_core (trace.Trace_core)

Module Trace_core

Trace.

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

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 : + '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 NEXT_RELEASE.

  • parameter params

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

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.

  • parameter level

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

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.

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 enter_manual_span : + 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 NEXT_RELEASE.

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

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 NEXT_RELEASE

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 NEXT_RELEASE

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

Extensions

type extension_event = ..

Extension event

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

  • 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:span_flavor -> + ?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.

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

  • parameter flavor

    a description of the span that can be used by the Collector.S to decide how to represent the span. Typically, `Sync spans start and stop on one thread, and are nested purely by their timestamp; and `Async spans can overlap, migrate between threads, etc. (as happens in Lwt, Eio, Async, etc.) which impacts how the collector might represent them.

  • parameter level

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

  • since 0.10
val enter_manual_sub_span : + explicit_span
  • deprecated use enter_span
val enter_manual_sub_span : parent:explicit_span -> ?flavor:[ `Sync | `Async ] -> ?level:Level.t -> @@ -32,7 +61,7 @@ __LINE__:int -> ?data:(unit -> (string * user_data) list) -> string -> - explicit_span
val enter_manual_toplevel_span : + explicit_span
val enter_manual_toplevel_span : ?flavor:[ `Sync | `Async ] -> ?level:Level.t -> ?__FUNCTION__:string -> @@ -40,27 +69,7 @@ __LINE__:int -> ?data:(unit -> (string * user_data) list) -> string -> - explicit_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.

  • since 0.3
val add_data_to_manual_span : + explicit_span
val exit_manual_span : explicit_span -> unit
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.

  • since 0.4
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.

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

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

  • parameter level

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

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.

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.

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.

  • 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 -> - ?data:(unit -> (string * user_data) list) -> - string -> - float -> - unit

Emit a counter of type float. 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 = (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.

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

Extensions

type extension_event = ..

Extension event

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

  • since 0.8
+ unit
diff --git a/trace/Trace_core__Meta_map/index.html b/trace/Trace_core__Core_ext/index.html similarity index 75% rename from trace/Trace_core__Meta_map/index.html rename to trace/Trace_core__Core_ext/index.html index 437902f..f373935 100644 --- a/trace/Trace_core__Meta_map/index.html +++ b/trace/Trace_core__Core_ext/index.html @@ -1,2 +1,2 @@ -Trace_core__Meta_map (trace.Trace_core__Meta_map)

Module Trace_core__Meta_map

This module is hidden.

+Trace_core__Core_ext (trace.Trace_core__Core_ext)

Module Trace_core__Core_ext

This module is hidden.

diff --git a/trace/Trace_debug/Track_spans/index.html b/trace/Trace_debug/Track_spans/index.html new file mode 100644 index 0000000..defb342 --- /dev/null +++ b/trace/Trace_debug/Track_spans/index.html @@ -0,0 +1,5 @@ + +Track_spans (trace.Trace_debug.Track_spans)

Module Trace_debug.Track_spans

type unclosed_spans = {
  1. num : int;
  2. by_name : (string * int) list;
}
val track : + ?on_lingering_spans:[ `Out of out_channel | `Call of unclosed_spans -> unit ] -> + Trace_core.Collector.t -> + Trace_core.Collector.t

Modify the enter/exit span functions to track the set of spans that are open, and warn at the end if some are not closed.

implementation notes: for now this uses a regular Hashtbl protected by a mutex, so runtime overhead isn't trivial.

  • parameter on_lingering_spans

    what to do with the non-closed spans

diff --git a/trace/Trace_debug/index.html b/trace/Trace_debug/index.html new file mode 100644 index 0000000..9660146 --- /dev/null +++ b/trace/Trace_debug/index.html @@ -0,0 +1,2 @@ + +Trace_debug (trace.Trace_debug)

Module Trace_debug

module Track_spans : sig ... end
diff --git a/trace/Trace_debug__Track_spans/index.html b/trace/Trace_debug__Track_spans/index.html new file mode 100644 index 0000000..117873b --- /dev/null +++ b/trace/Trace_debug__Track_spans/index.html @@ -0,0 +1,2 @@ + +Trace_debug__Track_spans (trace.Trace_debug__Track_spans)

Module Trace_debug__Track_spans

This module is hidden.

diff --git a/trace/Trace_event/Event/index.html b/trace/Trace_event/Event/index.html deleted file mode 100644 index a96e3d6..0000000 --- a/trace/Trace_event/Event/index.html +++ /dev/null @@ -1,2 +0,0 @@ - -Event (trace.Trace_event.Event)

Module Trace_event.Event

Events.

Each callback in a subscriber corresponds to an event, which can be for example queued somewhere or batched for further processing.

module Sub = Trace_subscriber
type t =
  1. | E_tick
  2. | E_init of {
    1. time_ns : int64;
    }
  3. | E_shutdown of {
    1. time_ns : int64;
    }
  4. | E_message of {
    1. tid : int;
    2. msg : string;
    3. time_ns : int64;
    4. data : (string * Trace_core.user_data) list;
    }
  5. | E_define_span of {
    1. tid : int;
    2. name : string;
    3. time_ns : int64;
    4. id : Trace_core.span;
    5. fun_name : string option;
    6. data : (string * Trace_core.user_data) list;
    }
  6. | E_exit_span of {
    1. id : Trace_core.span;
    2. time_ns : int64;
    }
  7. | E_add_data of {
    1. id : Trace_core.span;
    2. data : (string * Trace_core.user_data) list;
    }
  8. | E_enter_manual_span of {
    1. tid : int;
    2. name : string;
    3. time_ns : int64;
    4. id : Trace_core.trace_id;
    5. flavor : Trace_core.span_flavor option;
    6. fun_name : string option;
    7. data : (string * Trace_core.user_data) list;
    }
  9. | E_exit_manual_span of {
    1. tid : int;
    2. name : string;
    3. time_ns : int64;
    4. flavor : Trace_core.span_flavor option;
    5. data : (string * Trace_core.user_data) list;
    6. id : Trace_core.trace_id;
    }
  10. | E_counter of {
    1. name : string;
    2. tid : int;
    3. time_ns : int64;
    4. n : float;
    }
  11. | E_name_process of {
    1. name : string;
    }
  12. | E_name_thread of {
    1. tid : int;
    2. name : string;
    }
  13. | E_extension_event of {
    1. tid : int;
    2. time_ns : int64;
    3. ext : Trace_core.extension_event;
    }

An event with TEF/fuchsia semantics

diff --git a/trace/Trace_event/Subscriber/Callbacks/index.html b/trace/Trace_event/Subscriber/Callbacks/index.html deleted file mode 100644 index dab2890..0000000 --- a/trace/Trace_event/Subscriber/Callbacks/index.html +++ /dev/null @@ -1,57 +0,0 @@ - -Callbacks (trace.Trace_event.Subscriber.Callbacks)

Module Subscriber.Callbacks

type st = event_consumer

Type of the state passed to every callback.

val on_init : st -> time_ns:int64 -> unit

Called when the subscriber is initialized in a collector

val new_span : st -> Trace_core.span

How to generate a new span?

  • since NEXT_RELEASE
val new_trace_id : st -> Trace_core.trace_id

How to generate a new trace ID?

  • since NEXT_RELEASE
val on_shutdown : st -> time_ns:int64 -> unit

Called when the collector is shutdown

val on_name_thread : st -> time_ns:int64 -> tid:int -> name:string -> unit

Current thread is being named

val on_name_process : st -> time_ns:int64 -> tid:int -> name:string -> unit

Current process is being named

val on_enter_span : - st -> - __FUNCTION__:string option -> - __FILE__:string -> - __LINE__:int -> - time_ns:int64 -> - tid:int -> - data:(string * Trace_core.user_data) list -> - name:string -> - Trace_core.span -> - unit

Enter a regular (sync) span

val on_exit_span : st -> time_ns:int64 -> tid:int -> Trace_core.span -> unit

Exit a span. This and on_enter_span must follow strict stack discipline

val on_add_data : - st -> - data:(string * Trace_core.user_data) list -> - Trace_core.span -> - unit

Add data to a regular span (which must be active)

val on_message : - st -> - time_ns:int64 -> - tid:int -> - span:Trace_core.span option -> - data:(string * Trace_core.user_data) list -> - string -> - unit

Emit a log message

val on_counter : - st -> - time_ns:int64 -> - tid:int -> - data:(string * Trace_core.user_data) list -> - name:string -> - float -> - unit

Emit the current value of a counter

val on_enter_manual_span : - st -> - __FUNCTION__:string option -> - __FILE__:string -> - __LINE__:int -> - time_ns:int64 -> - tid:int -> - parent:Trace_core.span option -> - data:(string * Trace_core.user_data) list -> - name:string -> - flavor:Trace_core.span_flavor option -> - trace_id:Trace_core.trace_id -> - Trace_core.span -> - unit

Enter a manual (possibly async) span

val on_exit_manual_span : - st -> - time_ns:int64 -> - tid:int -> - name:string -> - data:(string * Trace_core.user_data) list -> - flavor:Trace_core.span_flavor option -> - trace_id:Trace_core.trace_id -> - Trace_core.span -> - unit

Exit a manual span

val on_extension_event : - st -> - time_ns:int64 -> - tid:int -> - Trace_core.extension_event -> - unit

Extension event

  • since 0.8
diff --git a/trace/Trace_event/Subscriber/index.html b/trace/Trace_event/Subscriber/index.html deleted file mode 100644 index 0f422b6..0000000 --- a/trace/Trace_event/Subscriber/index.html +++ /dev/null @@ -1,3 +0,0 @@ - -Subscriber (trace.Trace_event.Subscriber)

Module Trace_event.Subscriber

Subscriber that emits events

type event_consumer = {
  1. on_event : Event.t -> unit;
}

Callback for events.

A subscriber that turns calls into events that are passed to the event_consumer

diff --git a/trace/Trace_event/index.html b/trace/Trace_event/index.html deleted file mode 100644 index cd2213c..0000000 --- a/trace/Trace_event/index.html +++ /dev/null @@ -1,2 +0,0 @@ - -Trace_event (trace.Trace_event)

Module Trace_event

module Event : sig ... end

Events.

module Subscriber : sig ... end

Subscriber that emits events

diff --git a/trace/Trace_event__Event/index.html b/trace/Trace_event__Event/index.html deleted file mode 100644 index 6c10a83..0000000 --- a/trace/Trace_event__Event/index.html +++ /dev/null @@ -1,2 +0,0 @@ - -Trace_event__Event (trace.Trace_event__Event)

Module Trace_event__Event

This module is hidden.

diff --git a/trace/Trace_private_util/Domain_util/index.html b/trace/Trace_private_util/Domain_util/index.html deleted file mode 100644 index c3df095..0000000 --- a/trace/Trace_private_util/Domain_util/index.html +++ /dev/null @@ -1,2 +0,0 @@ - -Domain_util (trace.Trace_private_util.Domain_util)

Module Trace_private_util.Domain_util

val cpu_relax : unit -> unit
val n_domains : unit -> int
diff --git a/trace/Trace_private_util/index.html b/trace/Trace_private_util/index.html deleted file mode 100644 index 0ff145a..0000000 --- a/trace/Trace_private_util/index.html +++ /dev/null @@ -1,2 +0,0 @@ - -Trace_private_util (trace.Trace_private_util)

Module Trace_private_util

module Domain_util : sig ... end
module Rpool : sig ... end

A resource pool (for buffers)

diff --git a/trace/Trace_private_util__Domain_util/index.html b/trace/Trace_private_util__Domain_util/index.html deleted file mode 100644 index f463e07..0000000 --- a/trace/Trace_private_util__Domain_util/index.html +++ /dev/null @@ -1,2 +0,0 @@ - -Trace_private_util__Domain_util (trace.Trace_private_util__Domain_util)

Module Trace_private_util__Domain_util

This module is hidden.

diff --git a/trace/Trace_simple/Simple_span/index.html b/trace/Trace_simple/Simple_span/index.html new file mode 100644 index 0000000..09798be --- /dev/null +++ b/trace/Trace_simple/Simple_span/index.html @@ -0,0 +1,2 @@ + +Simple_span (trace.Trace_simple.Simple_span)

Module Trace_simple.Simple_span

A simple span.

This is a concrete representation of spans that is convenient to manipulate.

  • since NEXT_RELEASE
type span_flavor = [
  1. | `Sync
  2. | `Async
]
type t = {
  1. name : string;
  2. __FUNCTION__ : string option;
  3. __FILE__ : string;
  4. __LINE__ : int;
  5. time_ns : int64;
    (*

    Time the span was entered.

    *)
  6. mutable time_exit_ns : int64;
    (*

    Time the span was exited. Set at exit, Int64.max_int otherwise

    *)
  7. tid : int;
    (*

    Thread in which span was created

    *)
  8. trace_id : int64;
    (*

    For async spans

    *)
  9. parent : Trace_core.parent;
  10. flavor : span_flavor;
  11. params : Trace_core.extension_parameter list;
  12. mutable data : (string * Trace_core.user_data) list;
    (*

    Modified by add_data_to_span

    *)
}

The type of spans used by all subscribers.

type Trace_core.span +=
  1. | Span_simple of t
    (*

    How to turn a Simple_span.t into a span.

    *)
diff --git a/trace/Trace_simple/index.html b/trace/Trace_simple/index.html new file mode 100644 index 0000000..1f59d89 --- /dev/null +++ b/trace/Trace_simple/index.html @@ -0,0 +1,2 @@ + +Trace_simple (trace.Trace_simple)

Module Trace_simple

module Simple_span : sig ... end

A simple span.

diff --git a/trace/Trace_private_util__Rpool/index.html b/trace/Trace_simple__Simple_span/index.html similarity index 68% rename from trace/Trace_private_util__Rpool/index.html rename to trace/Trace_simple__Simple_span/index.html index 37dbce9..2f63eac 100644 --- a/trace/Trace_private_util__Rpool/index.html +++ b/trace/Trace_simple__Simple_span/index.html @@ -1,2 +1,2 @@ -Trace_private_util__Rpool (trace.Trace_private_util__Rpool)

Module Trace_private_util__Rpool

This module is hidden.

+Trace_simple__Simple_span (trace.Trace_simple__Simple_span)

Module Trace_simple__Simple_span

This module is hidden.

diff --git a/trace/Trace_subscriber/Callbacks/Dummy/index.html b/trace/Trace_subscriber/Callbacks/Dummy/index.html deleted file mode 100644 index 6142625..0000000 --- a/trace/Trace_subscriber/Callbacks/Dummy/index.html +++ /dev/null @@ -1,38 +0,0 @@ - -Dummy (trace.Trace_subscriber.Callbacks.Dummy)

Module Callbacks.Dummy

Dummy callbacks. It can be useful to reuse some of these functions in a real subscriber that doesn't want to handle all events, but only some of them.

To write a subscriber that only supports some callbacks, this can be handy:

  module My_callbacks = struct
-  type st = my_own_state
-  include Callbacks.Dummy
-  let on_counter (st:st) ~time_ns ~tid ~data ~name v : unit = ...
-  end
val on_init : 'a -> time_ns:'b -> unit
val new_span : 'a -> int64
val new_trace_id : 'a -> string
val on_shutdown : 'a -> time_ns:'b -> unit
val on_name_thread : 'a -> time_ns:'b -> tid:'c -> name:'d -> unit
val on_name_process : 'a -> time_ns:'b -> tid:'c -> name:'d -> unit
val on_message : 'a -> time_ns:'b -> tid:'c -> span:'d -> data:'e -> 'f -> unit
val on_counter : 'a -> time_ns:'b -> tid:'c -> data:'d -> name:'e -> 'f -> unit
val on_enter_span : - 'a -> - __FUNCTION__:'b -> - __FILE__:'c -> - __LINE__:'d -> - time_ns:'e -> - tid:'f -> - data:'g -> - name:'h -> - 'i -> - unit
val on_exit_span : 'a -> time_ns:'b -> tid:'c -> 'd -> unit
val on_add_data : 'a -> data:'b -> 'c -> unit
val on_enter_manual_span : - 'a -> - __FUNCTION__:'b -> - __FILE__:'c -> - __LINE__:'d -> - time_ns:'e -> - tid:'f -> - parent:'g -> - data:'h -> - name:'i -> - flavor:'j -> - trace_id:'k -> - 'l -> - unit
val on_exit_manual_span : - 'a -> - time_ns:'b -> - tid:'c -> - name:'d -> - data:'e -> - flavor:'f -> - trace_id:'g -> - 'h -> - unit
val on_extension_event : 'a -> time_ns:'b -> tid:'c -> 'd -> unit
diff --git a/trace/Trace_subscriber/Callbacks/index.html b/trace/Trace_subscriber/Callbacks/index.html deleted file mode 100644 index afa38e1..0000000 --- a/trace/Trace_subscriber/Callbacks/index.html +++ /dev/null @@ -1,10 +0,0 @@ - -Callbacks (trace.Trace_subscriber.Callbacks)

Module Trace_subscriber.Callbacks

Callbacks used for subscribers.

Each subscriber defines a set of callbacks, for each possible tracing event. These callbacks take a custom state that is paired with the callbacks in Subscriber.t.

To use a default implementation for some callbacks, use:

  module My_callbacks = struct
-    type st = …
-
-    include Trace_subscriber.Callbacks.Dummy
-
-    let on_init (state:st) ~time_ns : unit = …
-
-    (* … other custom callbacks … *)
-  end

NOTE: the trace_id passed alongside manual spans is guaranteed to be at least 64 bits.

module type S = sig ... end

First class module signature for callbacks

type 'st t = (module S with type st = 'st)

Callbacks for a subscriber. There is one callback per event in Trace. The type 'st is the state that is passed to every single callback.

module Dummy : sig ... end

Dummy callbacks. It can be useful to reuse some of these functions in a real subscriber that doesn't want to handle all events, but only some of them.

val dummy : unit -> 'st t

Dummy callbacks, ignores all events.

diff --git a/trace/Trace_subscriber/Callbacks/module-type-S/index.html b/trace/Trace_subscriber/Callbacks/module-type-S/index.html deleted file mode 100644 index 1af353c..0000000 --- a/trace/Trace_subscriber/Callbacks/module-type-S/index.html +++ /dev/null @@ -1,57 +0,0 @@ - -S (trace.Trace_subscriber.Callbacks.S)

Module type Callbacks.S

First class module signature for callbacks

type st

Type of the state passed to every callback.

val on_init : st -> time_ns:int64 -> unit

Called when the subscriber is initialized in a collector

val new_span : st -> Trace_core.span

How to generate a new span?

  • since NEXT_RELEASE
val new_trace_id : st -> Trace_core.trace_id

How to generate a new trace ID?

  • since NEXT_RELEASE
val on_shutdown : st -> time_ns:int64 -> unit

Called when the collector is shutdown

val on_name_thread : st -> time_ns:int64 -> tid:int -> name:string -> unit

Current thread is being named

val on_name_process : st -> time_ns:int64 -> tid:int -> name:string -> unit

Current process is being named

val on_enter_span : - st -> - __FUNCTION__:string option -> - __FILE__:string -> - __LINE__:int -> - time_ns:int64 -> - tid:int -> - data:(string * Trace_core.user_data) list -> - name:string -> - Trace_core.span -> - unit

Enter a regular (sync) span

val on_exit_span : st -> time_ns:int64 -> tid:int -> Trace_core.span -> unit

Exit a span. This and on_enter_span must follow strict stack discipline

val on_add_data : - st -> - data:(string * Trace_core.user_data) list -> - Trace_core.span -> - unit

Add data to a regular span (which must be active)

val on_message : - st -> - time_ns:int64 -> - tid:int -> - span:Trace_core.span option -> - data:(string * Trace_core.user_data) list -> - string -> - unit

Emit a log message

val on_counter : - st -> - time_ns:int64 -> - tid:int -> - data:(string * Trace_core.user_data) list -> - name:string -> - float -> - unit

Emit the current value of a counter

val on_enter_manual_span : - st -> - __FUNCTION__:string option -> - __FILE__:string -> - __LINE__:int -> - time_ns:int64 -> - tid:int -> - parent:Trace_core.span option -> - data:(string * Trace_core.user_data) list -> - name:string -> - flavor:Trace_core.span_flavor option -> - trace_id:Trace_core.trace_id -> - Trace_core.span -> - unit

Enter a manual (possibly async) span

val on_exit_manual_span : - st -> - time_ns:int64 -> - tid:int -> - name:string -> - data:(string * Trace_core.user_data) list -> - flavor:Trace_core.span_flavor option -> - trace_id:Trace_core.trace_id -> - Trace_core.span -> - unit

Exit a manual span

val on_extension_event : - st -> - time_ns:int64 -> - tid:int -> - Trace_core.extension_event -> - unit

Extension event

  • since 0.8
diff --git a/trace/Trace_subscriber/Span_generator/index.html b/trace/Trace_subscriber/Span_generator/index.html deleted file mode 100644 index 7996848..0000000 --- a/trace/Trace_subscriber/Span_generator/index.html +++ /dev/null @@ -1,2 +0,0 @@ - -Span_generator (trace.Trace_subscriber.Span_generator)

Module Trace_subscriber.Span_generator

A counter-based span generator.

  • since NEXT_RELEASE
type t
val create : unit -> t
val mk_span : t -> Trace_core.span
diff --git a/trace/Trace_subscriber/Span_tbl/index.html b/trace/Trace_subscriber/Span_tbl/index.html deleted file mode 100644 index fe71411..0000000 --- a/trace/Trace_subscriber/Span_tbl/index.html +++ /dev/null @@ -1,2 +0,0 @@ - -Span_tbl (trace.Trace_subscriber.Span_tbl)

Module Trace_subscriber.Span_tbl

A table that can be used to remember information about spans.

This is convenient when we want to rememner information from a span begin, when dealing with the corresponding span end.

NOTE: this is thread safe when threads are enabled.

type 'v t
val create : unit -> 'v t
val add : 'v t -> Trace_core.span -> 'v -> unit
val find_exn : 'v t -> Trace_core.span -> 'v
  • raises Not_found

    if information isn't found

val remove : _ t -> Trace_core.span -> unit

Remove the span if present

val to_list : 'v t -> (Trace_core.span * 'v) list
diff --git a/trace/Trace_subscriber/Subscriber/index.html b/trace/Trace_subscriber/Subscriber/index.html deleted file mode 100644 index 3d73edb..0000000 --- a/trace/Trace_subscriber/Subscriber/index.html +++ /dev/null @@ -1,2 +0,0 @@ - -Subscriber (trace.Trace_subscriber.Subscriber)

Module Trace_subscriber.Subscriber

Trace subscribers

type t =
  1. | Sub : {
    1. st : 'st;
    2. callbacks : 'st Callbacks.t;
    } -> t

A trace subscriber. It pairs a set of callbacks with the state they need (which can contain a file handle, a socket to write events to, config, etc.).

The design goal for this is that it should be possible to avoid allocations whenever the trace collector invokes the callbacks.

val dummy : t

Dummy subscriber that ignores every call.

val tee_l : t list -> t

Tee multiple subscribers, ie return a subscriber that forwards to every subscriber in subs.

To generate a new span or trace ID, the first subscriber of the list is used.

val tee : t -> t -> t

tee s1 s2 is a subscriber that forwards every call to s1 and s2 both.

diff --git a/trace/Trace_subscriber/Trace_id_8B_generator/index.html b/trace/Trace_subscriber/Trace_id_8B_generator/index.html deleted file mode 100644 index 2ebdef8..0000000 --- a/trace/Trace_subscriber/Trace_id_8B_generator/index.html +++ /dev/null @@ -1,2 +0,0 @@ - -Trace_id_8B_generator (trace.Trace_subscriber.Trace_id_8B_generator)

Module Trace_subscriber.Trace_id_8B_generator

A counter-based trace ID generator, producing 8-byte trace IDs.

  • since NEXT_RELEASE
type t
val create : unit -> t
val mk_trace_id : t -> Trace_core.trace_id
diff --git a/trace/Trace_subscriber/index.html b/trace/Trace_subscriber/index.html deleted file mode 100644 index 831cf98..0000000 --- a/trace/Trace_subscriber/index.html +++ /dev/null @@ -1,2 +0,0 @@ - -Trace_subscriber (trace.Trace_subscriber)

Module Trace_subscriber

Generic subscribers.

This defines the notion of a subscriber, a set of callbacks for every trace event. It also defines a collector that needs to be installed for the subscriber(s) to be called.

Thanks to Subscriber.tee_l it's possible to combine multiple subscribers into a single collector.

  • since 0.8
module Callbacks : sig ... end

Callbacks used for subscribers.

module Subscriber : sig ... end

Trace subscribers

module Span_tbl : sig ... end

A table that can be used to remember information about spans.

Main API

type t = Subscriber.t

A trace subscriber. It pairs a set of callbacks with the state they need (which can contain a file handle, a socket to write events to, config, etc.).

The design goal for this is that it should be possible to avoid allocations whenever the trace collector invokes the callbacks.

val collector : t -> Trace_core.collector

A collector that calls the subscriber's callbacks.

It uses mtime (if available) to obtain timestamps.

module Span_generator : sig ... end

A counter-based span generator.

module Trace_id_8B_generator : sig ... end

A counter-based trace ID generator, producing 8-byte trace IDs.

diff --git a/trace/Trace_subscriber__Subscriber/index.html b/trace/Trace_subscriber__Subscriber/index.html deleted file mode 100644 index fe3242a..0000000 --- a/trace/Trace_subscriber__Subscriber/index.html +++ /dev/null @@ -1,2 +0,0 @@ - -Trace_subscriber__Subscriber (trace.Trace_subscriber__Subscriber)

Module Trace_subscriber__Subscriber

This module is hidden.

diff --git a/trace/Trace_util/Domain_util/index.html b/trace/Trace_util/Domain_util/index.html new file mode 100644 index 0000000..d9414a1 --- /dev/null +++ b/trace/Trace_util/Domain_util/index.html @@ -0,0 +1,2 @@ + +Domain_util (trace.Trace_util.Domain_util)

Module Trace_util.Domain_util

val cpu_relax : unit -> unit
val n_domains : unit -> int
diff --git a/trace/Trace_util/Mock_/Inner/index.html b/trace/Trace_util/Mock_/Inner/index.html new file mode 100644 index 0000000..7f3f0ca --- /dev/null +++ b/trace/Trace_util/Mock_/Inner/index.html @@ -0,0 +1,2 @@ + +Inner (trace.Trace_util.Mock_.Inner)

Module Mock_.Inner

val mock : bool ref
val get_now_ns_ref : (unit -> int64) ref
val get_tid_ref : (unit -> int) ref
val get_pid_ref : (unit -> int) ref
val make_time_mock : unit -> unit -> int64

used to mock timing

diff --git a/trace/Trace_util/Mock_/index.html b/trace/Trace_util/Mock_/index.html new file mode 100644 index 0000000..f172245 --- /dev/null +++ b/trace/Trace_util/Mock_/index.html @@ -0,0 +1,2 @@ + +Mock_ (trace.Trace_util.Mock_)

Module Trace_util.Mock_

Mocking for tests

module Inner : sig ... end
val now_ns : unit -> int64

Now, in nanoseconds. Uses get_now_ns_ref

val get_tid : unit -> int

Current thread's ID. Uses get_tid_ref

val get_pid : unit -> int
val mock_all : unit -> unit
diff --git a/trace/Trace_util/Multi_collector/index.html b/trace/Trace_util/Multi_collector/index.html new file mode 100644 index 0000000..dbf78ee --- /dev/null +++ b/trace/Trace_util/Multi_collector/index.html @@ -0,0 +1,5 @@ + +Multi_collector (trace.Trace_util.Multi_collector)

Module Trace_util.Multi_collector

Combine multiple collectors into one

Combine multiple collectors, ie return a collector that forwards to every collector in the list.

combine s1 s2 is a collector that forwards every call to s1 and s2 both.

diff --git a/trace/Trace_private_util/Rpool/index.html b/trace/Trace_util/Rpool/index.html similarity index 64% rename from trace/Trace_private_util/Rpool/index.html rename to trace/Trace_util/Rpool/index.html index f2322d7..401fbae 100644 --- a/trace/Trace_private_util/Rpool/index.html +++ b/trace/Trace_util/Rpool/index.html @@ -1,5 +1,5 @@ -Rpool (trace.Trace_private_util.Rpool)

Module Trace_private_util.Rpool

A resource pool (for buffers)

type 'a t
val create : +Rpool (trace.Trace_util.Rpool)

Module Trace_util.Rpool

A resource pool (for buffers)

type 'a t
val create : max_size:int -> create:(unit -> 'a) -> clear:('a -> unit) -> diff --git a/trace/Trace_util/Span_id64/Gen/index.html b/trace/Trace_util/Span_id64/Gen/index.html new file mode 100644 index 0000000..c8da474 --- /dev/null +++ b/trace/Trace_util/Span_id64/Gen/index.html @@ -0,0 +1,2 @@ + +Gen (trace.Trace_util.Span_id64.Gen)

Module Span_id64.Gen

type t
val create : unit -> t
val gen : t -> int64
diff --git a/trace/Trace_util/Span_id64/Trace_id_generator/index.html b/trace/Trace_util/Span_id64/Trace_id_generator/index.html new file mode 100644 index 0000000..8544561 --- /dev/null +++ b/trace/Trace_util/Span_id64/Trace_id_generator/index.html @@ -0,0 +1,2 @@ + +Trace_id_generator (trace.Trace_util.Span_id64.Trace_id_generator)

Module Span_id64.Trace_id_generator

type t = int Stdlib.Atomic.t
val create : unit -> int Stdlib.Atomic.t
val gen : int Stdlib.Atomic.t -> int64
diff --git a/trace/Trace_util/Span_id64/index.html b/trace/Trace_util/Span_id64/index.html new file mode 100644 index 0000000..e301323 --- /dev/null +++ b/trace/Trace_util/Span_id64/index.html @@ -0,0 +1,2 @@ + +Span_id64 (trace.Trace_util.Span_id64)

Module Trace_util.Span_id64

type t = int64
module Gen : sig ... end
module Trace_id_generator : sig ... end
diff --git a/trace/Trace_util/Thread_util/index.html b/trace/Trace_util/Thread_util/index.html new file mode 100644 index 0000000..fdeb0a0 --- /dev/null +++ b/trace/Trace_util/Thread_util/index.html @@ -0,0 +1,2 @@ + +Thread_util (trace.Trace_util.Thread_util)

Module Trace_util.Thread_util

val get_tid : unit -> int

Get current thread ID

diff --git a/trace/Trace_util/Time_util/index.html b/trace/Trace_util/Time_util/index.html new file mode 100644 index 0000000..7dd47b0 --- /dev/null +++ b/trace/Trace_util/Time_util/index.html @@ -0,0 +1,2 @@ + +Time_util (trace.Trace_util.Time_util)

Module Trace_util.Time_util

val get_time_ns : unit -> int64

Get current time in nanoseconds. The beginning point is unspecified, and this is assumed to be best-effort monotonic. Ideally, use mtime.

diff --git a/trace/Trace_util/Trace_id64/Gen/index.html b/trace/Trace_util/Trace_id64/Gen/index.html new file mode 100644 index 0000000..ea3abd7 --- /dev/null +++ b/trace/Trace_util/Trace_id64/Gen/index.html @@ -0,0 +1,2 @@ + +Gen (trace.Trace_util.Trace_id64.Gen)

Module Trace_id64.Gen

type t
val create : unit -> t
val gen : t -> int64
diff --git a/trace/Trace_util/Trace_id64/index.html b/trace/Trace_util/Trace_id64/index.html new file mode 100644 index 0000000..d08c795 --- /dev/null +++ b/trace/Trace_util/Trace_id64/index.html @@ -0,0 +1,2 @@ + +Trace_id64 (trace.Trace_util.Trace_id64)

Module Trace_util.Trace_id64

type t = int64
module Gen : sig ... end
diff --git a/trace/Trace_util/Unix_util/index.html b/trace/Trace_util/Unix_util/index.html new file mode 100644 index 0000000..fe103cd --- /dev/null +++ b/trace/Trace_util/Unix_util/index.html @@ -0,0 +1,2 @@ + +Unix_util (trace.Trace_util.Unix_util)

Module Trace_util.Unix_util

val get_pid : unit -> int
diff --git a/trace/Trace_util/index.html b/trace/Trace_util/index.html new file mode 100644 index 0000000..75bbd86 --- /dev/null +++ b/trace/Trace_util/index.html @@ -0,0 +1,2 @@ + +Trace_util (trace.Trace_util)

Module Trace_util

module Domain_util : sig ... end
module Mock_ : sig ... end

Mocking for tests

module Multi_collector : sig ... end

Combine multiple collectors into one

module Rpool : sig ... end

A resource pool (for buffers)

module Span_id64 : sig ... end
module Thread_util : sig ... end
module Time_util : sig ... end
module Trace_id64 : sig ... end
module Unix_util : sig ... end
diff --git a/trace/Trace_event__Subscriber/index.html b/trace/Trace_util__Domain_util/index.html similarity index 68% rename from trace/Trace_event__Subscriber/index.html rename to trace/Trace_util__Domain_util/index.html index 1460f57..1c6259d 100644 --- a/trace/Trace_event__Subscriber/index.html +++ b/trace/Trace_util__Domain_util/index.html @@ -1,2 +1,2 @@ -Trace_event__Subscriber (trace.Trace_event__Subscriber)

Module Trace_event__Subscriber

This module is hidden.

+Trace_util__Domain_util (trace.Trace_util__Domain_util)

Module Trace_util__Domain_util

This module is hidden.

diff --git a/trace/Trace_util__Mock_/index.html b/trace/Trace_util__Mock_/index.html new file mode 100644 index 0000000..6d20366 --- /dev/null +++ b/trace/Trace_util__Mock_/index.html @@ -0,0 +1,2 @@ + +Trace_util__Mock_ (trace.Trace_util__Mock_)

Module Trace_util__Mock_

This module is hidden.

diff --git a/trace/Trace_subscriber__Callbacks/index.html b/trace/Trace_util__Multi_collector/index.html similarity index 68% rename from trace/Trace_subscriber__Callbacks/index.html rename to trace/Trace_util__Multi_collector/index.html index 92b5df7..dd455ed 100644 --- a/trace/Trace_subscriber__Callbacks/index.html +++ b/trace/Trace_util__Multi_collector/index.html @@ -1,2 +1,2 @@ -Trace_subscriber__Callbacks (trace.Trace_subscriber__Callbacks)

Module Trace_subscriber__Callbacks

This module is hidden.

+Trace_util__Multi_collector (trace.Trace_util__Multi_collector)

Module Trace_util__Multi_collector

This module is hidden.

diff --git a/trace/Trace_util__Rpool/index.html b/trace/Trace_util__Rpool/index.html new file mode 100644 index 0000000..bdbf391 --- /dev/null +++ b/trace/Trace_util__Rpool/index.html @@ -0,0 +1,2 @@ + +Trace_util__Rpool (trace.Trace_util__Rpool)

Module Trace_util__Rpool

This module is hidden.

diff --git a/trace-tef/Trace_tef__Emit_tef/index.html b/trace/Trace_util__Span_id64/index.html similarity index 59% rename from trace-tef/Trace_tef__Emit_tef/index.html rename to trace/Trace_util__Span_id64/index.html index bc112a9..7a3da55 100644 --- a/trace-tef/Trace_tef__Emit_tef/index.html +++ b/trace/Trace_util__Span_id64/index.html @@ -1,2 +1,2 @@ -Trace_tef__Emit_tef (trace-tef.Trace_tef__Emit_tef)

Module Trace_tef__Emit_tef

This module is hidden.

+Trace_util__Span_id64 (trace.Trace_util__Span_id64)

Module Trace_util__Span_id64

This module is hidden.

diff --git a/trace-tef/Trace_tef__Subscriber/index.html b/trace/Trace_util__Thread_util/index.html similarity index 60% rename from trace-tef/Trace_tef__Subscriber/index.html rename to trace/Trace_util__Thread_util/index.html index a47f51a..a2c8059 100644 --- a/trace-tef/Trace_tef__Subscriber/index.html +++ b/trace/Trace_util__Thread_util/index.html @@ -1,2 +1,2 @@ -Trace_tef__Subscriber (trace-tef.Trace_tef__Subscriber)

Module Trace_tef__Subscriber

This module is hidden.

+Trace_util__Thread_util (trace.Trace_util__Thread_util)

Module Trace_util__Thread_util

This module is hidden.

diff --git a/trace/Trace_util__Time_util/index.html b/trace/Trace_util__Time_util/index.html new file mode 100644 index 0000000..250077e --- /dev/null +++ b/trace/Trace_util__Time_util/index.html @@ -0,0 +1,2 @@ + +Trace_util__Time_util (trace.Trace_util__Time_util)

Module Trace_util__Time_util

This module is hidden.

diff --git a/trace/Trace_util__Trace_id64/index.html b/trace/Trace_util__Trace_id64/index.html new file mode 100644 index 0000000..7f306a6 --- /dev/null +++ b/trace/Trace_util__Trace_id64/index.html @@ -0,0 +1,2 @@ + +Trace_util__Trace_id64 (trace.Trace_util__Trace_id64)

Module Trace_util__Trace_id64

This module is hidden.

diff --git a/trace/Trace_util__Unix_util/index.html b/trace/Trace_util__Unix_util/index.html new file mode 100644 index 0000000..3dad7e9 --- /dev/null +++ b/trace/Trace_util__Unix_util/index.html @@ -0,0 +1,2 @@ + +Trace_util__Unix_util (trace.Trace_util__Unix_util)

Module Trace_util__Unix_util

This module is hidden.

diff --git a/trace/index.html b/trace/index.html index ba7a77c..3ec58a7 100644 --- a/trace/index.html +++ b/trace/index.html @@ -1,2 +1,2 @@ -index (trace.index)

Package trace

Package info

changes-files
readme-files
+index (trace.index)

Package trace

Package info

changes-files
readme-files