From 65a914984c129077480f3764c174bda7f805171b Mon Sep 17 00:00:00 2001 From: Simon Cruanes Date: Mon, 12 Jun 2023 11:06:59 -0400 Subject: [PATCH] update docs --- trace/Trace/Collector/index.html | 2 +- trace/Trace/Collector/module-type-S/index.html | 2 +- trace/Trace/index.html | 10 +++++----- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/trace/Trace/Collector/index.html b/trace/Trace/Collector/index.html index 138c09b..c08ff49 100644 --- a/trace/Trace/Collector/index.html +++ b/trace/Trace/Collector/index.html @@ -1,2 +1,2 @@ -Collector (trace.Trace.Collector)

Module Trace.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
\ No newline at end of file +Collector (trace.Trace.Collector)

Module Trace.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 diff --git a/trace/Trace/Collector/module-type-S/index.html b/trace/Trace/Collector/module-type-S/index.html index 42cee3d..3de67eb 100644 --- a/trace/Trace/Collector/module-type-S/index.html +++ b/trace/Trace/Collector/module-type-S/index.html @@ -1,5 +1,5 @@ -S (trace.Trace.Collector.S)

Module type Collector.S

val enter_span : +S (trace.Trace.Collector.S)

Module type Collector.S

Signature for a collector.

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

val enter_span : ?__FUNCTION__:string -> __FILE__:string -> __LINE__:int -> diff --git a/trace/Trace/index.html b/trace/Trace/index.html index e882786..1d54f5d 100644 --- a/trace/Trace/index.html +++ b/trace/Trace/index.html @@ -1,23 +1,23 @@ -Trace (trace.Trace)

Module Trace

Trace.

type span = int64

A span identifier.

type user_data = [
  1. | `Int of int
  2. | `String of string
  3. | `Bool of bool
  4. | `None
]

User defined data, generally passed as key/value pairs

module Collector : sig ... end

A global collector.

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 enter_span : +Trace (trace.Trace)

Module Trace

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. | `None
]

User defined data, generally passed as key/value pairs to whatever collector is installed (if any).

module Collector : sig ... end

A global collector.

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

Enter a span. A span is a delimited period of time with a start instant ("enter") and stop instant ("exit"), associated with some metadata about the code entering/exiting some piece of code.

In particular the entrypoint comes with the location of the code (you can use __FILE__ and __LINE__ directly in OCaml), a mandatory name, and some optional metadata in a JSON-like representation.

val exit_span : span -> unit

Exit the span.

This should be called exactly once per span (even in case of exception). Once this is called, a timestamp might be recorded, and the span is considered finished and can't be used anymore

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

val message : ?span:span -> ?data:(unit -> (string * user_data) list) -> string -> - unit
val messagef : + unit

message msg logs a message msg (if a collector is installed). Additional metadata can be provided.

  • parameter span

    the surrounding span, if any. This might be ignored by the collector.

val messagef : ?span:span -> ?data:(unit -> (string * user_data) list) -> ((('a, Stdlib.Format.formatter, unit, unit) Stdlib.format4 -> 'a) -> unit) -> - unit
val set_thread_name : string -> unit

Give a name to the current thread.

val set_process_name : string -> unit

Give a name to the current process.

val counter_int : string -> int -> unit

Emit a counter (int)

val counter_float : string -> float -> unit

Emit a counter (float)

Collector

type collector = (module Collector.S)
val setup_collector : collector -> unit

setup_collector c installs c as the collector.

  • raises Invalid_argument

    if there already is an established collector.

val shutdown : unit -> unit
\ No newline at end of file + unit

messagef (fun k->k"hello %s %d!" "world" 42) is like message "hello world 42!" but only computes the string formatting if a collector is installed.

val set_thread_name : string -> unit

Give a name to the current thread. This might be used by the collector to display traces in a more informative way.

val set_process_name : string -> unit

Give a name to the current process. This might be used by the collector to display traces in a more informative way.

val counter_int : string -> int -> unit

Emit a counter of type int. Counters represent the evolution of some quantity over time.

val counter_float : string -> float -> unit

Emit a counter of type float. See counter_int for more details.

Collector

type collector = (module Collector.S)

An event collector.

See Collector for more details.

val setup_collector : collector -> unit

setup_collector c installs c as the current collector.

  • raises Invalid_argument

    if there already is an established collector.

val shutdown : unit -> unit

shutdown () shutdowns the current collector, if one was installed, and waits for it to terminate before returning.

\ No newline at end of file