From 96b96246160a9ad6f99b0dcc3f5322d51adaf391 Mon Sep 17 00:00:00 2001 From: Simon Cruanes Date: Wed, 14 Jun 2023 10:48:13 -0400 Subject: [PATCH] update docs --- index.html | 4 ++-- trace-tef/Trace_tef/index.html | 2 +- trace/Trace/index.html | 4 ++-- trace/Trace_core/.dummy | 0 trace/Trace_core/Collector/index.html | 2 ++ .../Collector/module-type-S/index.html | 14 +++++++++++ trace/Trace_core/index.html | 23 +++++++++++++++++++ trace/index.html | 2 +- 8 files changed, 45 insertions(+), 6 deletions(-) create mode 100644 trace/Trace_core/.dummy create mode 100644 trace/Trace_core/Collector/index.html create mode 100644 trace/Trace_core/Collector/module-type-S/index.html create mode 100644 trace/Trace_core/index.html diff --git a/index.html b/index.html index 88027cd..b6275f7 100644 --- a/index.html +++ b/index.html @@ -11,8 +11,8 @@

OCaml package documentation

    -
  1. trace 0.1
    2. -
  2. trace-tef 0.1
    3. +
  3. trace 0.2
    4. +
  4. trace-tef 0.2
diff --git a/trace-tef/Trace_tef/index.html b/trace-tef/Trace_tef/index.html index f4e42c0..fa3bb50 100644 --- a/trace-tef/Trace_tef/index.html +++ b/trace-tef/Trace_tef/index.html @@ -2,4 +2,4 @@ Trace_tef (trace-tef.Trace_tef)

Module Trace_tef

val collector : out:[ `File of string | `Stderr | `Stdout ] -> unit -> - Trace.collector

Make a collector that writes into the given output. See setup for more details.

type output = [
  1. | `Stdout
  2. | `Stderr
  3. | `File of string
]

Output for tracing.

  • `Stdout will enable tracing and print events on stdout
  • `Stderr will enable tracing and print events on stderr
  • `File "foo" will enable tracing and print events into file named "foo"
val setup : ?out:[ output | `Env ] -> unit -> unit

setup () installs the collector depending on out.

  • parameter out

    can take different values:

    • regular output value to specify where events go
    • `Env will enable tracing if the environment variable "TRACE" is set.

    If it's set to anything but "1", the value is taken to be the file path into which to write. If it's set to "1", then the file is "trace.json".

val with_setup : ?out:[ output | `Env ] -> (unit -> 'a) -> 'a

Setup, and make sure to shutdown before exiting

\ No newline at end of file + Trace.collector

Make a collector that writes into the given output. See setup for more details.

type output = [
  1. | `Stdout
  2. | `Stderr
  3. | `File of string
]

Output for tracing.

  • `Stdout will enable tracing and print events on stdout
  • `Stderr will enable tracing and print events on stderr
  • `File "foo" will enable tracing and print events into file named "foo"
val setup : ?out:[ output | `Env ] -> unit -> unit

setup () installs the collector depending on out.

  • parameter out

    can take different values:

    • regular output value to specify where events go
    • `Env will enable tracing if the environment variable "TRACE" is set.
    • If it's set to "1", then the file is "trace.json".
    • If it's set to "stdout", then logging happens on stdout (since 0.2)
    • If it's set to "stderr", then logging happens on stdout (since 0.2)
    • Otherwise, if it's set to a non empty string, the value is taken to be the file path into which to write.
val with_setup : ?out:[ output | `Env ] -> unit -> (unit -> 'a) -> 'a

with_setup () f (optionally) sets a collector up, calls f(), and makes sure to shutdown before exiting. since 0.2 a () argument was added.

\ No newline at end of file diff --git a/trace/Trace/index.html b/trace/Trace/index.html index 1d54f5d..1b9ccb4 100644 --- a/trace/Trace/index.html +++ b/trace/Trace/index.html @@ -1,5 +1,5 @@ -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 : +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. | `None
]

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

module Collector = Trace_core.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 -> @@ -20,4 +20,4 @@ ?span:span -> ?data:(unit -> (string * user_data) list) -> ((('a, Stdlib.Format.formatter, unit, unit) Stdlib.format4 -> 'a) -> unit) -> - 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 + 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 diff --git a/trace/Trace_core/.dummy b/trace/Trace_core/.dummy new file mode 100644 index 0000000..e69de29 diff --git a/trace/Trace_core/Collector/index.html b/trace/Trace_core/Collector/index.html new file mode 100644 index 0000000..8630ce8 --- /dev/null +++ b/trace/Trace_core/Collector/index.html @@ -0,0 +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 diff --git a/trace/Trace_core/Collector/module-type-S/index.html b/trace/Trace_core/Collector/module-type-S/index.html new file mode 100644 index 0000000..5c11dca --- /dev/null +++ b/trace/Trace_core/Collector/module-type-S/index.html @@ -0,0 +1,14 @@ + +S (trace.Trace_core.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 -> + data: + (string * [ `Int of int | `String of string | `Bool of bool | `None ]) list -> + string -> + int64
val exit_span : int64 -> unit
val message : + ?span:int64 -> + data: + (string * [ `Int of int | `String of string | `Bool of bool | `None ]) list -> + string -> + unit
val name_thread : string -> unit

Give a name to the current thread

val name_process : string -> unit

Give a name to the current process

val counter_int : string -> int -> unit

Integer counter

val counter_float : string -> float -> unit

Float counter

val shutdown : unit -> unit

Shutdown collector, possibly waiting for it to finish sending data.

\ No newline at end of file diff --git a/trace/Trace_core/index.html b/trace/Trace_core/index.html new file mode 100644 index 0000000..62a8241 --- /dev/null +++ b/trace/Trace_core/index.html @@ -0,0 +1,23 @@ + +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. | `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

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

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

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

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 diff --git a/trace/index.html b/trace/index.html index 54bbc27..11ba485 100644 --- a/trace/index.html +++ b/trace/index.html @@ -1,2 +1,2 @@ -index (trace.index)

trace index

Library trace

The entry point of this library is the module: Trace.

\ No newline at end of file +index (trace.index)

trace index

Library trace

The entry point of this library is the module: Trace.

Library trace.core

The entry point of this library is the module: Trace_core.

\ No newline at end of file