ZenQuant.WS (zen_quant v0.2.0)

WebSocket health monitoring analytics.

Pure functions for assessing WebSocket connection health from timestamps and metrics. Designed to work with ZenWebsocket's get_state_metrics/1 output but accepts any map with the expected fields.

Example

last_update = DateTime.add(DateTime.utc_now(), -120, :second)
ZenQuant.WS.stale_check(last_update, threshold_seconds: 60)
# => %{stale: true, age_seconds: 120, threshold_seconds: 60}

metrics = %{
  connection_state: :connected,
  heartbeat_timer_active: true,
  heartbeat_failures: 0,
  last_heartbeat_at: DateTime.utc_now()
}
ZenQuant.WS.reconnect_metrics(metrics)
# => %{healthy: true, heartbeat_age_seconds: 0, ...original fields...}

API Functions

Function	Arity	Description	Param Kinds
`reconnect_metrics`	2	Compute derived health analytics from ZenWebsocket state metrics.	`state_metrics: exchange_data`
`stale_check`	2	Check if a WebSocket data stream is stale based on last update time.	`last_update: value`

Summary

Types

stale_result()

Staleness check result with age and threshold context

Functions

reconnect_metrics(state_metrics, opts \\ [])

Compute derived health analytics from ZenWebsocket state metrics.

stale_check(last_update, opts \\ [])

Check if a WebSocket data stream is stale based on last update time.

Types

stale_result()

@type stale_result() :: %{
  stale: boolean(),
  age_seconds: integer(),
  threshold_seconds: pos_integer()
}

Staleness check result with age and threshold context

Functions

reconnect_metrics(state_metrics, opts \\ [])

@spec reconnect_metrics(
  map(),
  keyword()
) :: map()

Compute derived health analytics from ZenWebsocket state metrics.

Parameters

state_metrics - Map with :connection_state, :heartbeat_timer_active, :heartbeat_failures, :last_heartbeat_at (exchange_data)

Options

now - Current time for age calculation (default: "DateTime.utc_now()")

Returns

Original fields plus :heartbeat_age_seconds and :healthy (boolean) (map)

Example

%{
  connection_state: :connected,
  healthy: true,
  heartbeat_timer_active: true,
  heartbeat_failures: 0,
  last_heartbeat_at: ~U[2026-02-25 12:00:00Z],
  heartbeat_age_seconds: 3
}

# descripex:contract
%{
  opts: %{
    now: %{
      default: "DateTime.utc_now()",
      type: :datetime,
      description: "Current time for age calculation"
    }
  },
  params: %{
    state_metrics: %{
      description: "Map with :connection_state, :heartbeat_timer_active, :heartbeat_failures, :last_heartbeat_at",
      source: "ZenWebsocket.Client.get_state_metrics/1",
      kind: :exchange_data
    }
  },
  returns: %{
    type: :map,
    description: "Original fields plus :heartbeat_age_seconds and :healthy (boolean)"
  },
  returns_example: %{
    connection_state: :connected,
    healthy: true,
    heartbeat_timer_active: true,
    heartbeat_failures: 0,
    last_heartbeat_at: ~U[2026-02-25 12:00:00Z],
    heartbeat_age_seconds: 3
  }
}

stale_check(last_update, opts \\ [])

@spec stale_check(
  DateTime.t(),
  keyword()
) :: stale_result()

Check if a WebSocket data stream is stale based on last update time.

Parameters

last_update - DateTime of the last received update (value)

Options

threshold_seconds - Staleness threshold in seconds (default: 60)
now - Current time for comparison (default: "DateTime.utc_now()")

Returns

Map with :stale (boolean), :age_seconds, :threshold_seconds (map)

Example

%{stale: true, age_seconds: 120, threshold_seconds: 60}

# descripex:contract
%{
  opts: %{
    now: %{
      default: "DateTime.utc_now()",
      type: :datetime,
      description: "Current time for comparison"
    },
    threshold_seconds: %{
      default: 60,
      type: :integer,
      description: "Staleness threshold in seconds"
    }
  },
  params: %{
    last_update: %{
      description: "DateTime of the last received update",
      kind: :value
    }
  },
  returns: %{
    type: :map,
    description: "Map with :stale (boolean), :age_seconds, :threshold_seconds"
  },
  returns_example: %{stale: true, age_seconds: 120, threshold_seconds: 60}
}