diff --git a/ppx_trace/_doc-dir/README.md b/ppx_trace/_doc-dir/README.md index b10a258..99e943b 100644 --- a/ppx_trace/_doc-dir/README.md +++ b/ppx_trace/_doc-dir/README.md @@ -150,9 +150,18 @@ Concrete tracing or observability formats such as: * [x] backend for [tldrs](https://github.com/imandra-ai/tldrs), a small rust daemon that aggregates TEF traces from multiple processes/clients into a single `.jsonl` file - * [ ] richer bindings with [ocaml-catapult](https://github.com/imandra-ai/catapult), - with multi-process backends, etc. + * [x] [tldrs](https://github.com/imandra-ai/tldrs), to collect TEF traces from multiple processes in a clean way. + This requires the rust `tldrs` program to be in path. + * ~~[ ] richer bindings with [ocaml-catapult](https://github.com/imandra-ai/catapult), + with multi-process backends, etc.~~ (subsumed by tldrs) - [x] Tracy (see [ocaml-tracy](https://github.com/imandra-ai/ocaml-tracy), more specifically `tracy-client.trace`) - [x] Opentelemetry (see [ocaml-opentelemetry](https://github.com/imandra-ai/ocaml-opentelemetry/), in `opentelemetry.trace`) - [ ] landmarks? - [ ] Logs (only for messages, obviously) + +## Subscribers + +The library `trace.subscriber` defines composable _subscribers_, which are sets of callbacks +that consume tracing events. +Multiple subscribers can be aggregated together (with events being dispatched to all of them) +and be installed as a normal _collector_. diff --git a/trace-fuchsia/_doc-dir/README.md b/trace-fuchsia/_doc-dir/README.md index b10a258..99e943b 100644 --- a/trace-fuchsia/_doc-dir/README.md +++ b/trace-fuchsia/_doc-dir/README.md @@ -150,9 +150,18 @@ Concrete tracing or observability formats such as: * [x] backend for [tldrs](https://github.com/imandra-ai/tldrs), a small rust daemon that aggregates TEF traces from multiple processes/clients into a single `.jsonl` file - * [ ] richer bindings with [ocaml-catapult](https://github.com/imandra-ai/catapult), - with multi-process backends, etc. + * [x] [tldrs](https://github.com/imandra-ai/tldrs), to collect TEF traces from multiple processes in a clean way. + This requires the rust `tldrs` program to be in path. + * ~~[ ] richer bindings with [ocaml-catapult](https://github.com/imandra-ai/catapult), + with multi-process backends, etc.~~ (subsumed by tldrs) - [x] Tracy (see [ocaml-tracy](https://github.com/imandra-ai/ocaml-tracy), more specifically `tracy-client.trace`) - [x] Opentelemetry (see [ocaml-opentelemetry](https://github.com/imandra-ai/ocaml-opentelemetry/), in `opentelemetry.trace`) - [ ] landmarks? - [ ] Logs (only for messages, obviously) + +## Subscribers + +The library `trace.subscriber` defines composable _subscribers_, which are sets of callbacks +that consume tracing events. +Multiple subscribers can be aggregated together (with events being dispatched to all of them) +and be installed as a normal _collector_. diff --git a/trace-tef/_doc-dir/README.md b/trace-tef/_doc-dir/README.md index b10a258..99e943b 100644 --- a/trace-tef/_doc-dir/README.md +++ b/trace-tef/_doc-dir/README.md @@ -150,9 +150,18 @@ Concrete tracing or observability formats such as: * [x] backend for [tldrs](https://github.com/imandra-ai/tldrs), a small rust daemon that aggregates TEF traces from multiple processes/clients into a single `.jsonl` file - * [ ] richer bindings with [ocaml-catapult](https://github.com/imandra-ai/catapult), - with multi-process backends, etc. + * [x] [tldrs](https://github.com/imandra-ai/tldrs), to collect TEF traces from multiple processes in a clean way. + This requires the rust `tldrs` program to be in path. + * ~~[ ] richer bindings with [ocaml-catapult](https://github.com/imandra-ai/catapult), + with multi-process backends, etc.~~ (subsumed by tldrs) - [x] Tracy (see [ocaml-tracy](https://github.com/imandra-ai/ocaml-tracy), more specifically `tracy-client.trace`) - [x] Opentelemetry (see [ocaml-opentelemetry](https://github.com/imandra-ai/ocaml-opentelemetry/), in `opentelemetry.trace`) - [ ] landmarks? - [ ] Logs (only for messages, obviously) + +## Subscribers + +The library `trace.subscriber` defines composable _subscribers_, which are sets of callbacks +that consume tracing events. +Multiple subscribers can be aggregated together (with events being dispatched to all of them) +and be installed as a normal _collector_. diff --git a/trace/Trace_subscriber/Callbacks/index.html b/trace/Trace_subscriber/Callbacks/index.html index eb97a61..31397f0 100644 --- a/trace/Trace_subscriber/Callbacks/index.html +++ b/trace/Trace_subscriber/Callbacks/index.html @@ -1,2 +1,10 @@ -Callbacks (trace.Trace_subscriber.Callbacks)

Module Trace_subscriber.Callbacks

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, do nothing.

\ No newline at end of file +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 customize 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 diff --git a/trace/Trace_subscriber/Subscriber/index.html b/trace/Trace_subscriber/Subscriber/index.html index e93736d..65379f7 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

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, config, etc.).

The design goal for this is that it should be possible to avoid allocations when the trace collector calls 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.

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

\ No newline at end of file diff --git a/trace/Trace_subscriber/index.html b/trace/Trace_subscriber/index.html index 431c63f..1c05e85 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.

module Callbacks : sig ... end
module Subscriber : sig ... end
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
type flavor =
  1. | Sync
  2. | Async
type t = Subscriber.t
val collector : t -> Trace_core.collector
\ No newline at end of file +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.

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.

\ No newline at end of file diff --git a/trace/_doc-dir/README.md b/trace/_doc-dir/README.md index b10a258..99e943b 100644 --- a/trace/_doc-dir/README.md +++ b/trace/_doc-dir/README.md @@ -150,9 +150,18 @@ Concrete tracing or observability formats such as: * [x] backend for [tldrs](https://github.com/imandra-ai/tldrs), a small rust daemon that aggregates TEF traces from multiple processes/clients into a single `.jsonl` file - * [ ] richer bindings with [ocaml-catapult](https://github.com/imandra-ai/catapult), - with multi-process backends, etc. + * [x] [tldrs](https://github.com/imandra-ai/tldrs), to collect TEF traces from multiple processes in a clean way. + This requires the rust `tldrs` program to be in path. + * ~~[ ] richer bindings with [ocaml-catapult](https://github.com/imandra-ai/catapult), + with multi-process backends, etc.~~ (subsumed by tldrs) - [x] Tracy (see [ocaml-tracy](https://github.com/imandra-ai/ocaml-tracy), more specifically `tracy-client.trace`) - [x] Opentelemetry (see [ocaml-opentelemetry](https://github.com/imandra-ai/ocaml-opentelemetry/), in `opentelemetry.trace`) - [ ] landmarks? - [ ] Logs (only for messages, obviously) + +## Subscribers + +The library `trace.subscriber` defines composable _subscribers_, which are sets of callbacks +that consume tracing events. +Multiple subscribers can be aggregated together (with events being dispatched to all of them) +and be installed as a normal _collector_.