diff --git a/trace-fuchsia/Trace_fuchsia_write/Event/Async_begin/index.html b/trace-fuchsia/Trace_fuchsia_write/Event/Async_begin/index.html index bbd4ef4..af45add 100644 --- a/trace-fuchsia/Trace_fuchsia_write/Event/Async_begin/index.html +++ b/trace-fuchsia/Trace_fuchsia_write/Event/Async_begin/index.html @@ -16,7 +16,7 @@ name:string -> t_ref:Thread_ref.t -> time_ns:int64 -> - async_id:int -> + async_id:Trace_core.trace_id -> args: [< `Bool of bool & 'a & 'b & 'c & 'd & 'e & 'f & 'g | `Float of float & 'h & 'i & 'j & 'k & 'l & 'm & 'n diff --git a/trace-fuchsia/Trace_fuchsia_write/Event/Async_end/index.html b/trace-fuchsia/Trace_fuchsia_write/Event/Async_end/index.html index 989040c..ac6680d 100644 --- a/trace-fuchsia/Trace_fuchsia_write/Event/Async_end/index.html +++ b/trace-fuchsia/Trace_fuchsia_write/Event/Async_end/index.html @@ -16,7 +16,7 @@ name:string -> t_ref:Thread_ref.t -> time_ns:int64 -> - async_id:int -> + async_id:Trace_core.trace_id -> args: [< `Bool of bool & 'a & 'b & 'c & 'd & 'e & 'f & 'g | `Float of float & 'h & 'i & 'j & 'k & 'l & 'm & 'n diff --git a/trace/Trace/index.html b/trace/Trace/index.html index 036b742..9f9a769 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 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_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 NEXT_RELEASE
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 NEXT_RELEASE
val with_span : ?level:Level.t -> ?__FUNCTION__:string -> __FILE__:string -> @@ -7,15 +7,15 @@ ?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 : - parent:explicit_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 -> @@ -23,15 +23,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 : - ?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 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

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

\ 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_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.

\ 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 22e28d5..d5b3641 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 NEXT_RELEASE.

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 1ba36f3..199e95a 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 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_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 NEXT_RELEASE
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 NEXT_RELEASE
val with_span : ?level:Level.t -> ?__FUNCTION__:string -> __FILE__:string -> @@ -7,15 +7,15 @@ ?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 : - parent:explicit_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 -> @@ -23,15 +23,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 : - ?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 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

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 NEXT_RELEASE
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_subscriber/Callbacks/index.html b/trace/Trace_subscriber/Callbacks/index.html index 9a9bf72..687e8b0 100644 --- a/trace/Trace_subscriber/Callbacks/index.html +++ b/trace/Trace_subscriber/Callbacks/index.html @@ -7,4 +7,4 @@ 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.

\ No newline at end of file +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.

\ No newline at end of file diff --git a/trace/Trace_subscriber/Callbacks/module-type-S/index.html b/trace/Trace_subscriber/Callbacks/module-type-S/index.html index fd1c842..8aac895 100644 --- a/trace/Trace_subscriber/Callbacks/module-type-S/index.html +++ b/trace/Trace_subscriber/Callbacks/module-type-S/index.html @@ -38,7 +38,7 @@ 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 -> @@ -47,7 +47,7 @@ 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 ->