From fe6682fc65a3da5c48543d6844fb05c3955e775b Mon Sep 17 00:00:00 2001 From: c-cube Date: Fri, 6 Sep 2024 14:35:47 +0000 Subject: [PATCH] deploy: c372c458c7dd215c229b719e8e36cbf809af1725 --- ambient-context/Ambient_context/index.html | 5 - .../index.html | 2 - .../Ambient_context_atomic/Atomic/index.html | 2 - .../Ambient_context_atomic/index.html | 2 - .../Ambient_context_hmap/index.html | 2 - .../Ambient_context_core/Types/index.html | 2 - .../Types/module-type-STORAGE/index.html | 2 - .../Ambient_context_core/index.html | 2 - .../index.html | 2 - .../Ambient_context_core__Types/index.html | 2 - .../Thread_local/index.html | 2 - .../Ambient_context_thread_local/index.html | 2 - .../index.html | 2 - .../Ambient_context_tls/M/index.html | 2 - .../Ambient_context_tls/index.html | 2 - ambient-context/_doc-dir/README.md | 204 ------------------ ambient-context/index.html | 2 - index.html | 2 +- .../Config/index.html | 7 +- .../Opentelemetry_client_ocurl/index.html | 2 +- .../_doc-dir/CHANGES.md | 6 + opentelemetry-cohttp-lwt/_doc-dir/CHANGES.md | 6 + .../Opentelemetry_lwt/Trace/index.html | 2 +- opentelemetry-lwt/_doc-dir/CHANGES.md | 6 + .../Conventions/Attributes/Host/index.html | 2 + .../Conventions/Attributes/index.html | 2 +- opentelemetry/Opentelemetry/Scope/index.html | 2 +- opentelemetry/Opentelemetry/Trace/index.html | 2 +- .../Opentelemetry_ambient_context/index.html | 2 + .../index.html | 2 +- .../index.html | 2 + .../index.html | 2 + .../module-type-STORAGE/index.html | 2 + opentelemetry/_doc-dir/CHANGES.md | 6 + opentelemetry/index.html | 2 +- 35 files changed, 47 insertions(+), 249 deletions(-) delete mode 100644 ambient-context/Ambient_context/index.html delete mode 100644 ambient-context/Ambient_context__ambient_context_unix__/index.html delete mode 100644 ambient-context/Ambient_context_atomic/Atomic/index.html delete mode 100644 ambient-context/Ambient_context_atomic/index.html delete mode 100644 ambient-context/Ambient_context_core/Ambient_context_hmap/index.html delete mode 100644 ambient-context/Ambient_context_core/Types/index.html delete mode 100644 ambient-context/Ambient_context_core/Types/module-type-STORAGE/index.html delete mode 100644 ambient-context/Ambient_context_core/index.html delete mode 100644 ambient-context/Ambient_context_core__Ambient_context_hmap/index.html delete mode 100644 ambient-context/Ambient_context_core__Types/index.html delete mode 100644 ambient-context/Ambient_context_thread_local/Thread_local/index.html delete mode 100644 ambient-context/Ambient_context_thread_local/index.html delete mode 100644 ambient-context/Ambient_context_thread_local__Thread_local/index.html delete mode 100644 ambient-context/Ambient_context_tls/M/index.html delete mode 100644 ambient-context/Ambient_context_tls/index.html delete mode 100644 ambient-context/_doc-dir/README.md delete mode 100644 ambient-context/index.html create mode 100644 opentelemetry/Opentelemetry/Conventions/Attributes/Host/index.html create mode 100644 opentelemetry/Opentelemetry_ambient_context/index.html rename {ambient-context/Ambient_context_atomic__Atomic => opentelemetry/Opentelemetry_ambient_context__}/index.html (52%) create mode 100644 opentelemetry/Opentelemetry_ambient_context_lwt/index.html create mode 100644 opentelemetry/Opentelemetry_ambient_context_types/index.html create mode 100644 opentelemetry/Opentelemetry_ambient_context_types/module-type-STORAGE/index.html diff --git a/ambient-context/Ambient_context/index.html b/ambient-context/Ambient_context/index.html deleted file mode 100644 index 75babe47..00000000 --- a/ambient-context/Ambient_context/index.html +++ /dev/null @@ -1,5 +0,0 @@ - -Ambient_context (ambient-context.Ambient_context)

Module Ambient_context

include module type of struct include Ambient_context_core.Types end
type storage = (module STORAGE)
type 'a key = int * 'a Hmap.key
val debug : bool
val id : int Atomic.t
val generate_debug_id : unit -> int
val compare_key : int -> int -> int
val current_storage_key : storage TLS.t
val get_current_storage : unit -> Ambient_context_core.Types.storage
val create_key : unit -> int * 'a Ambient_context_core.Ambient_context_hmap.key
val get : (int * 'a Ambient_context_core.Ambient_context_hmap.key) -> 'a option
val with_binding : 'a key -> 'a -> (unit -> 'r) -> 'r
val without_binding : - (int * 'a Ambient_context_core.Ambient_context_hmap.key) -> - (unit -> 'b) -> - 'c
val set_storage_provider : Ambient_context_core.Types.storage -> unit
diff --git a/ambient-context/Ambient_context__ambient_context_unix__/index.html b/ambient-context/Ambient_context__ambient_context_unix__/index.html deleted file mode 100644 index 94196d14..00000000 --- a/ambient-context/Ambient_context__ambient_context_unix__/index.html +++ /dev/null @@ -1,2 +0,0 @@ - -Ambient_context__ambient_context_unix__ (ambient-context.Ambient_context__ambient_context_unix__)

Module Ambient_context__ambient_context_unix__

This module is hidden.

diff --git a/ambient-context/Ambient_context_atomic/Atomic/index.html b/ambient-context/Ambient_context_atomic/Atomic/index.html deleted file mode 100644 index 58cc5ae0..00000000 --- a/ambient-context/Ambient_context_atomic/Atomic/index.html +++ /dev/null @@ -1,2 +0,0 @@ - -Atomic (ambient-context.Ambient_context_atomic.Atomic)

Module Ambient_context_atomic.Atomic

Atomic references.

type 'a t = 'a Stdlib.Atomic.t

An atomic (mutable) reference to a value of type 'a.

val make : 'a -> 'a t

Create an atomic reference.

val get : 'a t -> 'a

Get the current value of the atomic reference.

val set : 'a t -> 'a -> unit

Set a new value for the atomic reference.

val exchange : 'a t -> 'a -> 'a

Set a new value for the atomic reference, and return the current value.

val compare_and_set : 'a t -> 'a -> 'a -> bool

compare_and_set r seen v sets the new value of r to v only if its current value is physically equal to seen -- the comparison and the set occur atomically. Returns true if the comparison succeeded (so the set happened) and false otherwise.

val fetch_and_add : int t -> int -> int

fetch_and_add r n atomically increments the value of r by n, and returns the current value (before the increment).

val incr : int t -> unit

incr r atomically increments the value of r by 1.

val decr : int t -> unit

decr r atomically decrements the value of r by 1.

diff --git a/ambient-context/Ambient_context_atomic/index.html b/ambient-context/Ambient_context_atomic/index.html deleted file mode 100644 index 53011e7b..00000000 --- a/ambient-context/Ambient_context_atomic/index.html +++ /dev/null @@ -1,2 +0,0 @@ - -Ambient_context_atomic (ambient-context.Ambient_context_atomic)

Module Ambient_context_atomic

module Atomic : sig ... end

Atomic references.

diff --git a/ambient-context/Ambient_context_core/Ambient_context_hmap/index.html b/ambient-context/Ambient_context_core/Ambient_context_hmap/index.html deleted file mode 100644 index 03726b00..00000000 --- a/ambient-context/Ambient_context_core/Ambient_context_hmap/index.html +++ /dev/null @@ -1,2 +0,0 @@ - -Ambient_context_hmap (ambient-context.Ambient_context_core.Ambient_context_hmap)

Module Ambient_context_core.Ambient_context_hmap

include module type of struct include Hmap end

Keys

type 'a key = 'a Hmap.key

The type for keys whose lookup value is of type 'a.

module Key = Hmap.Key

Keys.

Maps

type t = Hmap.t

The type for heterogeneous value maps.

val empty : t

empty is the empty map.

val is_empty : t -> bool

is_empty m is true iff m is empty.

val mem : 'a key -> t -> bool

mem k m is true iff k is bound in m.

val add : 'a key -> 'a -> t -> t

add k v m is m with k bound to v.

val singleton : 'a key -> 'a -> t

singleton k v is add k v empty.

val rem : 'a key -> t -> t

rem k m is m with k unbound.

val find : 'a key -> t -> 'a option

find k m is the value of k's binding in m, if any.

val get : 'a key -> t -> 'a

get k m is the value of k's binding in m.

  • raises Invalid_argument

    if k is not bound in m.

type binding = Hmap.binding =
  1. | B : 'a key * 'a -> binding

The type for bindings.

val iter : (binding -> unit) -> t -> unit

iter f m applies f to all bindings of m.

val fold : (binding -> 'a -> 'a) -> t -> 'a -> 'a

fold f m acc folds over the bindings of m with f, starting with acc

val for_all : (binding -> bool) -> t -> bool

for_all p m is true iff all bindings of m satisfy p.

val exists : (binding -> bool) -> t -> bool

exists p m is true iff there exists a bindings of m that satisfies p.

val filter : (binding -> bool) -> t -> t

filter p m are the bindings of m that satisfy p.

val cardinal : t -> int

cardinal m is the number of bindings in m.

val any_binding : t -> binding option

any_binding m is a binding of m (if not empty).

val get_any_binding : t -> binding

get_any_binding m is a binding of m.

  • raises Invalid_argument

    if m is empty.

Functorial interface

The functorial interface allows to associate more information to the keys. For example a key name or a key value pretty-printer.

module type KEY_INFO = Hmap.KEY_INFO

The type for key information.

module type S = Hmap.S

Output signature of the functor Make

module Make = Hmap.Make

Functor for heterogeneous maps whose keys hold information of type Key_info.t

diff --git a/ambient-context/Ambient_context_core/Types/index.html b/ambient-context/Ambient_context_core/Types/index.html deleted file mode 100644 index ae3208d8..00000000 --- a/ambient-context/Ambient_context_core/Types/index.html +++ /dev/null @@ -1,2 +0,0 @@ - -Types (ambient-context.Ambient_context_core.Types)

Module Ambient_context_core.Types

module Hmap := Ambient_context_hmap
type 'a key = 'a Hmap.key
module type STORAGE = sig ... end
type storage = (module STORAGE)
diff --git a/ambient-context/Ambient_context_core/Types/module-type-STORAGE/index.html b/ambient-context/Ambient_context_core/Types/module-type-STORAGE/index.html deleted file mode 100644 index 87202126..00000000 --- a/ambient-context/Ambient_context_core/Types/module-type-STORAGE/index.html +++ /dev/null @@ -1,2 +0,0 @@ - -STORAGE (ambient-context.Ambient_context_core.Types.STORAGE)

Module type Types.STORAGE

val name : string
val get_map : unit -> Hmap.t option
val with_map : Hmap.t -> (unit -> 'b) -> 'b
val create_key : unit -> 'a key
val get : 'a key -> 'a option
val with_binding : 'a key -> 'a -> (unit -> 'b) -> 'b
val without_binding : 'a key -> (unit -> 'b) -> 'b
diff --git a/ambient-context/Ambient_context_core/index.html b/ambient-context/Ambient_context_core/index.html deleted file mode 100644 index a47aa99b..00000000 --- a/ambient-context/Ambient_context_core/index.html +++ /dev/null @@ -1,2 +0,0 @@ - -Ambient_context_core (ambient-context.Ambient_context_core)

Module Ambient_context_core

module Ambient_context_hmap : sig ... end
module Types : sig ... end
diff --git a/ambient-context/Ambient_context_core__Ambient_context_hmap/index.html b/ambient-context/Ambient_context_core__Ambient_context_hmap/index.html deleted file mode 100644 index 14f0d993..00000000 --- a/ambient-context/Ambient_context_core__Ambient_context_hmap/index.html +++ /dev/null @@ -1,2 +0,0 @@ - -Ambient_context_core__Ambient_context_hmap (ambient-context.Ambient_context_core__Ambient_context_hmap)

Module Ambient_context_core__Ambient_context_hmap

This module is hidden.

diff --git a/ambient-context/Ambient_context_core__Types/index.html b/ambient-context/Ambient_context_core__Types/index.html deleted file mode 100644 index 51dd7ed1..00000000 --- a/ambient-context/Ambient_context_core__Types/index.html +++ /dev/null @@ -1,2 +0,0 @@ - -Ambient_context_core__Types (ambient-context.Ambient_context_core__Types)

Module Ambient_context_core__Types

This module is hidden.

diff --git a/ambient-context/Ambient_context_thread_local/Thread_local/index.html b/ambient-context/Ambient_context_thread_local/Thread_local/index.html deleted file mode 100644 index 4dd46655..00000000 --- a/ambient-context/Ambient_context_thread_local/Thread_local/index.html +++ /dev/null @@ -1,2 +0,0 @@ - -Thread_local (ambient-context.Ambient_context_thread_local.Thread_local)

Module Ambient_context_thread_local.Thread_local

Thread/Domain local storage

This allows the creation of global state that is per-domain or per-thread.

type 'a t
val create : unit -> 'a t

Create new storage

val get : 'a t -> 'a option

Get current value

val get_exn : 'a t -> 'a

Like get but fails with an exception

  • raises Not_found

    if no value was found

val set : 'a t -> 'a -> unit
val remove : _ t -> unit
val get_or_create : create:(unit -> 'a) -> 'a t -> 'a
val with_ : 'a t -> 'a -> ('a option -> 'b) -> 'b

with_ var x f sets var to x for this thread, calls f prev where prev is the value currently in var (if any), and then restores the old value of var for this thread.

diff --git a/ambient-context/Ambient_context_thread_local/index.html b/ambient-context/Ambient_context_thread_local/index.html deleted file mode 100644 index dd7e98b6..00000000 --- a/ambient-context/Ambient_context_thread_local/index.html +++ /dev/null @@ -1,2 +0,0 @@ - -Ambient_context_thread_local (ambient-context.Ambient_context_thread_local)

Module Ambient_context_thread_local

module Thread_local : sig ... end

Thread/Domain local storage

diff --git a/ambient-context/Ambient_context_thread_local__Thread_local/index.html b/ambient-context/Ambient_context_thread_local__Thread_local/index.html deleted file mode 100644 index f10bb1be..00000000 --- a/ambient-context/Ambient_context_thread_local__Thread_local/index.html +++ /dev/null @@ -1,2 +0,0 @@ - -Ambient_context_thread_local__Thread_local (ambient-context.Ambient_context_thread_local__Thread_local)

Module Ambient_context_thread_local__Thread_local

This module is hidden.

diff --git a/ambient-context/Ambient_context_tls/M/index.html b/ambient-context/Ambient_context_tls/M/index.html deleted file mode 100644 index 39c6434b..00000000 --- a/ambient-context/Ambient_context_tls/M/index.html +++ /dev/null @@ -1,2 +0,0 @@ - -M (ambient-context.Ambient_context_tls.M)

Module Ambient_context_tls.M

val name : string
val get_map : unit -> Hmap.t option
val with_map : Hmap.t -> (unit -> 'a) -> 'b
val create_key : unit -> 'a Hmap.key
val get : 'a Hmap.key -> 'b option
val with_binding : 'a Hmap.key -> 'b -> (unit -> 'c) -> 'd
val without_binding : 'a Hmap.key -> (unit -> 'b) -> 'c
diff --git a/ambient-context/Ambient_context_tls/index.html b/ambient-context/Ambient_context_tls/index.html deleted file mode 100644 index af218fbe..00000000 --- a/ambient-context/Ambient_context_tls/index.html +++ /dev/null @@ -1,2 +0,0 @@ - -Ambient_context_tls (ambient-context.Ambient_context_tls)

Module Ambient_context_tls

val _internal_key : Hmap.t TLS.t
val let* : 'a option -> ('b -> 'c option) -> 'c option
module M : sig ... end
diff --git a/ambient-context/_doc-dir/README.md b/ambient-context/_doc-dir/README.md deleted file mode 100644 index 946b6c36..00000000 --- a/ambient-context/_doc-dir/README.md +++ /dev/null @@ -1,204 +0,0 @@ -ocaml-ambient-context -===================== - -This OCaml module provides a API that is type- and dependency-abstracted across thread-local storage, Lwt's [sequence-associated storage](https://github.com/ocsigen/lwt/blob/cc05e2bda6c34126a3fd8d150ee7cddb3b8a440b/src/core/lwt.ml#L727-L751 "Internal documentation for Lwt's SAS mechanism"), and Eio's [fiber-local storage](https://github.com/ocaml-multicore/eio/pull/256 "ocaml-multicore/eio#256, adding a fibre-local storage API") — all different approaches to "throwing" information "across the stack" at runtime, without modifying interleaving methods/components/dependencies. - -As a library author, depending on `ambient-context` allows you to - -1. abstract some sort of application-provided information into something like "thread-local storage", -2. while still being compatible with dependants who are calling into you from an asynchronous context (like Lwt or Eio), -3. *without* functorizing your interface over (or even depending on!) specifically Lwt or Eio, or preventing non-Lwt/Eio users from consuming your API. - -Simply put, `ambient-context` allows you to communicate with your dependants in situations where you cannot control intermediate dependencies, and cannot modify the API of your own library to accept a new parameter. - -> [!WARNING] -> Ambient context like this — effectively, implicit global state — is usually frowned upon for most uses, and with good reason. This module is *intended* to be used as a last resort, and exclusively for debugging, tracing, and reporting purposes, if at all possible. - -Installation and usage ... --------------------------- - -The intended usage of this library is in two collaborating components: - -1. that of a "deep in the dependency-tree" library (e.g. `foo-deep-lib`), -2. and a top-of-the-dependency-tree (e.g. `widget-app`). - -The former needs to be able to obtain information from the latter, *without* changing the API presented to intermediate dependencies (e.g. `bar-intermediary-lib`) — and equivalently, without changing the function-signatures of intermediate wrappers/callers. - - - -### ... as a top-level application - -If a library you depend on (let's pretend it's `foo-deep-lib`) uses `ambient-context`, they're effectively deferring an important decision about _how_ their library communicates with you. - -_This means you must to choose, and configure, a storage-mechanism relevant to the callsite(s) in your own application._ - -Your choice will vary depending on *from where*, in your own code, you're calling into a library that uses `ambient-context` — that is, whether an asynchronous event-loop (such as Lwt or Eio) exists 'above' your calls on the stack. Having determined whether you'll be calling your dependancy (e.g. `foo-deep-lib`) from such an asynchronous context , you'll then need to install the relevant storage-provider at runtime with an appropriately-placed call to `Ambient_context.set_storage_provider`. - -> **Example:** if you're writing an Lwt-enabled application, and you'll be calling `bar-intermediary-lib` below the `Lwt_main.run` event-loop on the stack, you'll need to install the `ambient-context-lwt` "storage provider" ... -> -> ```diff -> ; dune-project -> (depends -> (ocaml -> (>= 4.08)) -> + ambient-context.unix -> + ambient-context-lwt -> bar-intermediary-lib -> (alcotest :with-test) -> (ocaml-lsp-server :with-dev-setup) -> ``` -> -> ```diff -> ; src/dune -> (executable -> (name widget_app) -> - (libraries bar-intermediary-lib)) -> + (libraries ambient-context.unix ambient-context-lwt bar-intermediary-lib)) -> ``` -> -> ... and at runtime, your application will need to dictate the relevant storage backend (TLS, Lwt, or Eio) for a delineated section of the stack — usually, this involves wrapping the invocation of your asynchronous thread-scheduler's runloop — in this example, `Lwt_main.run`: -> -> ```ocaml -> (* src/widget_app.ml *) -> module Ctx = Ambient_context -> -> let () = -> let sock = create_socket () in -> let serve = create_server sock in -> -> (* add this line before [Lwt_main.run]: *) -> Ctx.set_storage_provider (Ambient_context_lwt.storage ()) ; -> Lwt_main.run @@ serve () -> ``` - -Once your application has configured the appropriate runtime context-storage, you'll presumably need to actually _use_ the ambient context in your calls to `foo-deep-lib`. - -To communicate with transitive dependencies, you need an opaque `key` — these are usually created and exposed by your transitive dependency; see its documentation. - -You can provide ambient values to the transitive dependency via calls to `Ambient_context.with_binding`; which takes that opaque `key`, the new `value` you want to set, and then a callback. - -> **Example:** In our Lwt-enabled application, assuming `foo-deep-lib` takes advantage of the ambient context to communicate about a header it wants to add to HTTP requests, we can set that header in our application's top-level context, and it will be available to `foo-deep-lib`'s calls to `Curl`: -> -> ```ocaml -> (* src/widget_app.ml *) -> module Ctx = Ambient_context -> -> let () = -> let sock = create_socket () in -> let serve = create_server sock in -> -> Ctx.set_storage_provider (Ambient_context_lwt.storage ()) ; -> Lwt_main.run @@ fun () -> -> Ctx.with_binding Foo_deep.header_context_key "my header value" @@ fun () -> -> (* This empty [bind] may be necessary; see -> {!Ambient_context_lwt.with_binding}. *) -> Lwt.bind (serve ()) (fun () -> ()) -> ``` - -Refer to your dependency's documentation for specific instructions on how to provide the ambient context they expect. - - -> [!NOTE] -> The precise semantics of `with_binding` depend on the chosen storage-backend; refer to your chosen backend's documentation. - -### ... as a library - -This library allows you to avoid depending on, or functorizing over, `Lwt.t`. In the most basic usage, you simply provide a `Ambient_context.key`, direct your consumers to the [above documentation](#as-a-top-level-application) and then anywhere in your API, you can pull the value 'currently' assigned to your key out of the ambient-context. - -You need depend only on `ambient-context` itself, *not* `ambient-context-lwt`, or even `lwt` itself: - -```diff - ; dune-project - (depends - (ocaml - (>= 4.08)) -+ ambient-context - (alcotest :with-test) - (ocaml-lsp-server :with-dev-setup) -``` - -```diff - ; lib/dune - (library - (name foo-deep-lib) -- (libraries curl pcre) -+ (libraries ambient-context curl pcre)) -``` - -Use `Ambient_context.create_key` to create an opaque key for the value, and expose that to your user: - -```ocaml -(* lib/foo_deep.ml *) -module Ctx = Ambient_context - -let header_context_key : string Ctx.key = Ctx.create_key () - -(* ... *) -``` - -Then, anywhere you like, you should be able to obtain the value assigned to `Foo_deep.header_context_key` by the consuming application up-stack from you: - -```ocaml -(* lib/foo_deep.ml *) -module Ctx = Ambient_context - -(* ... *) - -let http_request ?headers ?body action url = - let open Curl in - let headers = - match Ctx.get Foo_deep.header_context_key with - | None -> headers - | Some header -> - let header = "x-foo-deep: " ^ header in - Some (header :: Option.default [] headers) - in - (* ... *) -``` - -Contributing ------------- - -1. Create an opam switch and install the dependencies: - - ```console - $ opam switch create . ocaml.5.0.0 --deps-only --no-install - - # If you have opam >= 2.2 - $ opam install . --deps-only --with-test --with-dev-setup - - # ... or with opam < 2.2 - $ opam install . --deps-only --with-test - $ opam install ocaml-lsp-server ocamlformat - ``` - -2. Install [pre-commit][], and then configure your checkout: - - ```console - $ pre-commit install - pre-commit installed at .git/hooks/pre-commit - ``` - -[pre-commit]: "Installation instructions for th pre-commit tool" - -License -------- - -Copyright © 2023 ELLIOTTCABLE - -Permission is hereby granted, free of charge, to any person obtaining a copy of -this software and associated documentation files (the “Software”), to deal in -the Software without restriction, including without limitation the rights to -use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of -the Software, and to permit persons to whom the Software is furnished to do so, -subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS -FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR -COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER -IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN -CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/ambient-context/index.html b/ambient-context/index.html deleted file mode 100644 index 0d8bdc3d..00000000 --- a/ambient-context/index.html +++ /dev/null @@ -1,2 +0,0 @@ - -index (ambient-context.index)

Package ambient-context

Package info

readme-files
diff --git a/index.html b/index.html index fe61a999..5fcbd89e 100644 --- a/index.html +++ b/index.html @@ -1,2 +1,2 @@ -_opam

OCaml package documentation

Browse by name, by tag, the standard library and the OCaml manual (online, latest version).

Generated for /home/runner/work/ocaml-opentelemetry/ocaml-opentelemetry/_opam/lib

Packages by name

a

  1. ambient-context
  2. angstrom

b

  1. bigstringaf

c

  1. cohttp
  2. cohttp-lwt

h

  1. hmap

l

  1. lwt

m

  1. mtime

o

  1. ocaml
  2. opentelemetry
  3. opentelemetry-client-ocurl
  4. opentelemetry-cohttp-lwt
  5. opentelemetry-lwt

p

  1. pbrt
  2. ptime

s

  1. sexplib0

u

  1. uri

Packages by tag

\ No newline at end of file +_opam

OCaml package documentation

Browse by name, by tag, the standard library and the OCaml manual (online, latest version).

Generated for /home/runner/work/ocaml-opentelemetry/ocaml-opentelemetry/_opam/lib

Packages by name

a

  1. angstrom

b

  1. bigstringaf

c

  1. cohttp
  2. cohttp-lwt

h

  1. hmap

l

  1. lwt

m

  1. mtime

o

  1. ocaml
  2. opentelemetry
  3. opentelemetry-client-ocurl
  4. opentelemetry-cohttp-lwt
  5. opentelemetry-lwt

p

  1. pbrt
  2. ptime

s

  1. sexplib0

u

  1. uri

Packages by tag

\ No newline at end of file diff --git a/opentelemetry-client-ocurl/Opentelemetry_client_ocurl/Config/index.html b/opentelemetry-client-ocurl/Opentelemetry_client_ocurl/Config/index.html index 609f3db8..8365f74b 100644 --- a/opentelemetry-client-ocurl/Opentelemetry_client_ocurl/Config/index.html +++ b/opentelemetry-client-ocurl/Opentelemetry_client_ocurl/Config/index.html @@ -1,7 +1,10 @@ -Config (opentelemetry-client-ocurl.Opentelemetry_client_ocurl.Config)

Module Opentelemetry_client_ocurl.Config

Configuration for the ocurl backend

type t = private {
  1. debug : bool;
  2. url : string;
    (*

    Url of the endpoint. Default is "http://localhost:4318", or "OTEL_EXPORTER_OTLP_ENDPOINT" if set.

    *)
  3. headers : (string * string) list;
    (*

    API headers sent to the endpoint. Default is none or "OTEL_EXPORTER_OTLP_HEADERS" if set.

    *)
  4. batch_timeout_ms : int;
    (*

    Number of milliseconds after which we will emit a batch, even incomplete. Note that the batch might take longer than that, because this is only checked when a new event occurs or when a tick is emitted. Default 2_000.

    *)
  5. bg_threads : int;
    (*

    Are there background threads, and how many? Default 4. This will be adjusted to be at least 1 and at most 32.

    *)
  6. ticker_thread : bool;
    (*

    If true, start a thread that regularly checks if signals should be sent to the collector. Default true

    *)
  7. ticker_interval_ms : int;
    (*

    Interval for ticker thread, in milliseconds. This is only useful if ticker_thread is true. This will be clamped between 2 ms and some longer interval (maximum 60s currently). Default 500.

    • since 0.7
    *)
  8. self_trace : bool;
    (*

    If true, the OTEL library will also emit its own spans. Default false.

    • since 0.7
    *)
}

Configuration.

To build one, use make below. This might be extended with more fields in the future.

val make : +Config (opentelemetry-client-ocurl.Opentelemetry_client_ocurl.Config)

Module Opentelemetry_client_ocurl.Config

Configuration for the ocurl backend

type t = private {
  1. debug : bool;
  2. url_traces : string;
    (*

    Url to send traces

    *)
  3. url_metrics : string;
    (*

    Url to send metrics

    *)
  4. url_logs : string;
    (*

    Url to send logs

    *)
  5. headers : (string * string) list;
    (*

    API headers sent to the endpoint. Default is none or "OTEL_EXPORTER_OTLP_HEADERS" if set.

    *)
  6. batch_timeout_ms : int;
    (*

    Number of milliseconds after which we will emit a batch, even incomplete. Note that the batch might take longer than that, because this is only checked when a new event occurs or when a tick is emitted. Default 2_000.

    *)
  7. bg_threads : int;
    (*

    Are there background threads, and how many? Default 4. This will be adjusted to be at least 1 and at most 32.

    *)
  8. ticker_thread : bool;
    (*

    If true, start a thread that regularly checks if signals should be sent to the collector. Default true

    *)
  9. ticker_interval_ms : int;
    (*

    Interval for ticker thread, in milliseconds. This is only useful if ticker_thread is true. This will be clamped between 2 ms and some longer interval (maximum 60s currently). Default 500.

    • since 0.7
    *)
  10. self_trace : bool;
    (*

    If true, the OTEL library will also emit its own spans. Default false.

    • since 0.7
    *)
}

Configuration.

To build one, use make below. This might be extended with more fields in the future.

val make : ?debug:bool -> ?url:string -> + ?url_traces:string -> + ?url_metrics:string -> + ?url_logs:string -> ?headers:(string * string) list -> ?batch_timeout_ms:int -> ?bg_threads:int -> @@ -9,4 +12,4 @@ ?ticker_interval_ms:int -> ?self_trace:bool -> unit -> - t

Make a configuration.

val pp : Stdlib.Format.formatter -> t -> unit
+ t

Make a configuration.

  • parameter url

    base url used to construct per-signal urls. Per-signal url options take precedence over this base url. Default is "http://localhost:4318", or "OTEL_EXPORTER_OTLP_ENDPOINT" if set.

    Example of constructed per-signal urls with the base url http://localhost:4318

    • Traces: http://localhost:4318/v1/traces
    • Metrics: http://localhost:4318/v1/metrics
    • Logs: http://localhost:4318/v1/logs

    Use per-signal url options if different urls are needed for each signal type.

  • parameter url_traces

    url to send traces, or "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT" if set. The url is used as-is without any modification.

  • parameter url_metrics

    url to send metrics, or "OTEL_EXPORTER_OTLP_METRICS_ENDPOINT" if set. The url is used as-is without any modification.

  • parameter url_logs

    url to send logs, or "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT" if set. The url is used as-is without any modification.

val pp : Stdlib.Format.formatter -> t -> unit
diff --git a/opentelemetry-client-ocurl/Opentelemetry_client_ocurl/index.html b/opentelemetry-client-ocurl/Opentelemetry_client_ocurl/index.html index d4e3edac..9275b046 100644 --- a/opentelemetry-client-ocurl/Opentelemetry_client_ocurl/index.html +++ b/opentelemetry-client-ocurl/Opentelemetry_client_ocurl/index.html @@ -1,5 +1,5 @@ -Opentelemetry_client_ocurl (opentelemetry-client-ocurl.Opentelemetry_client_ocurl)

Module Opentelemetry_client_ocurl

val get_url : unit -> string
val set_url : string -> unit

Url of the endpoint. Default is "http://localhost:4318", or "OTEL_EXPORTER_OTLP_ENDPOINT" if set.

val get_headers : unit -> (string * string) list
val set_headers : (string * string) list -> unit

Set http headers that are sent on every http query to the collector.

module Config : sig ... end

Configuration for the ocurl backend

val create_backend : +Opentelemetry_client_ocurl (opentelemetry-client-ocurl.Opentelemetry_client_ocurl)

Module Opentelemetry_client_ocurl

val get_headers : unit -> (string * string) list
val set_headers : (string * string) list -> unit

Set http headers that are sent on every http query to the collector.

module Config : sig ... end

Configuration for the ocurl backend

val create_backend : ?stop:bool Atomic.t -> ?config:Config.t -> unit -> diff --git a/opentelemetry-client-ocurl/_doc-dir/CHANGES.md b/opentelemetry-client-ocurl/_doc-dir/CHANGES.md index 9df8f742..471daf64 100644 --- a/opentelemetry-client-ocurl/_doc-dir/CHANGES.md +++ b/opentelemetry-client-ocurl/_doc-dir/CHANGES.md @@ -1,4 +1,10 @@ +## 0.10 + +- feat: add support for per-signal urls (by @tatchi) +- build: disable protobuf regeneration during normal library use +- fix: emit GC metrics even in the absence of custom metrics + ## 0.9 - compat with trace 0.7 diff --git a/opentelemetry-cohttp-lwt/_doc-dir/CHANGES.md b/opentelemetry-cohttp-lwt/_doc-dir/CHANGES.md index 9df8f742..471daf64 100644 --- a/opentelemetry-cohttp-lwt/_doc-dir/CHANGES.md +++ b/opentelemetry-cohttp-lwt/_doc-dir/CHANGES.md @@ -1,4 +1,10 @@ +## 0.10 + +- feat: add support for per-signal urls (by @tatchi) +- build: disable protobuf regeneration during normal library use +- fix: emit GC metrics even in the absence of custom metrics + ## 0.9 - compat with trace 0.7 diff --git a/opentelemetry-lwt/Opentelemetry_lwt/Trace/index.html b/opentelemetry-lwt/Opentelemetry_lwt/Trace/index.html index f9a1ae96..cf5e9976 100644 --- a/opentelemetry-lwt/Opentelemetry_lwt/Trace/index.html +++ b/opentelemetry-lwt/Opentelemetry_lwt/Trace/index.html @@ -42,7 +42,7 @@ (unit -> 'b) * ((unit, string * Stdlib.Printexc.raw_backtrace) result -> - unit)

Sync span guard.

Notably, this includes implicit scope-tracking: if called without a ~scope argument (or ~parent/~trace_id), it will check in the Ambient_context for a surrounding environment, and use that as the scope. Similarly, it uses Scope.with_ambient_scope to set a new scope in the ambient context, so that any logically-nested calls to with_ will use this span as their parent.

NOTE be careful not to call this inside a Gc alarm, as it can cause deadlocks.

  • parameter force_new_trace_id

    if true (default false), the span will not use a ambient scope, the ~scope argument, nor ~trace_id, but will instead always create fresh identifiers for this span

val with_ : + unit)

Sync span guard.

Notably, this includes implicit scope-tracking: if called without a ~scope argument (or ~parent/~trace_id), it will check in the Ambient_context for a surrounding environment, and use that as the scope. Similarly, it uses Scope.with_ambient_scope to set a new scope in the ambient context, so that any logically-nested calls to with_ will use this span as their parent.

NOTE be careful not to call this inside a Gc alarm, as it can cause deadlocks.

  • parameter force_new_trace_id

    if true (default false), the span will not use a ambient scope, the ~scope argument, nor ~trace_id, but will instead always create fresh identifiers for this span

val with_ : ?force_new_trace_id:bool -> ?trace_state:string -> ?service_name:string -> diff --git a/opentelemetry-lwt/_doc-dir/CHANGES.md b/opentelemetry-lwt/_doc-dir/CHANGES.md index 9df8f742..471daf64 100644 --- a/opentelemetry-lwt/_doc-dir/CHANGES.md +++ b/opentelemetry-lwt/_doc-dir/CHANGES.md @@ -1,4 +1,10 @@ +## 0.10 + +- feat: add support for per-signal urls (by @tatchi) +- build: disable protobuf regeneration during normal library use +- fix: emit GC metrics even in the absence of custom metrics + ## 0.9 - compat with trace 0.7 diff --git a/opentelemetry/Opentelemetry/Conventions/Attributes/Host/index.html b/opentelemetry/Opentelemetry/Conventions/Attributes/Host/index.html new file mode 100644 index 00000000..90b22c99 --- /dev/null +++ b/opentelemetry/Opentelemetry/Conventions/Attributes/Host/index.html @@ -0,0 +1,2 @@ + +Host (opentelemetry.Opentelemetry.Conventions.Attributes.Host)

Module Attributes.Host

https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/host.md

val id : string
val name : string
val type_ : string
val arch : string
val ip : string
val mac : string
val image_id : string
val image_name : string
val image_version : string
diff --git a/opentelemetry/Opentelemetry/Conventions/Attributes/index.html b/opentelemetry/Opentelemetry/Conventions/Attributes/index.html index 81e35ba5..36f8e6d7 100644 --- a/opentelemetry/Opentelemetry/Conventions/Attributes/index.html +++ b/opentelemetry/Opentelemetry/Conventions/Attributes/index.html @@ -1,2 +1,2 @@ -Attributes (opentelemetry.Opentelemetry.Conventions.Attributes)

Module Conventions.Attributes

module Process : sig ... end
module Code : sig ... end

https://opentelemetry.io/docs/specs/semconv/attributes-registry/code/

module Service : sig ... end
module HTTP : sig ... end
+Attributes (opentelemetry.Opentelemetry.Conventions.Attributes)

Module Conventions.Attributes

module Process : sig ... end
module Code : sig ... end

https://opentelemetry.io/docs/specs/semconv/attributes-registry/code/

module Service : sig ... end
module HTTP : sig ... end
module Host : sig ... end

https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/host.md

diff --git a/opentelemetry/Opentelemetry/Scope/index.html b/opentelemetry/Opentelemetry/Scope/index.html index b0fca4fb..493c16c7 100644 --- a/opentelemetry/Opentelemetry/Scope/index.html +++ b/opentelemetry/Opentelemetry/Scope/index.html @@ -1,2 +1,2 @@ -Scope (opentelemetry.Opentelemetry.Scope)

Module Opentelemetry.Scope

Scopes.

A scope is a trace ID and the span ID of the currently active span.

type t = {
  1. trace_id : Trace_id.t;
  2. span_id : Span_id.t;
  3. mutable events : Event.t list;
  4. mutable attrs : key_value list;
}
val to_span_ctx : t -> Span_ctx.t

Turn the scope into a span context

val add_event : t -> (unit -> Event.t) -> unit

Add an event to the scope. It will be aggregated into the span.

Note that this takes a function that produces an event, and will only call it if there is an instrumentation backend.

val add_attrs : t -> (unit -> key_value list) -> unit

Add an attr to the scope. It will be aggregated into the span.

Note that this takes a function that produces attributes, and will only call it if there is an instrumentation backend.

val ambient_scope_key : t Ambient_context.key

The opaque key necessary to access/set the ambient scope with Ambient_context.

val get_ambient_scope : ?scope:t -> unit -> t option

Obtain current scope from Ambient_context, if available.

val with_ambient_scope : t -> (unit -> 'a) -> 'a0

with_ambient_scope sc thunk calls thunk() in a context where sc is the (thread|continuation)-local scope, then reverts to the previous local scope, if any.

+Scope (opentelemetry.Opentelemetry.Scope)

Module Opentelemetry.Scope

Scopes.

A scope is a trace ID and the span ID of the currently active span.

type t = {
  1. trace_id : Trace_id.t;
  2. span_id : Span_id.t;
  3. mutable events : Event.t list;
  4. mutable attrs : key_value list;
}
val to_span_ctx : t -> Span_ctx.t

Turn the scope into a span context

val add_event : t -> (unit -> Event.t) -> unit

Add an event to the scope. It will be aggregated into the span.

Note that this takes a function that produces an event, and will only call it if there is an instrumentation backend.

val add_attrs : t -> (unit -> key_value list) -> unit

Add an attr to the scope. It will be aggregated into the span.

Note that this takes a function that produces attributes, and will only call it if there is an instrumentation backend.

val ambient_scope_key : t {Ambient_context}2.key

The opaque key necessary to access/set the ambient scope with Ambient_context.

val get_ambient_scope : ?scope:t -> unit -> t option

Obtain current scope from Ambient_context, if available.

val with_ambient_scope : t -> (unit -> 'a) -> 'a0

with_ambient_scope sc thunk calls thunk() in a context where sc is the (thread|continuation)-local scope, then reverts to the previous local scope, if any.

diff --git a/opentelemetry/Opentelemetry/Trace/index.html b/opentelemetry/Opentelemetry/Trace/index.html index 1e99043a..801fb713 100644 --- a/opentelemetry/Opentelemetry/Trace/index.html +++ b/opentelemetry/Opentelemetry/Trace/index.html @@ -36,7 +36,7 @@ (unit -> 'b) * ((unit, string * Stdlib.Printexc.raw_backtrace) result -> - unit)

Sync span guard.

Notably, this includes implicit scope-tracking: if called without a ~scope argument (or ~parent/~trace_id), it will check in the Ambient_context for a surrounding environment, and use that as the scope. Similarly, it uses Scope.with_ambient_scope to set a new scope in the ambient context, so that any logically-nested calls to with_ will use this span as their parent.

NOTE be careful not to call this inside a Gc alarm, as it can cause deadlocks.

  • parameter force_new_trace_id

    if true (default false), the span will not use a ambient scope, the ~scope argument, nor ~trace_id, but will instead always create fresh identifiers for this span

val with_ : + unit)

Sync span guard.

Notably, this includes implicit scope-tracking: if called without a ~scope argument (or ~parent/~trace_id), it will check in the Ambient_context for a surrounding environment, and use that as the scope. Similarly, it uses Scope.with_ambient_scope to set a new scope in the ambient context, so that any logically-nested calls to with_ will use this span as their parent.

NOTE be careful not to call this inside a Gc alarm, as it can cause deadlocks.

  • parameter force_new_trace_id

    if true (default false), the span will not use a ambient scope, the ~scope argument, nor ~trace_id, but will instead always create fresh identifiers for this span

val with_ : ?force_new_trace_id:bool -> ?trace_state:string -> ?service_name:string -> diff --git a/opentelemetry/Opentelemetry_ambient_context/index.html b/opentelemetry/Opentelemetry_ambient_context/index.html new file mode 100644 index 00000000..d66deace --- /dev/null +++ b/opentelemetry/Opentelemetry_ambient_context/index.html @@ -0,0 +1,2 @@ + +Opentelemetry_ambient_context (opentelemetry.Opentelemetry_ambient_context)

Module Opentelemetry_ambient_context

Ambient context.

The ambient context, like the Matrix, is everywhere around you.

It is responsible for keeping track of that context in a manner that's consistent with the program's choice of control flow paradigm:

  • for synchronous/threaded/direct style code, TLS ("thread local storage") keeps track of a global variable per thread. Each thread has its own copy of the variable and updates it independently of other threads.
  • for Lwt, any 'a Lwt.t created inside the with_binding k v (fun _ -> …) will inherit the k := v assignment.
  • for Eio, fibers created inside with_binding k v (fun () -> …) will inherit the k := v assignment. This is consistent with the structured concurrency approach of Eio.

The only data stored by this storage is a Hmap.t, ie a heterogeneous map. Various users (libraries, user code, etc.) can create their own key to store what they are interested in, without affecting other parts of the storage.

module type STORAGE = Types.STORAGE
type storage = (module STORAGE)
val default_storage : storage
val get_current_storage : unit -> storage
val set_storage_provider : storage -> unit
type 'a key

A key that can be mapped to values of type 'a in the ambient context.

val compare_key : int -> int -> int

Total order on keys

val create_key : unit -> 'a key

Create a new fresh key, distinct from any previously created key.

val get : 'a key -> 'a option

Get the current value for a given key, or None if no value was associated with the key in the ambient context.

val with_binding : 'a key -> 'a -> (unit -> 'r) -> 'r

with_binding k v cb calls cb() in a context in which k is bound to v. This does not affect storage outside of cb().

val without_binding : 'a key -> (unit -> 'b) -> 'b

without_binding k cb calls cb() in a context where k has no binding (possibly shadowing the current ambient binding of k if it exists).

diff --git a/ambient-context/Ambient_context_atomic__Atomic/index.html b/opentelemetry/Opentelemetry_ambient_context__/index.html similarity index 52% rename from ambient-context/Ambient_context_atomic__Atomic/index.html rename to opentelemetry/Opentelemetry_ambient_context__/index.html index d66cde2c..51dcdfa7 100644 --- a/ambient-context/Ambient_context_atomic__Atomic/index.html +++ b/opentelemetry/Opentelemetry_ambient_context__/index.html @@ -1,2 +1,2 @@ -Ambient_context_atomic__Atomic (ambient-context.Ambient_context_atomic__Atomic)

Module Ambient_context_atomic__Atomic

This module is hidden.

+Opentelemetry_ambient_context__ (opentelemetry.Opentelemetry_ambient_context__)

Module Opentelemetry_ambient_context__

This module is hidden.

diff --git a/opentelemetry/Opentelemetry_ambient_context_lwt/index.html b/opentelemetry/Opentelemetry_ambient_context_lwt/index.html new file mode 100644 index 00000000..27d7232f --- /dev/null +++ b/opentelemetry/Opentelemetry_ambient_context_lwt/index.html @@ -0,0 +1,2 @@ + +Opentelemetry_ambient_context_lwt (opentelemetry.Opentelemetry_ambient_context_lwt)

Module Opentelemetry_ambient_context_lwt

Storage using Lwt keys

diff --git a/opentelemetry/Opentelemetry_ambient_context_types/index.html b/opentelemetry/Opentelemetry_ambient_context_types/index.html new file mode 100644 index 00000000..ae3d6354 --- /dev/null +++ b/opentelemetry/Opentelemetry_ambient_context_types/index.html @@ -0,0 +1,2 @@ + +Opentelemetry_ambient_context_types (opentelemetry.Opentelemetry_ambient_context_types)

Module Opentelemetry_ambient_context_types

Storage implementation.

There is a singleton storage for a given program, responsible for providing ambient context to the rest of the program.

type 'a key = 'a Hmap.key
module type STORAGE = sig ... end
type storage = (module STORAGE)
diff --git a/opentelemetry/Opentelemetry_ambient_context_types/module-type-STORAGE/index.html b/opentelemetry/Opentelemetry_ambient_context_types/module-type-STORAGE/index.html new file mode 100644 index 00000000..2d4709bf --- /dev/null +++ b/opentelemetry/Opentelemetry_ambient_context_types/module-type-STORAGE/index.html @@ -0,0 +1,2 @@ + +STORAGE (opentelemetry.Opentelemetry_ambient_context_types.STORAGE)

Module type Opentelemetry_ambient_context_types.STORAGE

val name : string

Name of the storage implementation.

val get_map : unit -> Hmap.t option

Get the hmap from the current ambient context, or None if there is no ambient context.

val with_map : Hmap.t -> (unit -> 'b) -> 'b

with_hmap h cb calls cb() in an ambient context in which get_map() will return h. Once cb() returns, the storage is reset to its previous value.

val create_key : unit -> 'a key

Create a new storage key, guaranteed to be distinct from any previously created key.

val get : 'a key -> 'a option
val with_binding : 'a key -> 'a -> (unit -> 'b) -> 'b
val without_binding : 'a key -> (unit -> 'b) -> 'b
diff --git a/opentelemetry/_doc-dir/CHANGES.md b/opentelemetry/_doc-dir/CHANGES.md index 9df8f742..471daf64 100644 --- a/opentelemetry/_doc-dir/CHANGES.md +++ b/opentelemetry/_doc-dir/CHANGES.md @@ -1,4 +1,10 @@ +## 0.10 + +- feat: add support for per-signal urls (by @tatchi) +- build: disable protobuf regeneration during normal library use +- fix: emit GC metrics even in the absence of custom metrics + ## 0.9 - compat with trace 0.7 diff --git a/opentelemetry/index.html b/opentelemetry/index.html index e8bbec01..2cc8ed62 100644 --- a/opentelemetry/index.html +++ b/opentelemetry/index.html @@ -1,2 +1,2 @@ -index (opentelemetry.index)

Package opentelemetry

Package info

changes-files
readme-files
+index (opentelemetry.index)

Package opentelemetry

Package info

changes-files
readme-files