internal state、dumper_control 与 freeze_gc 控制路径#

这章解决什么问题#

扩展与调试部分前面已经讲了 logger、exporter、watchdog、loads、single-rid 证据链，但还缺一类更偏底层维护与实验性的控制能力：如果你要直接拉内部状态快照、控制 dumper、或者冻结 GC，这些路径是怎样进入系统的？它们应该被看成调试工具、控制面，还是危急情况下的手术刀？

这一章专门把这类低层控制路径收进主线。

为什么这层值得成章#

因为这些能力虽然不属于日常用户路径，但对维护者和平台工程师很有价值：

  • get_internal_state() / set_internal_state() 提供更直接的内部视图与注入能力
  • dumper_control() 控制更底层证据采集
  • freeze_gc() 影响运行时垃圾回收行为

这类能力一旦存在，就说明系统作者已经把“深入观察和人工干预”当成正式维护需求，而不是临时加的 debug hack。

一张图：这类低层控制不是从日志系统旁路进去，而是走正式 communicator 控制面#

这张图解决的理解障碍是：很多人会以为这些低层控制是本地函数直调，而源码实际让它们走和其他控制请求一致的 manager 通道。

flowchart LR
    Tool["maintainer control request"] --> TM["TokenizerManager communicator"]
    TM --> SCH["Scheduler control handlers"]
    SCH --> Dump["dumper / internal state / freeze_gc"]

图比纯文字多解释的一点是：这些命令不是偷偷直连某个对象，而是作为正式控制消息进入运行时。

TokenizerManager 这一侧提供了哪些入口#

tokenizer_communicator_mixin.py 已经把这些能力显式暴露成 async 控制方法：

  • get_internal_state()
  • set_internal_state()
  • dumper_control()

这说明对外控制面并不只有 flush/load/profile，也包括更偏内部观测的控制动作。

get_internal_state() 为什么很有价值#

它会通过 communicator 发 GetInternalStateReq()，然后收各 rank 返回的 GetInternalStateReqOutput。这意味着内部状态快照不是本地线程里临时打印一下，而是可以跨 rank 正式收集。

对维护者来说，这特别重要，因为很多问题正是“单个 rank 看起来没事，但全局状态不一致”。

set_internal_state() 为什么更敏感#

它不是只读，而是允许把状态写回去。也正因为这样，这一层更像“手术刀”而不是普通诊断工具。一本技术书应该把这类能力讲明白：

  • 它很强
  • 但它不是常规路径
  • 它更适合实验、复现、受控修复或深度调试场景

dumper_control() 如何补上证据采集链的最后缺口#

前面的 dump / logger / exporter 章节更多是在讲“系统默认会落什么证据”；dumper_control() 则更像“维护者要不要主动改变采集策略”。这说明 dump 系统并不只是静态存在，而是允许被动态控制。

这类能力在复杂 runtime 中非常有价值，因为很多时候你并不想永远开着最重的 dump，只想在问题窗口期临时打开。

freeze_gc() 为什么也走正式控制面#

FreezeGCReq 会被 scheduler handler 接住，随后调用 freeze_gc("Scheduler")，并继续往下游路径传。这说明 GC 冻结并不是本地脚本 hack，而是被纳入正式运行时控制语义的一部分。

这非常值得写进书里，因为它说明系统已经承认：某些问题可能需要短期改变运行时内存管理策略，而不是只靠外部观测。

为什么这层应该放在维护层，而不是运行时架构正文里#

因为这里关注的重点已经不是“系统平时怎样工作”，而是“当常规观测不够时，还能怎样更直接地窥探或控制系统内部状态”。这更像 maintainer-grade controls，而不是一般读者首先需要掌握的架构路径。

这一层最容易出现的误判#

1. 把 get_internal_state() 当成普通日志#

它更像一次跨 rank 的状态快照采集。

2. 把 set_internal_state() 当成常规接口#

它更接近调试/实验工具，而不是一般业务调用路径。

3. 以为 freeze_gc() 只影响本地进程#

它走的是正式控制消息路径，影响的是运行时控制面。

如果你要用这些低层控制，先怎么走#

建议按这个顺序：

  1. 先确认常规证据链是否已经不够。
  2. 再决定是要“看状态”还是“改状态”。
  3. 若要采集更重证据，再配合 dumper control。
  4. 若问题与 GC / 内存抖动相关，再考虑 freeze_gc。

小结#

这一章真正要补齐的，是维护层里最深的一层控制面：

  • 常规观测给你证据
  • internal state / dumper / freeze_gc 则给你更直接的观察与干预手段

到这里，扩展与调试部分就不只是在讲“如何看系统”，也开始讲“在极端情况下，如何更直接地摸到系统内部”。