Macaw.Data.Source.Telemetry (macaw_data v0.18.0)

View Source

An 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

t()

@type t() :: %Macaw.Data.Source.Telemetry{
  metric: String.t(),
  server: GenServer.server()
}

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

flush(server)

@spec flush(GenServer.server()) :: :ok | {:error, term()}

Every subscriber sent the rows new since the last flush, now: :ok, or the call's error.

format_error(reason)

@spec format_error(term()) :: String.t()

A reason's words (spec/00 §5): this module's, else the library's.

source(server, name)

@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.

sources(server)

@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.

start_link(opts)

@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}.

start_link!(opts)

@spec start_link!(keyword()) :: pid()

As start_link/1, the pid alone, raising Macaw.Data.Error naming the faults.