Macaw.Data.Source.Telemetry (macaw_data v0.18.0)
View SourceAn in-process :telemetry collector, one push source per metric (spec/01 §10.3).
start_link(metrics: definitions) attaches one handler for the definitions' events and
collects. A definition is a Telemetry.Metrics struct, read by its fields (name,
event_name, measurement, tags, tag_values, keep, unit, description,
reporter_options) and its struct's name, so this library takes no dependency on
telemetry_metrics. :telemetry itself is optional: without it the module compiles
and start_link/1 answers {:error, :no_telemetry}.
Each metric is a source (sources/1, source/2) whose rows are %{t: DateTime, value: v} plus the metric's tags, and whose schema says so: t the :time window field;
value labeled with the definition's description (else its name), in the definition's
unit as a UCUM code (Macaw.Data.Unit.from_telemetry/1) with the quantity it implies,
each tag a category. A counter's value is the count so far for its tags and a sum's the
running total; a last value's, a summary's and a distribution's the measurement.
value's metric_kind is :counter for a counter or a sum and :gauge otherwise. The
definition's reporter_options[:macaw] (facts_key: names another key) adds what only
the application knows of it, exactly polarity, bounds, target and metric_kind,
the last overriding the inference:
summary("http.request.duration",
unit: {:native, :millisecond},
reporter_options: [macaw: [polarity: :lower_is_better, bounds: [0, nil], target: 250]]
)The collector stamps every row on receipt with its own clock, strictly increasing, and
keeps the newest keep: rows of each metric. Each metric honors a window of DateTime
bounds, served up to the request's now and never past it, so one request with one
now has one answer (spec/01 §2.3), and pushes (Macaw.Data.Source.Push): its schema
first at subscription, then every every: milliseconds an increment of the rows new
since the last flush, numbered from 1 for each subscription. A fetch under a
subscription is its snapshot: it states the number of the last increment sent as its
position, and leaves out the rows waiting for the next flush (spec/01 §4.1). Every
delivery's rows are a Macaw.Data.Table of the metric's origin.
A call to a collector that is gone answers {:error, :noproc}, one that does not answer
in time {:error, :timeout}: the caller is never linked to the collector's fate.
Ported from visualize's Visualize.Feed.Telemetry.
Summary
Functions
Returns a specification to start this module under a supervisor.
Every subscriber sent the rows new since the last flush, now: :ok, or the call's error.
A reason's words (spec/00 §5): this module's, else the library's.
One metric's source, by its dotted name; a name the collector lacks answers {:error, {:unknown_metric, name}} when it is asked.
Each metric's source, by its dotted name ("vm.memory.total"): {:ok, sources} or the call's error.
The collector over metrics:, a list of Telemetry.Metrics definitions, attached and
linked to the caller: {:ok, pid}, or {:error, reason} with nothing started. Options:
name:, keep: (rows kept per metric, 10_000), every: (the push interval in
milliseconds, 1000; nil pushes only on flush/1), clock: (a function of no
argument answering microseconds, System.os_time(:microsecond) by default) and
facts_key: (the reporter options' key for the application's facts, :macaw).
As start_link/1, the pid alone, raising Macaw.Data.Error naming the faults.
Types
@type t() :: %Macaw.Data.Source.Telemetry{ metric: String.t(), server: GenServer.server() }
Functions
Returns a specification to start this module under a supervisor.
See Supervisor.
@spec flush(GenServer.server()) :: :ok | {:error, term()}
Every subscriber sent the rows new since the last flush, now: :ok, or the call's error.
A reason's words (spec/00 §5): this module's, else the library's.
@spec source(GenServer.server(), String.t()) :: t()
One metric's source, by its dotted name; a name the collector lacks answers {:error, {:unknown_metric, name}} when it is asked.
@spec sources(GenServer.server()) :: {:ok, %{required(String.t()) => t()}} | {:error, term()}
Each metric's source, by its dotted name ("vm.memory.total"): {:ok, sources} or the call's error.
@spec start_link(keyword()) :: GenServer.on_start() | {:error, term()}
The collector over metrics:, a list of Telemetry.Metrics definitions, attached and
linked to the caller: {:ok, pid}, or {:error, reason} with nothing started. Options:
name:, keep: (rows kept per metric, 10_000), every: (the push interval in
milliseconds, 1000; nil pushes only on flush/1), clock: (a function of no
argument answering microseconds, System.os_time(:microsecond) by default) and
facts_key: (the reporter options' key for the application's facts, :macaw).
The definitions and options are judged in the caller, before anything starts, every
fault at once (spec/00 §5): {[:metrics], :required}; {[:metrics], {:type, :metrics}} for anything but a proper list; {[:metrics, i], {:type, :metric}} for an
element that is no Telemetry.Metrics definition; {[:metrics, i | path], reason} for
facts the schema refuses, or a fact key it does not take; {[key], {:type, type}} for
an option of the wrong type and {[key], :unknown_key} for one it does not take.
Without :telemetry it is {:error, :no_telemetry}.
As start_link/1, the pid alone, raising Macaw.Data.Error naming the faults.