Record and query LLM usage statistics per workflow step.

Recording stats (from a worker)

Call record/2 with the current job and a usage map after a successful LLM call. LLMWorker calls this automatically when perform_workflow/1 returns {:ok, result} and the result contains a "llm_usage" key.

You can also call it manually for more control:

def perform_workflow(%Oban.Job{} = job) do
  start = System.monotonic_time(:millisecond)
  {:ok, response} = MyApp.LLM.complete(prompt)
  latency = System.monotonic_time(:millisecond) - start

  Stats.record(job, %{
    model: response.model,
    input_tokens: response.usage.input_tokens,
    output_tokens: response.usage.output_tokens,
    cache_read_tokens: response.usage.cache_read_input_tokens,
    cache_write_tokens: response.usage.cache_creation_input_tokens,
    latency_ms: latency
  })

  {:ok, %{text: response.content}}
end

Convention: embed usage in the result map

The easiest approach is to embed llm_usage in the result you return from perform_workflow/1. LLMWorker.__handle_result__/2 will strip it out before passing the result to downstream steps and record stats automatically:

def perform_workflow(job) do
  {:ok, response} = call_llm(job)

  {:ok, %{
    text: response.text,
    llm_usage: %{                          # ← picked up automatically
      model: response.model,
      input_tokens: response.usage.input_tokens,
      output_tokens: response.usage.output_tokens,
      latency_ms: response.latency_ms
    }
  }}
end

The llm_usage key is stripped before the result is stored in meta and before it's returned to downstream steps, so they never see it.

Querying

# Total cost for a workflow
Stats.workflow_totals("my-workflow-uuid")
# => %{input_tokens: 12_430, output_tokens: 3_100, cost_usd: #Decimal<0.12>}

# Per-step breakdown
Stats.steps_for_workflow("my-workflow-uuid")

# Cost by model across all workflows in a time window
Stats.cost_by_model(~U[2025-01-01 00:00:00Z], ~U[2025-02-01 00:00:00Z])