diff --git a/trace/Trace/index.html b/trace/Trace/index.html index 7d0d5dd..147db0c 100644 --- a/trace/Trace/index.html +++ b/trace/Trace/index.html @@ -1,5 +1,5 @@ -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). 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

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 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 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 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 : ?level:Level.t -> ?__FUNCTION__:string -> __FILE__:string -> @@ -7,14 +7,23 @@ ?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.

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 : ?level:Level.t -> ?__FUNCTION__:string -> __FILE__:string -> __LINE__:int -> ?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_sub_span : + 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 : + parent:explicit_span_ctx option -> + ?flavor:[ `Sync | `Async ] -> + ?level:Level.t -> + ?__FUNCTION__:string -> + __FILE__:string -> + __LINE__:int -> + ?data:(unit -> (string * user_data) list) -> + string -> + explicit_span

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 : parent:explicit_span -> ?flavor:[ `Sync | `Async ] -> ?level:Level.t -> @@ -23,7 +32,7 @@ __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.

  • parameter level

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

  • since 0.3
val enter_manual_toplevel_span : + explicit_span
val enter_manual_toplevel_span : ?flavor:[ `Sync | `Async ] -> ?level:Level.t -> ?__FUNCTION__:string -> @@ -31,7 +40,7 @@ __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.

  • parameter level

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

  • 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
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 : diff --git a/trace/Trace_core/Collector/index.html b/trace/Trace_core/Collector/index.html index 67608dc..d93b06a 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_explicit_span : Trace_core__.Types.explicit_span
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.

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.

diff --git a/trace/Trace_core/Collector/module-type-S/index.html b/trace/Trace_core/Collector/module-type-S/index.html index 1832e1d..d0dc1f2 100644 --- a/trace/Trace_core/Collector/module-type-S/index.html +++ b/trace/Trace_core/Collector/module-type-S/index.html @@ -13,7 +13,7 @@ list -> string -> (int64 -> 'a) -> - 'a

Run the function in a new span.

This replaces the previous enter_span and exit_span which were too flexible to be efficient to implement in async contexts.

  • since 0.3
val enter_span : + 'a

Run the function in a new span.

  • since 0.3
val enter_span : __FUNCTION__:string option -> __FILE__:string -> __LINE__:int -> @@ -27,7 +27,7 @@ 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 option -> + parent:Trace_core__.Types.explicit_span_ctx option -> flavor:[ `Sync | `Async ] option -> __FUNCTION__:string option -> __FILE__:string -> @@ -41,7 +41,7 @@ | `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 : + 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 diff --git a/trace/Trace_core/index.html b/trace/Trace_core/index.html index 7ce42cd..21b6300 100644 --- a/trace/Trace_core/index.html +++ b/trace/Trace_core/index.html @@ -1,5 +1,5 @@ -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). 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

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 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 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 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 : ?level:Level.t -> ?__FUNCTION__:string -> __FILE__:string -> @@ -7,14 +7,23 @@ ?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.

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 : ?level:Level.t -> ?__FUNCTION__:string -> __FILE__:string -> __LINE__:int -> ?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_sub_span : + 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 : + parent:explicit_span_ctx option -> + ?flavor:[ `Sync | `Async ] -> + ?level:Level.t -> + ?__FUNCTION__:string -> + __FILE__:string -> + __LINE__:int -> + ?data:(unit -> (string * user_data) list) -> + string -> + explicit_span

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 : parent:explicit_span -> ?flavor:[ `Sync | `Async ] -> ?level:Level.t -> @@ -23,7 +32,7 @@ __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.

  • parameter level

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

  • since 0.3
val enter_manual_toplevel_span : + explicit_span
val enter_manual_toplevel_span : ?flavor:[ `Sync | `Async ] -> ?level:Level.t -> ?__FUNCTION__:string -> @@ -31,7 +40,7 @@ __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.

  • parameter level

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

  • 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
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 : diff --git a/trace/Trace_event/Event/index.html b/trace/Trace_event/Event/index.html new file mode 100644 index 0000000..47a5dab --- /dev/null +++ b/trace/Trace_event/Event/index.html @@ -0,0 +1,2 @@ + +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 * Sub.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 * Sub.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 * Sub.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 : Sub.flavor option;
    6. fun_name : string option;
    7. data : (string * Sub.user_data) list;
    }
  9. | E_exit_manual_span of {
    1. tid : int;
    2. name : string;
    3. time_ns : int64;
    4. flavor : Sub.flavor option;
    5. data : (string * Sub.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 new file mode 100644 index 0000000..8161d9c --- /dev/null +++ b/trace/Trace_event/Subscriber/Callbacks/index.html @@ -0,0 +1,57 @@ + +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 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_subscriber__.Types.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_subscriber__.Types.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_subscriber__.Types.user_data) list -> + string -> + unit

Emit a log message

val on_counter : + st -> + time_ns:int64 -> + tid:int -> + data:(string * Trace_subscriber__.Types.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_subscriber__.Types.user_data) list -> + name:string -> + flavor:Trace_subscriber__.Types.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_subscriber__.Types.user_data) list -> + flavor:Trace_subscriber__.Types.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 new file mode 100644 index 0000000..136d5a2 --- /dev/null +++ b/trace/Trace_event/Subscriber/index.html @@ -0,0 +1,3 @@ + +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 new file mode 100644 index 0000000..80e2ecf --- /dev/null +++ b/trace/Trace_event/index.html @@ -0,0 +1,2 @@ + +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 new file mode 100644 index 0000000..b6714db --- /dev/null +++ b/trace/Trace_event__Event/index.html @@ -0,0 +1,2 @@ + +Trace_event__Event (trace.Trace_event__Event)

Module Trace_event__Event

This module is hidden.

diff --git a/trace/Trace_subscriber__Time_/index.html b/trace/Trace_event__Subscriber/index.html similarity index 68% rename from trace/Trace_subscriber__Time_/index.html rename to trace/Trace_event__Subscriber/index.html index 7ca588f..a15af02 100644 --- a/trace/Trace_subscriber__Time_/index.html +++ b/trace/Trace_event__Subscriber/index.html @@ -1,2 +1,2 @@ -Trace_subscriber__Time_ (trace.Trace_subscriber__Time_)

Module Trace_subscriber__Time_

This module is hidden.

+Trace_event__Subscriber (trace.Trace_event__Subscriber)

Module Trace_event__Subscriber

This module is hidden.

diff --git a/trace/Trace_private_util/B_queue/index.html b/trace/Trace_private_util/B_queue/index.html deleted file mode 100644 index 4029a41..0000000 --- a/trace/Trace_private_util/B_queue/index.html +++ /dev/null @@ -1,2 +0,0 @@ - -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.

diff --git a/trace/Trace_private_util/Mpsc_bag/index.html b/trace/Trace_private_util/Mpsc_bag/index.html deleted file mode 100644 index 2574922..0000000 --- a/trace/Trace_private_util/Mpsc_bag/index.html +++ /dev/null @@ -1,2 +0,0 @@ - -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.

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

Module Trace_private_util.Rpool

A resource pool (for buffers)

type 'a t
val create : + max_size:int -> + create:(unit -> 'a) -> + clear:('a -> unit) -> + unit -> + 'a t
val alloc : 'a t -> 'a
val recycle : 'a t -> 'a -> unit
val with_ : 'a t -> ('a -> 'b) -> 'b
diff --git a/trace/Trace_private_util/index.html b/trace/Trace_private_util/index.html index 0b5f08c..cdd5a02 100644 --- a/trace/Trace_private_util/index.html +++ b/trace/Trace_private_util/index.html @@ -1,2 +1,2 @@ -Trace_private_util (trace.Trace_private_util)

Module Trace_private_util

module B_queue : sig ... end

Basic Blocking Queue

module Domain_util : sig ... end
module Mpsc_bag : sig ... end

A multi-producer, single-consumer bag

+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__B_queue/index.html b/trace/Trace_private_util__B_queue/index.html deleted file mode 100644 index 35c56c3..0000000 --- a/trace/Trace_private_util__B_queue/index.html +++ /dev/null @@ -1,2 +0,0 @@ - -Trace_private_util__B_queue (trace.Trace_private_util__B_queue)

Module Trace_private_util__B_queue

This module is hidden.

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

Module Trace_private_util__Mpsc_bag

This module is hidden.

diff --git a/trace/Trace_subscriber__Thread_/index.html b/trace/Trace_private_util__Rpool/index.html similarity index 68% rename from trace/Trace_subscriber__Thread_/index.html rename to trace/Trace_private_util__Rpool/index.html index d39c918..c1cd864 100644 --- a/trace/Trace_subscriber__Thread_/index.html +++ b/trace/Trace_private_util__Rpool/index.html @@ -1,2 +1,2 @@ -Trace_subscriber__Thread_ (trace.Trace_subscriber__Thread_)

Module Trace_subscriber__Thread_

This module is hidden.

+Trace_private_util__Rpool (trace.Trace_private_util__Rpool)

Module Trace_private_util__Rpool

This module is hidden.

diff --git a/trace/Trace_subscriber/Callbacks/Dummy/index.html b/trace/Trace_subscriber/Callbacks/Dummy/index.html index 3714f06..461dd6c 100644 --- a/trace/Trace_subscriber/Callbacks/Dummy/index.html +++ b/trace/Trace_subscriber/Callbacks/Dummy/index.html @@ -1,5 +1,9 @@ -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.

val on_init : 'a -> time_ns:'b -> unit
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 : +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 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 -> diff --git a/trace/Trace_subscriber/Callbacks/index.html b/trace/Trace_subscriber/Callbacks/index.html index 85a4f8b..4f2155f 100644 --- a/trace/Trace_subscriber/Callbacks/index.html +++ b/trace/Trace_subscriber/Callbacks/index.html @@ -1,10 +1,10 @@ -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 = …
+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
+    include Trace_subscriber.Callbacks.Dummy
 
-  let on_init (state:st) ~time_ns : unit = …
+    let on_init (state:st) ~time_ns : unit = …
 
-  (* … other custom callbacks … *)
-end 
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.

+    (* … 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 index eda25eb..e799c94 100644 --- a/trace/Trace_subscriber/Callbacks/module-type-S/index.html +++ b/trace/Trace_subscriber/Callbacks/module-type-S/index.html @@ -1,28 +1,28 @@ -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:float -> unit

Called when the subscriber is initialized in a collector

val on_shutdown : st -> time_ns:float -> unit

Called when the collector is shutdown

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

Current thread is being named

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

Current process is being named

val on_enter_span : +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 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:float -> + time_ns:int64 -> tid:int -> data:(string * Trace_subscriber__.Types.user_data) list -> name:string -> Trace_core.span -> - unit

Enter a regular (sync) span

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

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

val on_add_data : + 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_subscriber__.Types.user_data) list -> Trace_core.span -> unit

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

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

Emit a log message

val on_counter : st -> - time_ns:float -> + time_ns:int64 -> tid:int -> data:(string * Trace_subscriber__.Types.user_data) list -> name:string -> @@ -32,26 +32,26 @@ __FUNCTION__:string option -> __FILE__:string -> __LINE__:int -> - time_ns:float -> + time_ns:int64 -> tid:int -> parent:Trace_core.span option -> data:(string * Trace_subscriber__.Types.user_data) list -> name:string -> flavor:Trace_subscriber__.Types.flavor option -> - trace_id:int -> + trace_id:Trace_core.trace_id -> Trace_core.span -> unit

Enter a manual (possibly async) span

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

Exit a manual span

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

Extension event

  • since 0.8
diff --git a/trace/Trace_subscriber/Span_tbl/index.html b/trace/Trace_subscriber/Span_tbl/index.html new file mode 100644 index 0000000..287f718 --- /dev/null +++ b/trace/Trace_subscriber/Span_tbl/index.html @@ -0,0 +1,2 @@ + +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 index df09ab3..54d252b 100644 --- a/trace/Trace_subscriber/Subscriber/index.html +++ b/trace/Trace_subscriber/Subscriber/index.html @@ -1,2 +1,2 @@ -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 : t -> t -> t

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

val tee_l : t list -> t

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

+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 all the subscribers in subs.

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/index.html b/trace/Trace_subscriber/index.html index e9ef98d..8cbc714 100644 --- a/trace/Trace_subscriber/index.html +++ b/trace/Trace_subscriber/index.html @@ -1,2 +1,2 @@ -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.

  • since 0.8
module Callbacks : sig ... end

Callbacks used for subscribers.

module Subscriber : sig ... end

Trace subscribers

type user_data =
  1. | U_bool of bool
  2. | U_float of float
  3. | U_int of int
  4. | U_none
  5. | U_string of string
    (*

    A non polymorphic-variant version of Trace_core.user_data

    *)
type flavor =
  1. | Sync
  2. | Async
    (*

    A non polymorphic-variant version of Trace_core.flavor

    *)

Main API

type t = Subscriber.t
val collector : t -> Trace_core.collector

A collector that calls the subscriber's callbacks.

It uses mtime (if available) to obtain timestamps.

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

type user_data =
  1. | U_bool of bool
  2. | U_float of float
  3. | U_int of int
  4. | U_none
  5. | U_string of string
    (*

    A non polymorphic-variant version of Trace_core.user_data

    *)
type flavor =
  1. | Sync
  2. | Async
    (*

    A non polymorphic-variant version of Trace_core.flavor

    *)

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.

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

Module Trace_subscriber__Span_tbl

This module is hidden.

diff --git a/trace/_doc-dir/CHANGES.md b/trace/_doc-dir/CHANGES.md index dd9ae4f..55db48f 100644 --- a/trace/_doc-dir/CHANGES.md +++ b/trace/_doc-dir/CHANGES.md @@ -1,3 +1,22 @@ +# 0.10 + +- breaking: manual spans now take a `explicit_span_ctx` as parent, that + can potentially be transmitted across processes/machines. It also + is intended to be more compatible with OTEL. +- breaking `trace.subscriber`: timestamps are `int64`ns now, not floats +- breaking `trace`: pass a `string` trace_id in manual spans, which helps + for backends such as opentelemetry. It's also useful for extensions. + +- refactor `trace-fuchsia`: full revamp of the library, modularized, using subscriber API +- refactor `trace-tef`: split into exporter,writer,subscriber, using subscriber API +- feat: add `trace.event`, useful for background threads +- feat `trace.subscriber`: add `Span_tbl`, and a depopt on picos_aux +- feat `trace.subscriber`: tee a whole array at once +- feat tef-tldrs: use EMIT_TEF_AT_EXIT +- feat `trace.subscriber`: depopt on unix for timestamps +- refactor `trace-tef`: depopt on unix for TEF timestamps + + # 0.9.1 diff --git a/trace/index.html b/trace/index.html index ddfa448..14ad45a 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