Foundation.Contracts.Telemetry behaviour (foundation v0.1.3)

Behaviour contract for telemetry implementations.

Defines the interface for metrics collection, event emission, and monitoring across different telemetry backends.

Summary

Callbacks

Attach event handlers for specific events.

Check if telemetry is available.

Detach event handlers.

Emit a counter metric.

Emit a histogram metric for distribution analysis.

Execute telemetry event with measurements.

Get collected metrics.

Initialize the telemetry service.

Measure execution time and emit results.

Get telemetry service status.

Types

event_name()

@type event_name() :: [atom(), ...]

measurements()

@type measurements() :: map()

metadata()

@type metadata() :: map()

metric_value()

@type metric_value() :: number()

Callbacks

attach_handlers(list)

@callback attach_handlers([event_name()]) :: :ok | {:error, Foundation.Types.Error.t()}

Attach event handlers for specific events.

available?()

@callback available?() :: boolean()

Check if telemetry is available.

detach_handlers(list)

@callback detach_handlers([event_name()]) :: :ok

Detach event handlers.

emit_counter(event_name, metadata)

@callback emit_counter(event_name(), metadata()) :: :ok

Emit a counter metric.

emit_gauge(event_name, metric_value, metadata)

@callback emit_gauge(event_name(), metric_value(), metadata()) :: :ok

Emit a gauge metric.

emit_histogram(event_name, metric_value)

@callback emit_histogram(event_name(), metric_value()) :: :ok

emit_histogram(event_name, metric_value, metadata)

@callback emit_histogram(event_name(), metric_value(), metadata()) :: :ok

Emit a histogram metric for distribution analysis.

Histograms track the distribution of values over time and are useful for measuring latencies, response sizes, and other continuous metrics.

Parameters

  • event_name - List of atoms representing the telemetry event path
  • value - Numeric value to record in the histogram
  • metadata - Optional map containing additional context (defaults to empty map)

Examples

emit_histogram([:api, :request_duration], 150, %{endpoint: "/users"})
emit_histogram([:database, :query_time], 45.5)

execute(event_name, measurements, metadata)

@callback execute(event_name(), measurements(), metadata()) :: :ok

Execute telemetry event with measurements.

get_metrics()

@callback get_metrics() :: {:ok, map()} | {:error, Foundation.Types.Error.t()}

Get collected metrics.

initialize()

@callback initialize() :: :ok | {:error, Foundation.Types.Error.t()}

Initialize the telemetry service.

measure(event_name, metadata, function)

@callback measure(event_name(), metadata(), (-> result)) :: result when result: var

Measure execution time and emit results.

status()

@callback status() :: {:ok, map()} | {:error, Foundation.Types.Error.t()}

Get telemetry service status.