mirror of
https://github.com/kvcache-ai/Mooncake.git
synced 2026-11-05 01:17:55 +00:00
[GH-ISSUE #2864] [RFC]: TENT Operator CLI and Sanitized Diagnostic Bundle #742
Labels
No labels
ascend
auto-closed
bug
bug
CI/Build
Common
documentation
enhancement
feature request
good first issue
help wanted
high priority
MetaX
nightly-failure
pull-request
PyTorch Backend
question
RFC
Roadmap
stale
Store
Tests
Transfer Engine
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
kvcache-ai/Mooncake#742
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Originally created by @catyans on GitHub (Jul 12, 2026).
Original GitHub issue: https://github.com/kvcache-ai/Mooncake/issues/2864
Summary
This RFC proposes a single TENT operator CLI, tentatively named
tent, and a versioned sanitized diagnostic bundle format.The goal is to let an operator answer the following questions without reading TENT source code or manually correlating many logs:
The first implementation milestone is read-only. It must not hot-reload configuration, quarantine a rail, trigger failover, change QoS policy, or upload diagnostics automatically.
The CLI should reuse existing functionality rather than create parallel implementations:
show-linkand NIC discovery from #2820;tebenchfor performance testing;Motivation
The TENT roadmap in #1058 explicitly lists an isolated transfer/diagnostics CLI as a community-contributable production-readiness item. TENT has accumulated many useful mechanisms, but their operational interfaces remain fragmented.
Examples:
show_link, including local NIC discovery, NUMA affinity, link speed, and a readable/JSON topology matrix.tebenchexercises real transfers and already contains multiple benchmark modes.probePeerAliveByID()can test control-plane liveness.These are useful data sources, but users still need different binaries, configuration knowledge, log patterns, and manual interpretation. A failed cross-node run often requires separately checking:
This increases support cost and makes bug reports difficult to reproduce. The CLI should provide a common diagnostic model and explain what it observed, what it inferred, and what it could not verify.
Goals
tentcommand with stable subcommands.Non-goals
tebench.Proposed command surface
The exact spelling can be adjusted during review, but the command responsibilities should remain distinct.
tent versionPrint:
tent show-topologyDisplay the local topology known to TENT:
This command should call the same topology/prober code used by TENT, not parse a second set of sysfs files independently.
tent check-configValidate an effective configuration without starting transfer traffic.
Checks should include:
The output must distinguish:
PASS: verified and valid;WARN: valid but suspicious or unverifiable;FAIL: invalid or unsafe;SKIP: collector/feature unavailable in this build.tent show-linkReuse #2820's
show_linkimplementation and output model. The existing binary may remain as a compatibility wrapper or alias.In later milestones, an optional remote target may add:
tent test-runPerform a small, bounded connectivity test using registered scratch memory.
It should report separately:
Safety requirements:
tent show-planConsume #2863's planner or legacy decision adapter and explain:
Before #2863 is implemented, this subcommand may be absent or limited to the current selector decision. The CLI RFC must not define a second Execution Plan model.
tent statusQuery a local running TENT instance through a bounded local interface in a later milestone. Candidate fields:
The local query interface should default to a Unix socket or localhost and must not block transfer progress. This command is observation-only; health-policy automation belongs to a separate RFC.
tent collect-diagnosticsCollect a bounded snapshot from available commands and data sources.
Suggested contents:
manifest.jsonwith bundle/schema version and checksums;The bundle is created locally and is never uploaded automatically.
tent benchThis is an optional convenience frontend to
tebench, not a new benchmark implementation. It should preserve access to the underlying tebench command line and output schema. More complex benchmark changes should continue to land in tebench first.Diagnostic data model
All subcommands should build a normalized diagnostic result before rendering text or JSON.
Collector failures should be represented in the result instead of aborting the entire bundle, unless a required command input is invalid.
JSON compatibility
Machine-readable output is a public operational contract.
Rules:
schema_versionis required;latency_us,bandwidth_bps);Example:
Redaction and security
Diagnostics frequently contain deployment-sensitive information. Redaction must happen at collection/model boundaries, not as a final regex over serialized JSON.
Always excluded by default
Redaction modes
Suggested modes:
Strict mode can use a random per-bundle salt so the same host/device remains correlatable inside one bundle without being correlatable across bundles.
Bundle handling
Remote testing
test-runand remoteshow-linkmust use existing authenticated/authorized control paths where available. The CLI must not introduce an unauthenticated arbitrary-memory test server. A standalone validation server, if needed later, requires an explicit security design and is out of v1 scope.Offline and live modes
Commands fall into two groups.
Offline/local discovery
versionshow-topologycheck-configshow-linkThese should work without a running TENT instance or metadata service when possible.
Live/remote diagnosis
show-linktest-runshow-planwith remote metadatastatuscollect-diagnosticsThese must report partial/unavailable state clearly when the peer or metadata service cannot be reached.
Exit codes
Suggested stable exit codes:
Warnings alone return zero unless
--strictis specified. JSON output must still be emitted for diagnostic failures whenever possible.Architecture
Collectors should be reusable libraries rather than logic embedded directly in
main(). Existing commands such asshow_linkcan call the same collector/rendering library.Optional collectors must be isolated by build feature. A CPU-only build should still provide config/topology checks and report GPU/RDMA collectors as unavailable rather than failing to build the CLI.
Compatibility and rollout
show_linkbehavior remains available during migration.Proposed PR sequence
PR1: Diagnostic core and schema
DiagnosticSnapshot, checks, evidence, renderers, redaction primitives, and schema tests.tent version.PR2: Topology and existing show-link integration
tent show-topologyandtent show-linkusing existing collectors.show_linkas a wrapper/alias if maintainers prefer.PR3: Config validation
tent check-config.PR4: Bounded connectivity test
tent test-runusing scratch registered buffers.PR5: Plan explain
tent show-planby consuming #2863.PR6: Live status and diagnostic bundle
tent statusandtent collect-diagnostics.Later work
tent benchconvenience integration with tebench;Validation plan
Unit and schema tests
Differential tests
tent show-linkmatches the existing #2820 collector output;tent check-configaccepts configurations accepted by the runtime and rejects known-invalid configurations before runtime initialization;tent show-planmatches #2863 explain output;tent benchforwards to tebench without changing benchmark semantics.Real-cluster validation
On the existing H20/RoCE nodes, cover:
For every failure, the CLI should identify the furthest verified stage and avoid claiming later stages passed. For example, a successful control probe must not be reported as successful RDMA data connectivity.
Overhead
Expected benefits and claims boundary
This RFC should provide:
It does not claim to fix a failing path automatically or improve transfer performance. Any future remediation or automatic health policy requires separate design and validation.
Relationship to existing work
show-link; do not duplicate its discovery code.Open questions
tentthe preferred binary name, or should the initial commands live under an existing Mooncake CLI namespace?show_linkbecome a compatibility wrapper aroundtent show-link, or remain independently installed?show-topology,check-config, andshow-link, or shouldtest-runalso be included?collect-diagnosticscreate a directory, JSON file, or compressed archive by default?benchremain visibly separate from tebench until the rest of the CLI stabilizes?Before submitting a new issue...
@github-actions[bot] commented on GitHub (Jul 12, 2026):
Thanks for opening this issue, @catyans!
18214026A maintainer will triage this when possible. To help us respond faster, please include:
Useful links: Documentation · Contributing guide
@catyans commented on GitHub (Jul 12, 2026):
Real topology-source feasibility experiment on 2026-07-13 using the current
show_linkimplementation from merge head159712b7.Environment: Lingjun H20
lingjun-099, Linux 5.10.134, 2 x Xeon Platinum 8575C / 192 vCPUs / 2 NUMA nodes, 8 x H20-3e, driver 580.105.08, five mlx5 HCAs. Built with GCC 13.3,BUILD_EXAMPLES=ON,USE_TENT=ON,USE_CUDA=OFF. Command:show_link --discover_only --json.Results:
local_nicsandtopology;mlx5_bond_0as temporarily unavailable and returned only 4 NICs;Conclusion: the underlying topology collection is fast enough for an operator command and already exposes useful structured data, but the transient 4/5 result shows why the RFC needs explicit
complete/degraded, per-probe errors, timestamp/generation and retry guidance. A partial snapshot must not look authoritative. This also confirms thatshow-topologyshould combine multiple probes rather than simply wrap the current JSON.@alogfans commented on GitHub (Jul 17, 2026):
We believe these peripheral components are a priority at this stage.
@catyans commented on GitHub (Jul 21, 2026):
Thanks — just to confirm, do you mean these operator and diagnostic components are a priority at the current stage? If so, I will start with a small read-only PR containing the diagnostic schema, JSON renderer, and tent version, without transport initialization or runtime control changes.
@catyans commented on GitHub (Jul 31, 2026):
I will take the priority feedback as support for the smallest read-only implementation slice: diagnostic schema, JSON rendering, and version reporting only, without transport initialization, runtime mutation, or control commands. I will link the implementation PR here once that focused slice is ready.
@0z5a commented on GitHub (Sep 16, 2026):
Hi @catyans , I'd like to take PR1 (Diagnostic core and schema):
DiagnosticSnapshot/ checks and evidence, text + JSON renderers, redaction primitives, schema tests, andtent version, keeping it offline-only with no transport initialization or remote calls.I'll keep unresolved RFC choices (such as the final CLI naming and broader redaction policy) minimally coupled so they can be adjusted during review.
@0z5a commented on GitHub (Sep 16, 2026):
PR1 implementation is now available in #4154. It adds the diagnostic schema/core model, text and JSON renderers, redaction primitives, schema and redaction tests, and the offline-only
tent versioncommand. The CLI does not link or initialize transports, metadata clients, device runtimes, or remote connections.@noqt commented on GitHub (Oct 2, 2026):
For the RFC's additive-field compatibility and secret-non-disclosure tests, one additional case is a nested object under an ordinary field name:
At PR1 head
042b7ce25c99, passing that object tosanitize("details", value)uses the default public classification and checks the outer field name; it does not classify the child keys. This is a proposed regression case for future collectors, not a claim thattent versionexposes deployment data. It is distinct from the existing review about dynamic summaries/remediation.A useful offline test specification:
This makes the distinction explicit: accepting an additive input field need not mean publishing it. The existing unavailable-is-not-zero test can remain a separate invariant.
I work on noqt's Eggcracker receipt exporter. Its immutable synthetic recipe is an optional fixed-schema example: fabricated input, offline command, no private logs or native workload. It is not a TENT integration. The export says
NOT_AUTHENTICATEDandNOT_PERFORMED: a hash binds input bytes, not the producer's identity, and no live containment was checked. I have not run the proposed TENT test.@xiaodouzi666 commented on GitHub (Oct 14, 2026):
Hi @catyans, thanks for the RFC. I would like to take PR2–PR4 of the plan on top of #4154 (with the follow-up fixes proposed there), and we have a working implementation that we validated on two 8×H20 hosts with five ConnectX NICs each (no root): single-host fault injection, and a two-host run where a 5×5 NIC-pair matrix agreed with
ib_write_bwin both directions.I will push a preview branch with the full stack and link it here before opening the first PR.