Module `Metrics`Source

Metrics Monitoring.

Metrics provides a basic infrastructure to monitor metrics using time series. Monitoring is performed on sources, indexed by tags. Tags allow users to select at runtime which metric sources are producing data points. Disabled data-sources have a low runtime cost (only a closure allocation) which make Metrics suitable to instrument production systems.

Both sources tags and data-points are built using dictionaries of typed entries called fields.

Metrics is heavily inspired by Logs as it decouples metric reporting from metric monitoring. This is handled by custom reporters.

v0.5.0 - homepage

Fields

Sourcetype graph

The type for metric graphs.

Sourcetype field

The type for metric fields.

Sourcetype key = string

The type for field keys.

Source

type 'a field_f =
  ?doc:string ->
  ?unit:string ->
  ?graph:graph ->
  ?graphs:graph list ->
  key ->
  'a ->
  field

The type for field functions.

Sourceval string : string field_f

string ?doc k v is the field whose key is k and value is v.

Sourceval int : int field_f

int ?doc k i is the field whose key is k and value is i.

Sourceval uint : int field_f

uint ?doc k i is the field whose key is k and value is i.

Sourceval int32 : int32 field_f

int32 k i is the field whose key is k and value is i.

Sourceval uint32 : int32 field_f

uint32 ?doc k i is the field whose key is k and value is i.

Sourceval int64 : int64 field_f

int64 ?doc k i is the field whose key is k and value is i.

Sourceval uint64 : int64 field_f

uint64 ?doc k i is the field whose key is k and value is i.

Sourceval float : float field_f

uint ?doc k f is the field whose key is k and value is i.

Sourceval bool : bool field_f

uint ?doc k b is the field whose key is k and value is i.

Sourceval duration : int64 -> field

duration t is the field ("duration", t, "ns").

Sourcetype status = [

| `Ok
| `Error

]

The type for process status.

Sourceval status : status -> field

status t is the field ("status", "ok") or ("status", "error").

Custom fields

Sourcetype 'a ty =

| String : string ty
| Bool : bool ty
| Float : float ty
| Int : int ty
| Int32 : int32 ty
| Int64 : int64 ty
| Uint : int ty
| Uint32 : int32 ty
| Uint64 : int64 ty
| Other : 'a Fmt.t -> 'a ty

The type of supported values in metric fields.

Source

val field : 
  ?doc:string ->
  ?unit:string ->
  ?graph:graph ->
  ?graphs:graph list ->
  string ->
  'a ty ->
  'a ->
  field

field ?doc ?unit k ty v is the field whose key is k, value type is ty and value is v.

Reading Fields

Sourceval key : field -> string

key f is f's key.

Sourceval doc : field -> string option

doc f is f's documentation.

Sourceval unit : field -> string option

unit t are t's units.

Sourceval graphs : field -> graph list option

graphs t is the graphs where t appears.

Sourcetype value =

| V : 'a ty * 'a -> value
(*
Type for values.
*)

Sourceval value : field -> value

value f is f's value.

Sourceval index : fields:string list -> field -> int

index ~fields f is f's index in the list of field keys fields. Raise Not_found if f is not a field of t.

Sourceval index_key : fields:string list -> string -> int

Same as index but using field keys instead.

Pretty-printing Fields

Sourceval pp_key : field Fmt.t

pp_key is the pretty-printer for field keys.

Sourceval pp_value : field Fmt.t

pp_value is the pretty-printer for field values, using sensible default.

Data points

Sourcemodule Data : sig ... end

Data defines what is stored in the time series.

Sourcetype data = Data.t

The type for data points.

Sources

Sourcetype ('a, 'b) src

The type for metric sources. A source defines a named unit for a time series. 'a is the type of the function used to create new data points. 'b is the type for tags.

Sourcemodule Src : sig ... end

Metric sources.

Metric Graphs

Sourcemodule Graph : sig ... end

Sourcemodule Key : sig ... end

Monitoring

Sourceval is_active : ('a, 'b) src -> bool

is_active src is true iff src monitoring is enabled.

Sourceval add : ('a, 'b) src -> ('a -> tags) -> ('b -> Data.t) -> unit

add src t f adds a new data point to src for the tags t.

Source

val run : 
  ('a, ('b, exn) result -> Data.t) src ->
  ('a -> tags) ->
  (unit -> 'b) ->
  'b

run src t f runs f () and add a new data points.

Depending on src configuration, new data points might have duration information (e.g. how long g () took, in nano-seconds) and status information (e.g. to check if an exception has been raised).

Sourcetype ('a, 'b) rresult = ('a, [ `Exn of exn | `Error of 'b ]) result

The type for extended results.

Source

val rrun : 
  ('a, ('b, 'c) rresult -> Data.t) src ->
  ('a -> tags) ->
  (unit -> ('b, 'c) result) ->
  ('b, 'c) result

Same as run but also record if the result is Ok or Error.

Reporters

TODO: explain and give an example

Sourcetype reporter = {

now : unit -> int64;
at_exit : unit -> unit;
report : 'a. tags:tags -> data:data -> over:(unit -> unit) -> Src.t -> (unit -> 'a) -> 'a;

}

The type for reporters.

Sourceval nop_reporter : reporter

nop_reporter is the initial reporter returned by reporter, it does nothing if a metric gets reported.

Sourceval reporter : unit -> reporter

reporter () is the current reporter.

Sourceval set_reporter : reporter -> unit

set_reporter r sets the current reporter to r.

Sourcemodule SM : Map.S with type key = Src.t

Sourceval cache_reporter : ?cb:(Src.t -> tags -> data -> unit) -> unit -> reporter

cache_reporter ?cb () is a reporter that stores the last measurement from each source in a map (which can be retrieved by get_cache below). This overcomes the push vs pull interface. Each measurement _event_ is sent at an arbitrary point in time, while reporting over a communication channel may be rate-limited (i.e. report every 10 seconds statistics, rather than whenever they appear). The optional cb function is called for each measurement that gets reported.

This is only a good idea for counters, histograms etc. may be useful for other numbers (such as time consumed between receive and send - the measurement should provide the information whether it's a counter or sth else).

Sourceval get_cache : unit -> (tags * data) list SM.t

get_cache () is the current data of the cache reporter. The cache is only filled if cache_reporter ?cb () is set as a reporter.

OCaml Gc sources

The Gc module of the OCaml system provides counters of the memory management via Gc.quick_stat and Gc.stat function. Both are provided here.

Sourceval gc_stat : tags:'a Tags.t -> ('a, unit -> data) src

gc_stat ~tags is the source of OCaml's Gc.stat () memory management counters.

Sourceval gc_quick_stat : tags:'a Tags.t -> ('a, unit -> data) src

gc_quick_stat ~tags is the source of OCaml's Gc.quick_stat () memory management counters.

Source

val report : 
  ('a, 'b) src ->
  over:(unit -> unit) ->
  k:(unit -> 'c) ->
  ('a -> tags) ->
  ('b -> (data -> 'c) -> 'd) ->
  'd

Sourceval init : ('a, 'b) src -> data -> unit

Sourceval now : unit -> int64

package metrics

Module MetricsSource

Fields

Custom fields

Reading Fields

Pretty-printing Fields

Data points

Tags

Sources

Metric Graphs

Monitoring

Reporters

OCaml Gc sources

Module `Metrics`Source