Parapet.Telemetry.AsyncDelivery (parapet v1.0.0)

Copy Markdown View Source

Public contract helpers for Parapet's async and delivery telemetry families.

Stable

This module is stable as of v1.0.0. Its public API will not change without a major-version bump and a full deprecation cycle. See Stability & Deprecation Policy for details.

Summary

Functions

allowed_public_keys(family)

Returns the list of allowed public metadata keys for a given event family. Accepts either a full event name list (e.g. [:parapet, :delivery, :outbound]) or a family atom (e.g. :outbound).

delay_bucket(delay_ms)

Buckets a delay in milliseconds into a low-cardinality atom for use as a telemetry metadata value. Accepts integers or floats (floats are rounded). Raises FunctionClauseError for negative values.

event_families()

Returns the list of all six frozen async and delivery telemetry event family name tuples.

event_name(family)

Returns the full telemetry event name tuple for a given delivery or async family atom.

normalize_async_outcome(outcome)

Normalizes an async outcome atom or string to its canonical form. Raises ArgumentError for unknown outcomes.

normalize_delivery_outcome(outcome)

Normalizes a delivery outcome atom or string to its canonical form. Raises ArgumentError for unknown outcomes.

normalize_fault_plane(plane)

Normalizes a fault plane atom or string to its canonical form. Raises ArgumentError for unknown fault planes.

normalize_retry_state(state)

Normalizes a retry state atom or string to its canonical form. Raises ArgumentError for unknown retry states.

shape_metadata(family, metadata)

Shapes a raw metadata map for a given event family into the public-key-only metadata map expected in the telemetry event. Strips private/internal keys, normalizes known values, and collects ref keys under a :refs sub-map. Accepts either a full event name list or a family atom.

Functions

allowed_public_keys(family)

(since 1.0.0)

Returns the list of allowed public metadata keys for a given event family. Accepts either a full event name list (e.g. [:parapet, :delivery, :outbound]) or a family atom (e.g. :outbound).

delay_bucket(delay_ms)

(since 1.0.0)

Buckets a delay in milliseconds into a low-cardinality atom for use as a telemetry metadata value. Accepts integers or floats (floats are rounded). Raises FunctionClauseError for negative values.

event_families()

(since 1.0.0)

Returns the list of all six frozen async and delivery telemetry event family name tuples.

event_name(family)

(since 1.0.0)

Returns the full telemetry event name tuple for a given delivery or async family atom.

normalize_async_outcome(outcome)

(since 1.0.0)

Normalizes an async outcome atom or string to its canonical form. Raises ArgumentError for unknown outcomes.

normalize_delivery_outcome(outcome)

(since 1.0.0)

Normalizes a delivery outcome atom or string to its canonical form. Raises ArgumentError for unknown outcomes.

normalize_fault_plane(plane)

(since 1.0.0)

Normalizes a fault plane atom or string to its canonical form. Raises ArgumentError for unknown fault planes.

normalize_retry_state(state)

(since 1.0.0)

Normalizes a retry state atom or string to its canonical form. Raises ArgumentError for unknown retry states.

shape_metadata(family, metadata)

(since 1.0.0)

Shapes a raw metadata map for a given event family into the public-key-only metadata map expected in the telemetry event. Strips private/internal keys, normalizes known values, and collects ref keys under a :refs sub-map. Accepts either a full event name list or a family atom.