From ae920773899feb408dccf708e02b6c05d94cc57b Mon Sep 17 00:00:00 2001 From: Simon Cruanes Date: Sat, 27 Dec 2025 22:08:22 -0500 Subject: [PATCH] more docs --- src/client/batch.mli | 2 +- src/client/consumer.ml | 2 +- src/client/emitter_combine.ml | 2 +- src/client/export_error.ml | 2 ++ src/client/exporter_add_batching.ml | 6 +++++- src/client/exporter_combine.ml | 2 ++ src/client/exporter_debug.ml | 5 +++++ src/client/exporter_queued.ml | 9 ++++++++- src/client/exporter_stdout.ml | 2 +- src/client/generic_io.ml | 5 ++++- src/client/generic_notifier.ml | 2 ++ src/client/sampler.mli | 8 +++++--- src/client/self_trace.mli | 3 ++- 13 files changed, 39 insertions(+), 11 deletions(-) diff --git a/src/client/batch.mli b/src/client/batch.mli index 706f4167..08ae88db 100644 --- a/src/client/batch.mli +++ b/src/client/batch.mli @@ -1,4 +1,4 @@ -(** A thread-safe batch of resources, to be sent together when ready . *) +(** A thread-safe batch of resources, to be sent together when ready. *) type 'a t diff --git a/src/client/consumer.ml b/src/client/consumer.ml index c4201864..ec33befb 100644 --- a/src/client/consumer.ml +++ b/src/client/consumer.ml @@ -1,4 +1,4 @@ -(** Consumer that accepts items from a bounded queue *) +(** Consumer that accepts items from a bounded queue and processes them. *) open Common_ diff --git a/src/client/emitter_combine.ml b/src/client/emitter_combine.ml index c35fe4dc..938c55fd 100644 --- a/src/client/emitter_combine.ml +++ b/src/client/emitter_combine.ml @@ -1,4 +1,4 @@ -(** Combine multiple emitters into one *) +(** Combine multiple emitters into one. *) open Opentelemetry_emitter.Emitter diff --git a/src/client/export_error.ml b/src/client/export_error.ml index 32f5e541..4ed81c92 100644 --- a/src/client/export_error.ml +++ b/src/client/export_error.ml @@ -1,3 +1,5 @@ +(** Error that can occur during export *) + type t = [ `Status of int * Opentelemetry.Proto.Status.status | `Failure of string diff --git a/src/client/exporter_add_batching.ml b/src/client/exporter_add_batching.ml index 41ff7086..4c5efe95 100644 --- a/src/client/exporter_add_batching.ml +++ b/src/client/exporter_add_batching.ml @@ -1,4 +1,8 @@ -(** Add batching to emitters *) +(** Add batching to the emitters of an exporter. + + The exporter has multiple emitters (one per signal type), this can add + batching on top of each of them (so that they emit less frequent, larger + batches of signals, amortizing the per-signal cost). *) open Common_ diff --git a/src/client/exporter_combine.ml b/src/client/exporter_combine.ml index 78bf84dc..28577d90 100644 --- a/src/client/exporter_combine.ml +++ b/src/client/exporter_combine.ml @@ -1,3 +1,5 @@ +(** Combine multiple exporters into one *) + open Common_ open Opentelemetry_atomic diff --git a/src/client/exporter_debug.ml b/src/client/exporter_debug.ml index 1d634272..d9701295 100644 --- a/src/client/exporter_debug.ml +++ b/src/client/exporter_debug.ml @@ -1,3 +1,8 @@ +(** Basic debug exporter, prints signals on stdout/stderr/... + + As the name says, it's not intended for production but as a quick way to + export signals and eyeball them. *) + open Common_ open Opentelemetry_emitter diff --git a/src/client/exporter_queued.ml b/src/client/exporter_queued.ml index c8ab2043..31a90993 100644 --- a/src/client/exporter_queued.ml +++ b/src/client/exporter_queued.ml @@ -1,4 +1,11 @@ -(** Build an exporter from a queue and a consumer *) +(** Build an exporter from a queue and a consumer. + + The exporter will send signals into the queue (possibly dropping them if the + queue is full), and the consumer is responsible for actually exporting the + signals it reads from the other end of the queue. + + At shutdown time, the queue is closed for writing, but only once it's empty + will the consumer properly shutdown. *) open Common_ module BQ = Bounded_queue diff --git a/src/client/exporter_stdout.ml b/src/client/exporter_stdout.ml index b65482e6..ee1bc0b8 100644 --- a/src/client/exporter_stdout.ml +++ b/src/client/exporter_stdout.ml @@ -1,4 +1,4 @@ -(** A simple exporter that prints on stdout *) +(** A simple exporter that prints on stdout. *) open Common_ open Opentelemetry_emitter diff --git a/src/client/generic_io.ml b/src/client/generic_io.ml index 9e297026..fba94580 100644 --- a/src/client/generic_io.ml +++ b/src/client/generic_io.ml @@ -1,4 +1,7 @@ -(** Generic IO *) +(** Generic IO monad. + + This factors out some logic between various concurrency frameworks. *) + module type S = sig type 'a t diff --git a/src/client/generic_notifier.ml b/src/client/generic_notifier.ml index 8005982c..17ea42a7 100644 --- a/src/client/generic_notifier.ml +++ b/src/client/generic_notifier.ml @@ -1,3 +1,5 @@ +(** Generic notifier (used to signal when a bounded queue is empty) *) + module type IO = Generic_io.S module type S = sig diff --git a/src/client/sampler.mli b/src/client/sampler.mli index 784c8346..b66b75f0 100644 --- a/src/client/sampler.mli +++ b/src/client/sampler.mli @@ -1,4 +1,4 @@ -(** Basic random sampling *) +(** Basic random sampling. *) type t @@ -16,10 +16,12 @@ val accept : t -> bool val proba_accept : t -> float val actual_rate : t -> float -(** The ratio of signals we actually accepted so far *) +(** The ratio of signals we actually accepted so far. This should asymptotically + be equal to {!proba_accept} if the random generator is good. *) open Opentelemetry_emitter val wrap_emitter : t -> 'a Emitter.t -> 'a Emitter.t (** [wrap_emitter sampler e] is a new emitter that uses the [sampler] on each - individual signal before passing them to [e]. *) + individual signal before passing them to [e]. This means only [proba_accept] + of the signals will actually be emitted. *) diff --git a/src/client/self_trace.mli b/src/client/self_trace.mli index 07cf9369..2a9bb320 100644 --- a/src/client/self_trace.mli +++ b/src/client/self_trace.mli @@ -1,4 +1,5 @@ -(** Mini tracing module (disabled if [config.self_trace=false]) *) +(** Mini tracing module for OTEL itself (disabled if [config.self_trace=false]) +*) open Common_