Package org.mockserver.mock.action.http

Class LlmCostBudgetMonitor

java.lang.Object

org.mockserver.mock.action.http.LlmCostBudgetMonitor

public class LlmCostBudgetMonitor
extends Object

Cost-budget circuit-breaker for LLM forwarding. When the cumulative LLM cost (tracked by the mock_server_llm_cost_usd metric) exceeds the configured budget (mockserver.llmCostBudgetUsd), further LLM forwarding is halted with a 429 response and a WARN log.

The monitor is deterministic and fail-open: a negative, unset, or malformed budget never blocks traffic. It is reset by HttpState.reset().

Unlike the chaos auto-halt which removes registrations, this breaker returns a clear error response rather than modifying state — the user explicitly set a cost ceiling, so we respect it per-request.

The singleton pattern matches ChaosAutoHaltMonitor and ServiceChaosRegistry.

Method Summary

Modifier and Type	Method	Description
HttpResponse	checkBudgetOrNull()	Check the budget and return an error response if exceeded, or null if the request should proceed.
double	getCumulativeCostUsd()	Return the cumulative cost in USD.
static LlmCostBudgetMonitor	getInstance()
long	getTripCount()	Return the number of times the budget breaker has tripped.
boolean	isBudgetExceeded()	Check whether the cost budget is exceeded.
void	recordCost(Double costUsd)	Record a cost increment.
void	reset()	Reset the monitor state.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

getInstance

public static LlmCostBudgetMonitor getInstance()

recordCost

public void recordCost(Double costUsd)

Record a cost increment. Called after a completion is served or forwarded.

Parameters:

costUsd - the estimated cost in USD (null or non-positive is ignored)

isBudgetExceeded

public boolean isBudgetExceeded()

Check whether the cost budget is exceeded. Returns true if the budget is configured (positive) and the cumulative cost has exceeded it. Returns false if the budget is unset, negative, or not yet exceeded — fail-open on misconfig.

checkBudgetOrNull

public HttpResponse checkBudgetOrNull()

Check the budget and return an error response if exceeded, or null if the request should proceed. This is the choke-point guard called before LLM forwarding.

getCumulativeCostUsd

public double getCumulativeCostUsd()

Return the cumulative cost in USD.

getTripCount

public long getTripCount()

Return the number of times the budget breaker has tripped.

reset

public void reset()

Reset the monitor state. Called on server reset.