[mathemakitten]

• I, the PR author, have personally reviewed every line of this PR.

What does this PR do ?

• Adds a RouterTracer class that captures per-layer top-K routing decisions via forward hooks on TopKRouter modules, writing one JSONL record per (step, layer, rank). Works identically for training and inference.
• Adds tools/moe_routing/ with two analysis scripts that work on traces from either training or inference:
  • analyze_routing_concentration.py — per-layer expert activation frequency, top-N coverage curves, and a heatmap of hot experts vs layers.
  • analyze_routing_predictability.py — applies layer L's router weights to L_prev's hidden states and measures cosine/Spearman similarity between predicted and actual per-expert token-count distributions. High scores here are the affirmative signal that distributional routing is predictable one layer ahead.

Notes on usability

• Use --moe-routing-trace-max-iters / --moe-routing-trace-max-steps to bound the capture window; the tracer self-disables and removes its hooks after the limit is reached
• Python forward hooks do not fire during CUDA graph replay. Run with --cuda-graph-impl none when collecting traces.
• analyze_routing_predictability.py requires --moe-routing-trace-capture-hidden-states and --moe-routing-trace-dump-weights at collection time.

Follow-up items

• Unify hook registration helpers: megatron/training/activation_logging.py has a generic _register_hooks(model, module_types, hook_factory) utility that walks model chunks and registers forward hooks. RouterTracer.register_hooks does the same thing with a loop. These can be consolidated with a shared helper into core/, but requires some more work to unify the hook registration pattern (_register_hooks in activation_logging.py does not currently live in core).

Issue tracking

For PRs from open-source community contributors:

• New features: a linked issue is required. Please open a feature request and reference it here before submitting the PR.
• Small updates (bug fixes, minor improvements): a linked issue is recommended and will accelerate the PR review process.

Linked issue:

Contribution process

Pre-checks

• I have added relevant unit tests
• I have added relevant functional tests
• I have added proper typing to my code Typing guidelines
• I have added relevant documentation
• I have run the autoformatter.sh on my PR

Code review

Feel free to message or comment @NVIDIA/mcore-oncall to help accelerate your merge into main. The less complex your PR is, the faster it will be approved and merged!

All PRs start as draft. If you open a non-draft PR, it will be automatically converted to draft.

Step 1: Mark PR as "Ready for Review"

1. When your PR is ready, click Ready for Review.
2. An oncall reviewer is auto-assigned and expert reviewers are notified based on your changes.
   • Some PRs may jump straight to step 2. This is determined by .github/CODEOWNERS.

⚠️ Only mark as ready once merge-conflicts are resolved and the CI is passing.
Final Review might get declined if these requirements are not fulfilled.

Step 2: Final Review

For PRs that change megatron/core, once all expert reviewers have approved, the Final Review label is applied automatically and final reviewers are assigned.

For PRs outside megatron/core, this step is skipped.

Step 3: Approved

Once all required reviewers have approved, the Approved label is applied automatically.

Merge

Any member of mcore-engineers will be able to merge your PR.

[github-actions]

This PR has been automatically converted to draft because all PRs must start as drafts.

When you are ready for review, click Ready for Review to begin the review process. This will:

1. Add the oncall reviewer (optional reviewer)
2. Add required review teams based on your changes

See the contribution guide for more details.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[maanug-nv]

wouldn't LoggerConfig make more sense for these settings?

[mathemakitten]

Yes, moved.

[svcnvidia-nemo-ci]

🔄 Merge queue validation started!

You can track the progress here: https://github.com/NVIDIA/Megatron-LM/actions/runs/28890461242