Foundation.Services.TelemetryService (foundation v0.1.4)

GenServer implementation for telemetry collection and metrics.

Provides structured telemetry with automatic metric collection, event emission, and performance monitoring.

Summary

Functions

Returns a specification to start this module under a supervisor.

Emit a histogram metric with default empty metadata.

Emit a histogram metric for distribution analysis.

Reset all metrics (for testing purposes).

Reset all internal state for testing purposes.

Types

server_state()

@type server_state() :: %{
  metrics: %{required(atom()) => map()},
  handlers: %{required([atom()]) => function()},
  config: map(),
  namespace: atom()
}

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

emit_counter(event_name, value, metadata)

@spec emit_counter([atom()], number(), map()) :: :ok

emit_histogram(event_name, value)

@spec emit_histogram([atom(), ...], number()) :: :ok

Emit a histogram metric with default empty metadata.

Convenience function for emitting histogram metrics when no additional context is needed.

Parameters

  • event_name - List of atoms representing the telemetry event path
  • value - Numeric value to record in the histogram

Examples

iex> emit_histogram([:response, :size], 1024)
:ok

iex> emit_histogram([:processing, :duration], 250.5)
:ok

Returns

  • :ok - Metric emitted successfully

Raises

  • ArgumentError - If event_name is not a list of atoms or value is not numeric

emit_histogram(event_name, value, metadata)

@spec emit_histogram([atom(), ...], number(), map()) :: :ok

Emit a histogram metric for distribution analysis.

Histograms track the distribution of values over time and are useful for measuring latencies, 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 - Map containing additional context for the measurement

Examples

iex> emit_histogram([:api, :request_duration], 150, %{endpoint: "/users"})
:ok

iex> emit_histogram([:database, :query_time], 45.5, %{table: "users"})
:ok

Returns

  • :ok - Metric emitted successfully

Raises

  • ArgumentError - If event_name is not a list of atoms, value is not numeric, or metadata is not a map

initialize(opts)

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

reset_metrics()

@spec reset_metrics() :: :ok | {:error, Foundation.Types.Error.t()}

Reset all metrics (for testing purposes).

reset_state()

@spec reset_state() :: :ok | {:error, Foundation.Types.Error.t()}

Reset all internal state for testing purposes.

Clears all metrics, handlers, and resets configuration to defaults. This function should only be used in test environments.

start_link(opts \\ [])

@spec start_link(keyword()) :: GenServer.on_start()

stop()

@spec stop() :: :ok