Pristine.Ports.Telemetry behaviour (Pristine v0.4.0)

Copy Markdown View Source

Telemetry boundary for observability and metrics.

This port provides a unified interface for emitting telemetry events, measuring function execution times, and recording counters/gauges.

Required Callback

  • emit/3 - Emit a telemetry event with measurements and metadata

Optional Callbacks

  • measure/3 - Time function execution and emit duration event
  • emit_counter/2 - Emit a counter event
  • emit_gauge/3 - Emit a gauge event with a specific value

Summary

Types

event()

Callbacks

emit(event, metadata, measurements)

Emit a telemetry event with measurements and metadata.

emit_counter(event, metadata)

Emit a counter event (increment by 1).

emit_gauge(event, value, metadata)

Emit a gauge event with a specific value.

measure(event, metadata, function)

Measure function execution time and emit a telemetry event.

Types

event()

@type event() :: atom() | [atom()]

Callbacks

emit(event, metadata, measurements)

@callback emit(event :: event(), metadata :: map(), measurements :: map()) :: :ok

Emit a telemetry event with measurements and metadata.

Parameters

  • event - The event name (atom) or full event path (list of atoms)
  • metadata - Additional context for the event
  • measurements - Numeric measurements for the event

emit_counter(event, metadata)

(optional) 
@callback emit_counter(event :: event(), metadata :: map()) :: :ok

Emit a counter event (increment by 1).

Useful for tracking occurrences of events like requests, errors, etc.

emit_gauge(event, value, metadata)

(optional) 
@callback emit_gauge(event :: event(), value :: number(), metadata :: map()) :: :ok

Emit a gauge event with a specific value.

Useful for tracking point-in-time values like queue sizes, memory usage, active connections, etc.

measure(event, metadata, function)

(optional) 
@callback measure(event :: event(), metadata :: map(), (-> result)) :: result
when result: term()

Measure function execution time and emit a telemetry event.

Wraps the function execution, measures its duration, and emits a telemetry event with the duration measurement.

Returns the result of the function.