Skip to content

Decision record · ADR

ADR-0079: Allocate a Specialized Engine metrics port only when the stack opts in

Status: accepted | Date: 2026-11-09

References: RFC-0003, ADR-0071, ADR-0078

Qualifying an Engine-provided KV store (ADR-0078) needs per-Engine evidence: whether the replica that did not condition a prefix read it through the store. One Specialized Engine implementation keeps those counters per Engine and serves them on an HTTP listener it opens only when given --metrics-port PORT, binding that port on the host of --listen; on a replica spanning hosts only host 0 accepts it. Passing it through extra_args gives every replica the same fixed port, which collides when replicas share a machine, or 0, whose chosen port appears only in the Engine’s log. Under ADR-0071 every contract argument reaches every Specialized Engine, and other Engine implementations do not accept --metrics-port.

The Specialized Engine integration accepts the stack setting engine_metrics, a boolean fact of the Engine implementation, absent by default. When true, every Engine replica declares one additional logical port metrics, rank zero receives --metrics-port with its allocated port as a contract argument, and an extra_args entry naming --metrics-port is rejected during planning. The Engine serves its metrics on that port on the host of its listen address. The allocated port is recorded with the Engine’s other ports. InferLab does not scrape it; a recorded run reads it from the server record. Absent or false, nothing changes.

An Engine with a metrics listener exposes per-replica counters at an allocated, recorded address, so several replicas on one machine never collide and a recorded run can snapshot each Engine without parsing logs. Engines that do not declare it are unaffected. Every rank of a replica spanning hosts is allocated the port though only rank zero renders it. No adapter protocol, record schema, or control-plane change is needed; the change ships with the Specialized Engine integration.

Allocate and render the Engine metrics port only when the stack declares engine_metrics (accepted)

Section titled “Allocate and render the Engine metrics port only when the stack declares engine_metrics (accepted)”
  • Pros: Engines that do not open a metrics listener receive exactly the arguments they receive today, The port is allocated per replica and recorded, so a recorded run reads it from the server record
  • Cons: One more stack setting; ranks other than zero of a multi-host replica hold an allocated port they do not use

Make –metrics-port a contract argument every Specialized Engine receives (rejected)

Section titled “Make –metrics-port a contract argument every Specialized Engine receives (rejected)”
  • Cons: Every other Engine implementation must accept an option it has no use for or fail before SERVING

Keep the port in extra_args with value 0 and read the chosen port from the Engine log (rejected)

Section titled “Keep the port in extra_args with value 0 and read the chosen port from the Engine log (rejected)”
  • Cons: Qualification evidence would rest on parsing a log line rather than an allocated, recorded port

Have InferLab scrape each Engine’s metrics at Bench window boundaries (rejected)

Section titled “Have InferLab scrape each Engine’s metrics at Bench window boundaries (rejected)”
  • Cons: A new measurement capability no workflow beyond this qualification needs; allocation and recording suffice for a recorded run to scrape