Powered by AppSignal & Oban Pro

Periodic Timer Signals

heartbeats.livemd

Periodic Timer Signals

This tutorial uses a static Jido.Plugin.Timer interval to send an Agent a periodic Signal. A heartbeat is one application meaning for this Timer mode. It is not a separate timer engine.

Timer only produces Signals. It does not detect missed beats or report liveness. Use a cron definition when work must align with a wall-clock slot.

Install Jido

Mix.install([
  {:jido, github: "agentjido/jido", branch: "main"}
])

Start a Jido instance

Timer runs under the Agent activation, so the Agent must start through an instance.

{:ok, _instance} = Jido.start_link(name: HeartbeatGuide.Jido)

defmodule HeartbeatGuide.Wait do
  def until(check, attempts \\ 200) do
    cond do
      check.() ->
        :ok

      attempts == 0 ->
        raise "condition was not met in time"

      true ->
        Process.sleep(10)
        until(check, attempts - 1)
    end
  end
end

Receive the default tick

Declare Timer with an interval and add a route for its Signal. Without :signal_type, each tick is a Jido.Plugin.Timer.Signal.Tick with the type "jido.agent.heartbeat" and the source "/plugin/heartbeat". The value of :signal_data becomes the Action input.

defmodule HeartbeatGuide.Monitor do
  use Jido.Agent,
    name: "heartbeat_guide_monitor",
    plugins: [{Jido.Plugin.Timer, %{interval: 20, signal_data: %{check: "disk"}}}]

  state do
    schema Jido.Joi.object(%{
             beats: Jido.Joi.integer() |> Jido.Joi.default(0),
             last: Jido.Joi.map() |> Jido.Joi.default(%{})
           })
  end

  routes do
    route "jido.agent.heartbeat" do
      action input, context: context do
        state = context.agent_state

        {:ok,
         %{
           state
           | beats: state.beats + 1,
             last: %{type: context.signal.type, source: context.signal.source, input: input}
         }}
      end
    end
  end
end

{:ok, monitor} = Jido.start_agent(HeartbeatGuide.Jido, HeartbeatGuide.Monitor, id: "monitor-1")
:ok = Jido.AgentServer.await_ready(monitor)

The first tick arrives after one full interval. Wait for a few ticks and read the state:

:ok = HeartbeatGuide.Wait.until(fn -> Jido.AgentServer.snapshot(monitor).agent.state.beats >= 3 end)

Jido.AgentServer.snapshot(monitor).agent.state.last
# => %{type: "jido.agent.heartbeat", source: "/plugin/heartbeat", input: %{check: "disk"}}

Jido.AgentServer.plugin_state(monitor, Jido.Plugin.Timer)
# => {:ok, %{cron: %{}, every: %{heartbeat: %{status: :running, ...}}}}

The Timer stops with the Agent:

:ok = Jido.stop_agent(HeartbeatGuide.Jido, monitor)

Send your own Signal type

Set :signal_type and :source when the periodic Signal is a domain event. The route then matches that type.

defmodule HeartbeatGuide.InvoiceSweeper do
  use Jido.Agent,
    name: "heartbeat_guide_invoice_sweeper",
    plugins: [
      {Jido.Plugin.Timer,
       %{
         interval: 20,
         signal_type: "invoice.sweep_due",
         signal_data: %{batch_size: 50},
         source: "/billing/sweeper"
       }}
    ]

  state do
    schema Jido.Joi.object(%{sweeps: Jido.Joi.list(Jido.Joi.integer()) |> Jido.Joi.default([])})
  end

  routes do
    route "invoice.sweep_due" do
      action %{batch_size: batch_size},
        schema: Jido.Joi.object(%{batch_size: Jido.Joi.integer()}),
        context: context do
        {:ok, %{context.agent_state | sweeps: context.agent_state.sweeps ++ [batch_size]}}
      end
    end
  end
end

{:ok, sweeper} =
  Jido.start_agent(HeartbeatGuide.Jido, HeartbeatGuide.InvoiceSweeper, id: "sweeper-1")

:ok = Jido.AgentServer.await_ready(sweeper)
:ok = HeartbeatGuide.Wait.until(fn -> length(Jido.AgentServer.snapshot(sweeper).agent.state.sweeps) >= 2 end)

Jido.AgentServer.snapshot(sweeper).agent.state.sweeps |> Enum.take(2)
# => [50, 50]
:ok = Jido.stop_agent(HeartbeatGuide.Jido, sweeper)

Static Timer options are part of the Agent definition. Runtime options cannot replace them when the Agent starts.

Options

Option Default Accepted values
:interval 5_000 Positive integer, in milliseconds.
:signal_type "jido.agent.heartbeat" Non-empty, valid UTF-8 string.
:signal_data %{} Plain map, not a struct.
:source "/plugin/heartbeat" Non-empty URI reference.

An invalid value fails the Agent definition with the message "Timer static interval options are invalid". An unknown option key is also rejected.

Delivery behavior

  • The Timer casts each tick to the Agent. A long Turn can leave ticks queued behind it. Excess casts are dropped and logged at the postponed Turn limit.
  • The next tick starts after the previous tick is sent. This is a fixed-delay interval, not wall-clock alignment.
  • Each tick is a fresh Signal with a new ID.
  • The interval definition is in the Agent :timer state. A runtime replacement starts one new full interval. Ticks missed while offline are not replayed.

Jido.Plugin.Heartbeat was removed. Use Jido.Plugin.Timer for all new and migrated Agents.

Next steps