OtlpShipper.MetricsReporter (otlp_shipper v0.1.1)

Copy Markdown View Source

Supervised Telemetry.Metrics reporter exporting OTLP/HTTP metrics through Finch.

Start {OtlpShipper.MetricsReporter, metrics: metrics, service_name: "checkout"} in your supervision tree. Counter and sum definitions become delta Sums; distributions become explicit-bound delta Histograms; last values become Gauges. Summaries are rejected with {:error, :unsupported_metric, :use_distribution}. Distributions require reporter_options: [buckets: [...]] in converted units.

Accepts shared Config options plus :metrics (required), :max_series (1000), :max_pending (2048 pending observations), :max_tag_bytes (4096 external bytes), :name (optional supervisor name), and :finch_name (default OtlpShipper.MetricsReporter.Finch). Independent instances need distinct Finch names. flush_ms is the aggregation interval (default 1000 ms).

A supervised GenServer serializes aggregation. Telemetry callbacks reserve a bounded ingress slot before sending a sample; no HTTP or GenServer call occurs in the event producer. If ingress is full the new observation is dropped. The first max_series series in an interval are admitted; new series beyond the cap are dropped until the next interval. Existing series continue updating.

Intervals follow processing order, including observations waiting in ingress. Flush resets all active series; idle intervals emit nothing, including gauges. Sums remain nonmonotonic after any accepted negative observation until restart. Tags are not truncated, since that could merge distinct series. Invalid data, callback errors, overload, and transport drops emit the shared dropped event. Keep/tag/measurement callbacks must be fast and must not perform blocking work.

Completed data points enter the shared bounded Buffer. Counts in transport/drop telemetry refer to points there, and observations at ingress/aggregation. There is one HTTP batch in flight. Shutdown detaches handlers, takes a final snapshot, and drains the Buffer within its shutdown budget. Crashes/restart gaps lose data; retrying an accepted request whose response was lost can duplicate points.

Summary

Functions

Closes the current interval and requests asynchronous export. Returns after the snapshot is queued, not after delivery. Observations from this calling process emitted before flush are included. Concurrent producers may enter either interval.

Starts the supervised reporter after validating all definitions and options.

Functions

flush(supervisor)

@spec flush(Supervisor.supervisor()) :: :ok | {:error, :unavailable}

Closes the current interval and requests asynchronous export. Returns after the snapshot is queued, not after delivery. Observations from this calling process emitted before flush are included. Concurrent producers may enter either interval.

start_link(opts)

@spec start_link(keyword()) ::
  Supervisor.on_start() | {:error, atom()} | {:error, atom(), atom()}

Starts the supervised reporter after validating all definitions and options.