installMetricTap
Install an opt-in metric tap on this device and start offering its metric buffer for extraction. A no-op until called — kuilt never opens a metric session implicitly.
Hosts a session on loom and continuously offers exporter's metric buffer for replication to any peer that joins. The tap is fabric-agnostic: pass a loopback WebSocket Loom for a simulator/CI puller (the default and safest choice), or a LAN/peer-to-peer Loom to reach a real device. Discovery and admission are the Loom's concern, not the tap's.
Parameters
the fabric to host the session on. Bind it to loopback by default.
the device's metric buffer to offer.
the scope the host's replicator runs in. Closing the returned host (or cancelling this scope) stops the tap.
tap tuning; the defaults suit a developer turning the tap on to debug.
how peers are admitted. The default LogTapAdmission.Open keeps the loopback-safe ungated behaviour; pass LogTapAdmission.Verify to require a join code before a peer can pull (see installMetricTapJoining for the device-joins topology). The same LogTapAdmission type gates both the log and metric taps.
Samples
// The device's converged metric buffer — the same one the metric pipeline fills.
val exporter = WarpMetricExporter(
replica = ReplicaId("device-uuid-abc123"),
store = InMemoryDurableStore(),
)
// The fabric the two peers meet over. An in-memory/loopback Loom is the
// simulator-and-CI case; swap it for a LAN or peer-to-peer Loom to reach a real phone.
val loom = InMemoryLoom()
// On the device: turn the opt-in metric tap on. It does nothing until called and is
// loopback-bound by default. Hold the host; close it to stop offering metrics.
val host = installMetricTap(loom, exporter, scope)
// In the test / CI harness: join the same session and pull the converged snapshot —
// every counter, gauge and cardinality collapsed to the numbers the device reports.
val client = MetricTapClient(loom.join(InMemoryTag("puller")), scope)
val metrics: MetricSnapshot = client.pull()
// Release both replicators when finished.
client.close()
host.close()
return metricsval exporter = WarpMetricExporter(
replica = ReplicaId("device-uuid-abc123"),
store = InMemoryDurableStore(),
)
val loom = InMemoryLoom()
// Expose the metric tap on a real network behind the same admission gate the log tap
// uses. Mint a short-lived join code from a CRYPTOGRAPHICALLY SECURE source —
// cryptoRandom() — the code is the only secret, so never Random.Default.
val secure = cryptoRandom()
val token = LogTapJoinToken.issue(random = secure, clock = Clock.System)
val host = installMetricTap(loom, exporter, scope, admission = LogTapAdmission.Verify(token, Clock.System, secure))
// Show token.code to the operator OUT OF BAND (the library never logs it), then present
// it from the puller. A wrong or expired code is refused before any metric replicates.
val client = MetricTapClient(
loom.join(InMemoryTag("puller")),
scope,
admission = LogTapAdmission.Present(token.code),
)
val metrics: MetricSnapshot = client.pull()
client.close()
host.close()
return metrics