ironflow capacity

Inspection of the unified capacity/dispatch subsystem (ADR 0037, #1206). Read-only views over the database-backed capacity tables. Requires platform credentials (any platform principal — platform_admin, operator, or viewer; the gate is “is-platform”, not a specific role) — set IRONFLOW_API_KEY to a ifplatform_ key or authenticate via ironflow platform login. Regular tenant keys return 403.

Dev mode caveat

ironflow serve in dev mode (--dev) injects a non-platform request context, so capacity endpoints always return 403 in dev. Use a platform API key against a production or staging server.

ironflow capacity <subcommand> [flags]

Subcommands:

Subcommand	Description
lanes	List concurrency lanes (lane digest, env, function, limit, active_reserved)
queue	List dispatch_queue segments (queue position, run ID, exec mode, blocking reason)
leases	List active (unexpired) concurrency leases
buckets	List dispatch fairness-ledger buckets
sessions	List pull-worker sessions
credits	List pull-worker credits (claimed and free slots)
stats	Per-(environment, function) capacity snapshot: active leases, lane limit, queued segments, reservations, oldest queue age

All subcommands share the same flags:

Flags:

Flag	Short	Type	Default	Description
--server	-s	string		Server URL (default: IRONFLOW_SERVER_URL or http://localhost:9123)
--env		string		Filter by environment ID
--function		string		Filter by function ID
--json		bool	false	Output as JSON instead of a table

Filter caveats:

• stats ignores --env and --function — it always returns the full per-(environment, function) snapshot.
• leases and credits ignore --function — concurrency_leases and worker_credits have no function_id column; only --env filtering applies.
• Lane identities are returned as opaque HMAC digests. Lease entries carry lease_token_hash only — raw lane keys and lease tokens are never stored or returned.

Examples:

# Summary snapshot: active leases, queue depth, lane limits per function
ironflow capacity stats

# Inspect a specific function's lane state
ironflow capacity lanes --function my-fn

# View the dispatch queue for one environment as JSON
ironflow capacity queue --env env_default --json

# List active leases (env filter only; function filter ignored)
ironflow capacity leases --env env_default

# List pull-worker sessions
ironflow capacity sessions

# List pull-worker credits
ironflow capacity credits

# Inspect fairness-ledger buckets for a function
ironflow capacity buckets --function my-fn

Output columns (table mode):

lanes: LANE_DIGEST, ENV, FUNCTION, SCOPE, LIMIT, ACTIVE_RESERVED queue: QUEUE_SEQ, RUN_ID, EXEC_SEQ, MODE, FUNCTION, LANE_DIGEST, BLOCKING, ELIGIBLE_AT leases: LEASE_ID, RUN_ID, EXEC_SEQ, LANE_DIGEST, EXPIRES_AT, NODE buckets: ENV, FUNCTION, LANE_DIGEST, LAST_DISPATCHED_AT sessions: SESSION_ID, WORKER_ID, NODE, ENV, DRAINING, HEARTBEAT_EXPIRY credits: CREDIT_ID, WORKER_ID, SESSION_ID, SLOT, CLAIMED, CLAIMED_RUN_ID stats: ENV, FUNCTION, ACTIVE_LEASES, LANE_LIMIT, QUEUED, RESERVATIONS, OLDEST_QUEUE_AGE_S

---