WebsockexNova.Gun.Helpers.StateTracer (WebsockexNova v0.1.1)

View Source

Provides detailed tracing capabilities for connection state transitions.

This module implements event tracing for WebSocket connection state changes, allowing for easier debugging and monitoring of the connection lifecycle.

Features:

  • Records all state transitions with timestamps
  • Tracks connection statistics (uptime, reconnection frequency)
  • Provides a searchable history of connection events
  • Can output trace events to a file or monitoring system
  • Supports optional correlation IDs for distributed tracing

Summary

Functions

Exports the trace history to a file.

Gets connection statistics from the trace context.

Gets the full trace history from the connection state.

Initializes a new trace context in the connection state.

Functions

export_trace(state, path)

@spec export_trace(WebsockexNova.Gun.ConnectionState.t(), Path.t()) ::
  :ok | {:error, term()}

Exports the trace history to a file.

Parameters

  • state - The connection state
  • path - File path for the export

Returns

:ok on success, {:error, reason} on failure

get_statistics(state)

@spec get_statistics(WebsockexNova.Gun.ConnectionState.t()) :: map()

Gets connection statistics from the trace context.

Parameters

  • state - The connection state

Returns

Map of connection statistics

get_trace_history(state)

@spec get_trace_history(WebsockexNova.Gun.ConnectionState.t()) :: [map()]

Gets the full trace history from the connection state.

Parameters

  • state - The connection state

Returns

List of trace events in chronological order (oldest first)

init_trace(state, trace_id \\ nil)

@spec init_trace(WebsockexNova.Gun.ConnectionState.t(), String.t() | nil) :: map()

Initializes a new trace context in the connection state.

Parameters

  • state - The current connection state
  • trace_id - Optional trace ID for distributed tracing (generates one if nil)

Returns

Updated connection state with trace context

trace_transition(state, event_type, from_status, to_status, metadata \\ %{})

@spec trace_transition(
  WebsockexNova.Gun.ConnectionState.t(),
  atom(),
  atom(),
  atom(),
  map()
) :: map()

Traces a state transition event.

Parameters

  • state - The current connection state
  • event_type - The type of event (:connect, :disconnect, :upgrade, etc.)
  • from_status - Previous connection status
  • to_status - New connection status
  • metadata - Additional contextual information about the event

Returns

Updated connection state with the event recorded