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

Attach event handlers for specific events.

Examples

iex> events = [[:foundation, :function, :call], [:foundation, :query, :execution]]
iex> Foundation.Telemetry.attach_handlers(events)
:ok

@spec available?() :: boolean()

Check if telemetry is available.

Examples

iex> Foundation.Telemetry.available?()
true

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

Detach event handlers.

Examples

iex> events = [[:foundation, :function, :call]]
iex> Foundation.Telemetry.detach_handlers(events)
:ok

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

Emit a counter metric.

Examples

iex> Foundation.Telemetry.emit_counter(
...>   [:foundation, :events, :processed],
...>   %{event_type: :function_entry}
...> )
:ok

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

Emit a gauge metric.

Examples

iex> Foundation.Telemetry.emit_gauge(
...>   [:foundation, :memory, :usage],
...>   1024000,
...>   %{unit: :bytes}
...> )
:ok

@spec emit_performance(atom(), metric_value(), metadata()) :: :ok

Emit a performance metric with automatic categorization.

Examples

iex> Foundation.Telemetry.emit_performance(
...>   :query_duration, 1500, %{query_type: :complex}
...> )
:ok

@spec emit_system_event(atom(), metadata()) :: :ok

Emit a system event counter.

Examples

iex> Foundation.Telemetry.emit_system_event(:error, %{error_type: :validation})
:ok

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

Execute telemetry event with measurements.

Examples

iex> Foundation.Telemetry.execute(
...>   [:foundation, :function, :call],
...>   %{duration: 1000},
...>   %{module: MyModule, function: :my_func}
...> )
:ok

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

Get collected metrics.

Examples

iex> Foundation.Telemetry.get_metrics()
{:ok, %{
  [:foundation, :function, :call] => %{
    timestamp: 123456789,
    measurements: %{duration: 1500},
    count: 42
  }
}}

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

Get metrics for a specific event pattern.

Examples

iex> Foundation.Telemetry.get_metrics_for([:foundation, :function])
{:ok, %{...}}  # Only metrics matching the pattern

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

Initialize the telemetry service.

Examples

iex> Foundation.Telemetry.initialize()
:ok

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

Measure execution time and emit results.

Examples

iex> result = Foundation.Telemetry.measure(
...>   [:foundation, :query, :execution],
...>   %{query_type: :complex},
...>   fn -> expensive_operation() end
...> )
:operation_result

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

Get telemetry service status.

Examples

iex> Foundation.Telemetry.status()
{:ok, %{status: :running, uptime: 12345}}

@spec time_function(module(), atom(), (-> result)) :: result when result: var

Time a function execution and emit telemetry.

Convenience function that automatically creates appropriate event names.

Examples

iex> Foundation.Telemetry.time_function(
...>   MyModule, :expensive_function,
...>   fn -> MyModule.expensive_function(arg1, arg2) end
...> )
:function_result