OtlpShipper.Metrics.Definition (otlp_shipper v0.1.1)

Copy Markdown View Source

Validates Telemetry.Metrics definitions and extracts samples before aggregation.

Measurement functions already include Telemetry.Metrics unit conversion. Keep predicates run first; nil measurements are skipped (including counters). Counter measurements may be any non-nil value and contribute one event. Numeric metrics require finite signed-64-bit integers or doubles.

Summary

Functions

new(metrics)

Validates definitions and rejects duplicate OTLP names. Histograms require explicit strictly increasing finite reporter_options[:buckets] (at most 256). Summaries return {:error, :unsupported_metric, :use_distribution}.

sample(definition, measurements, metadata, max_tag_bytes \\ 4096)

Extracts {attributes, value} or skips a filtered/missing measurement. Tag values are scalar and bounded by total external size and 32 keys. No tag truncation is performed because it could merge distinct series. Callback errors are sanitized; they never detach the telemetry handler.

unit(unit)

Maps supported units to UCUM; native time must be converted explicitly.

Functions

new(metrics)

@spec new(list()) :: {:ok, [map()]} | {:error, atom()} | {:error, atom(), atom()}

Validates definitions and rejects duplicate OTLP names. Histograms require explicit strictly increasing finite reporter_options[:buckets] (at most 256). Summaries return {:error, :unsupported_metric, :use_distribution}.

iex> {:ok, [definition]} = OtlpShipper.Metrics.Definition.new([Telemetry.Metrics.counter("web.count")])
iex> {definition.name, definition.kind, definition.unit}
{"web.count", :counter, "1"}

sample(definition, measurements, metadata, max_tag_bytes \\ 4096)

@spec sample(map(), map(), map(), pos_integer()) ::
  {:ok, [map()], number()} | :skip | {:error, atom()}

Extracts {attributes, value} or skips a filtered/missing measurement. Tag values are scalar and bounded by total external size and 32 keys. No tag truncation is performed because it could merge distinct series. Callback errors are sanitized; they never detach the telemetry handler.

iex> {:ok, [definition]} = OtlpShipper.Metrics.Definition.new([Telemetry.Metrics.sum("web.bytes")])
iex> OtlpShipper.Metrics.Definition.sample(definition, %{bytes: 42}, %{})
{:ok, [], 42}

unit(unit)

@spec unit(atom()) :: {:ok, binary()} | {:error, :unsupported_unit}

Maps supported units to UCUM; native time must be converted explicitly.

iex> OtlpShipper.Metrics.Definition.unit(:millisecond)
{:ok, "ms"}