From a20d2feb5d05b772a74d6d829daa7be7d9240dab Mon Sep 17 00:00:00 2001 From: c-cube Date: Tue, 13 Feb 2024 02:22:46 +0000 Subject: [PATCH] deploy: d3e710605e032d448d03838e53dd0128a1e3b20e --- trace/Trace/index.html | 24 ++++++++++++++-- trace/Trace_core/Collector/index.html | 2 +- .../Collector/module-type-S/index.html | 28 +++++++++++++++++-- trace/Trace_core/index.html | 24 ++++++++++++++-- trace/Trace_private_util/B_queue/index.html | 2 ++ .../Trace_private_util/Domain_util/index.html | 2 ++ trace/Trace_private_util/Mpsc_bag/index.html | 2 ++ 7 files changed, 75 insertions(+), 9 deletions(-) create mode 100644 trace/Trace_private_util/B_queue/index.html create mode 100644 trace/Trace_private_util/Domain_util/index.html create mode 100644 trace/Trace_private_util/Mpsc_bag/index.html diff --git a/trace/Trace/index.html b/trace/Trace/index.html index f49a636..37e0e16 100644 --- a/trace/Trace/index.html +++ b/trace/Trace/index.html @@ -1,18 +1,36 @@ -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 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).

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

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 with_span : +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 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 = 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. mutable meta : Trace_core.Meta_map.t;
    (*

    Metadata for this span (and its context)

    *)
}

Explicit span, with collector-specific metadata

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

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

with_span ~__FILE__ ~__LINE__ name f enters a new span sp, and calls f sp. sp might be a dummy span if no collector is installed. When f sp returns or raises, the span sp is exited.

This is the recommended way to instrument most code.

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.

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.

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 : ?__FUNCTION__:string -> __FILE__:string -> __LINE__:int -> ?data:(unit -> (string * user_data) list) -> string -> - span
val exit_span : span -> unit
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 : + span
val exit_span : span -> unit
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_sub_span : + parent:explicit_span -> + ?flavor:[ `Sync | `Async ] -> + ?__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.

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

  • since 0.3
val enter_manual_toplevel_span : + ?flavor:[ `Sync | `Async ] -> + ?__FUNCTION__:string -> + __FILE__:string -> + __LINE__:int -> + ?data:(unit -> (string * user_data) list) -> + string -> + explicit_span

Like with_span but the caller is responsible for carrying this explicit_span around until it's exited with exit_manual_span. The span can be used as a parent in enter_manual_sub_span.

  • since 0.3
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 -> + (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 : ?span:span -> ?data:(unit -> (string * user_data) list) -> string -> diff --git a/trace/Trace_core/Collector/index.html b/trace/Trace_core/Collector/index.html index 9c177d5..015d582 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
module type S = sig ... end

Signature for a collector.

\ No newline at end of file +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_explicit_span : Trace_core__.Types.explicit_span
module type S = sig ... end

Signature for a collector.

\ No newline at end of file diff --git a/trace/Trace_core/Collector/module-type-S/index.html b/trace/Trace_core/Collector/module-type-S/index.html index ec6b838..74c76cd 100644 --- a/trace/Trace_core/Collector/module-type-S/index.html +++ b/trace/Trace_core/Collector/module-type-S/index.html @@ -26,7 +26,22 @@ | `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 add_data_to_span : + 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 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.

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 @@ -35,7 +50,16 @@ | `Float of float | `None ]) list -> - unit
  • since Adds data to the current span.

0.4

val message : + 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 diff --git a/trace/Trace_core/index.html b/trace/Trace_core/index.html index 3d47938..5b1473a 100644 --- a/trace/Trace_core/index.html +++ b/trace/Trace_core/index.html @@ -1,18 +1,36 @@ -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 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).

module Collector : sig ... end

A global collector.

module Meta_map : sig ... end

Associative containers with Heterogeneous Values

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 with_span : +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 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 = {
  1. span : span;
    (*

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

    *)
  2. mutable meta : Meta_map.t;
    (*

    Metadata for this span (and its context)

    *)
}

Explicit span, with collector-specific metadata

module Collector : sig ... end

A global collector.

module Meta_map : sig ... end

Associative containers with Heterogeneous Values

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

with_span ~__FILE__ ~__LINE__ name f enters a new span sp, and calls f sp. sp might be a dummy span if no collector is installed. When f sp returns or raises, the span sp is exited.

This is the recommended way to instrument most code.

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.

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.

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 : ?__FUNCTION__:string -> __FILE__:string -> __LINE__:int -> ?data:(unit -> (string * user_data) list) -> string -> - span
val exit_span : span -> unit
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 : + span
val exit_span : span -> unit
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_sub_span : + parent:explicit_span -> + ?flavor:[ `Sync | `Async ] -> + ?__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.

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

  • since 0.3
val enter_manual_toplevel_span : + ?flavor:[ `Sync | `Async ] -> + ?__FUNCTION__:string -> + __FILE__:string -> + __LINE__:int -> + ?data:(unit -> (string * user_data) list) -> + string -> + explicit_span

Like with_span but the caller is responsible for carrying this explicit_span around until it's exited with exit_manual_span. The span can be used as a parent in enter_manual_sub_span.

  • since 0.3
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 -> + (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 : ?span:span -> ?data:(unit -> (string * user_data) list) -> string -> diff --git a/trace/Trace_private_util/B_queue/index.html b/trace/Trace_private_util/B_queue/index.html new file mode 100644 index 0000000..193dbc8 --- /dev/null +++ b/trace/Trace_private_util/B_queue/index.html @@ -0,0 +1,2 @@ + +B_queue (trace.Trace_private_util.B_queue)

Module Trace_private_util.B_queue

Basic Blocking Queue

type 'a t
val create : unit -> _ t
exception Closed
val push : 'a t -> 'a -> unit

push q x pushes x into q, and returns ().

  • raises Closed

    if close q was previously called.

val pop_all : 'a t -> 'a list

pop_all bq returns all items presently in bq, in the same order, and clears bq. It blocks if no element is in bq.

val close : _ t -> unit

Close the queue, meaning there won't be any more push allowed.

\ No newline at end of file diff --git a/trace/Trace_private_util/Domain_util/index.html b/trace/Trace_private_util/Domain_util/index.html new file mode 100644 index 0000000..2448442 --- /dev/null +++ b/trace/Trace_private_util/Domain_util/index.html @@ -0,0 +1,2 @@ + +Domain_util (trace.Trace_private_util.Domain_util)

Module Trace_private_util.Domain_util

val cpu_relax : unit -> unit
val n_domains : unit -> int
\ No newline at end of file diff --git a/trace/Trace_private_util/Mpsc_bag/index.html b/trace/Trace_private_util/Mpsc_bag/index.html new file mode 100644 index 0000000..0d8f1c5 --- /dev/null +++ b/trace/Trace_private_util/Mpsc_bag/index.html @@ -0,0 +1,2 @@ + +Mpsc_bag (trace.Trace_private_util.Mpsc_bag)

Module Trace_private_util.Mpsc_bag

A multi-producer, single-consumer bag

type 'a t
val create : unit -> 'a t
val add : 'a t -> 'a -> unit

add q x adds x in the bag.

val pop_all : 'a t -> 'a list option

Return all current items in the insertion order.

\ No newline at end of file