RFC-0051-Structured-call_hierarchy-metadata-for-FX-nodes#92
Conversation
|
Hi @andrewd-aws! Thank you for your pull request and welcome to our community. Action RequiredIn order to merge any pull request (code, docs, etc.), we require contributors to sign our Contributor License Agreement, and we don't seem to have one on file for you. ProcessIn order for us to review and merge your suggested changes, please sign at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need to sign the corporate CLA. Once the CLA is signed, our tooling will perform checks and validations. Afterwards, the pull request will be tagged with If you have received this in error or have any questions, please contact us at cla@meta.com. Thanks! |
|
|
||
| The implementation builds on existing Dynamo infrastructure. During proxy creation, `stack_trace` is already built by walking the InstructionTranslator (tx) parent chain. `call_hierarchy` is built during the same walk: at each frame, if `nn_module_stack` has new keys compared to the previous frame, the frame is a module entry; otherwise it is a function entry (filtered for torch-internal and non-meaningful frames). Because both module and function entries come from the same ordered traversal, the interleaving is correct by construction. This works regardless of how modules override `__call__` or `forward`. Module invocation counts come from `nn_module_stack`'s existing `@N` key suffix. Function invocation counts are tracked via a `function_call_counts` dict shared across the tx chain, incremented when `InliningInstructionTranslator` is created. | ||
|
|
||
| We can gate the feature by `torch._dynamo.config.record_call_hierarchy` (default `False`). When disabled, zero additional work is performed. Or, if overhead is low enough have it on by default. |
There was a problem hiding this comment.
I think this is an interesting callout - from the prototyped implementation, do we have a feeling for the runtime overhead?
There was a problem hiding this comment.
We're actively working on getting some numbers on this
There was a problem hiding this comment.
checking back on this, do you have the numbers for the overhead?
|
|
||
| ## Alternatives | ||
|
|
||
| - Parse `stack_trace` strings at consumption time. This is what consumers do today and it is fragile, lacks invocation counts, and cannot be correctly interleaved with `nn_module_stack`. |
There was a problem hiding this comment.
I'mm interested in why this is fragile. stack_trace gives you the exact line, which one can use for line-level profiling and etc. Can you give a little more detail on why the new proposal would be easier to use than stack_trace?
There was a problem hiding this comment.
Would be helpful if you can describe a concrete use-case for the new node meta.
There was a problem hiding this comment.
Sorry for the delay on this.
Yes, I agree stack_trace works well for line-level profiling and pointing developers to source locations.
A concrete use case for us where this breaks down is with profiling, where we want to display each instruction annotated with its origin in the model as a hierarchical path, so users can expand and collapse the model structure to identify bottlenecks across related ops at any level of granularity. Building this path requires knowing, for each FX node, the complete interleaved sequence of modules and functions that produced it, including invocation counts to distinguish repeated calls to shared modules or helpers. nn_module_stack provides the module nesting but is missing function calls entirely, and stack_trace includes functions but filters out module frames and has no invocation counts; neither alone nor together can one infer this interleaved path with invocation counts correctly.
So essentially the difficulty is in reconstructing the hierarchical scope tree from what we currently output w.r.t. op provenance. Module frames from torch/nn/modules/ are filtered out by is_co_filename_from_nn_modules(), so module boundaries don't appear in the trace. You could try to recover them by parsing the source file at the line number indicated in the trace (e.g., read line 8, see self.qkv(x), infer the module), but this requires source file access at consumption time and I see this breaking for dynamic attribute access, generated code, etc. Invocation counts for shared modules or functions called in a loop are also unrecoverable. The proposed call_hierarchy would provide this information directly.
IvanYashchuk
left a comment
IvanYashchuk
left a comment
There was a problem hiding this comment.
I like the direction of this RFC. The parts I would tighten before treating this as a supported metadata contract are:
- Overhead. Can we add actual enabled/disabled numbers to the RFC? The disabled case should be effectively zero, and the enabled case should include memory overhead from per-node hierarchy lists, not only instruction count.
- Schema identity.
function.nameand leafattrlook like display labels. Do we want this to be a stable consumer contract? If yes, I think we need at least functionqualname/source location and full module path, or an explicit statement that this is best-effort debug metadata. - Transform behavior. Can we document what should happen across decomposition, fusion, graph breaks, AOTAutograd backward nodes, and generated nodes?
fwd_call_hierarchyis useful, but it should be clear that backward ops carry forward-origin metadata, not that they were directly authored at the forward location.
MLIR prior art seems relevant here: they make operation location first-class and use callsite/fused/name locations to preserve source and fusion provenance. I am not suggesting copying that API, but I think the RFC should separate source/debug provenance from metadata that can affect compiler behavior.
| Each FX node gets a `call_hierarchy` field in `node.meta`: an ordered list of dicts from outermost to innermost scope. Each entry is either a module entry or a function entry: | ||
|
|
||
| ```python | ||
| [ | ||
| {"type": "module", "class": "Qwen2Model", "attr": "model", "count": 0}, | ||
| {"type": "module", "class": "Qwen2Attention", "attr": "self_attn", "count": 0}, | ||
| {"type": "function", "name": "apply_rotary_pos_emb", "count": 0}, | ||
| {"type": "function", "name": "rotate_half", "count": 1}, | ||
| {"type": "module", "class": "Linear", "attr": "q_proj", "count": 0}, | ||
| ] | ||
| ``` |
There was a problem hiding this comment.
Are name and attr intended as display labels or stable identifiers?
If downstream tools are expected to rely on this, I think function entries need at least qualname and source location, and module entries probably need the full module path instead of only the leaf attr. Same-named helper functions or repeated modules from generated/model code will otherwise be hard to distinguish.
| ] | ||
| ``` | ||
|
|
||
| The `count` field is a 0-indexed invocation count. For modules, this tracks shared module instances called multiple times. For functions, this tracks repeated calls to the same function. |
There was a problem hiding this comment.
Can we define the scope of count more precisely? Is it per parent scope, per code object, per graph capture, or per Dynamo fx chain?
If this is only for display disambiguation, that is fine, but if compiler heuristics can depend on it then we need stable behavior across graph breaks and recompilations.
|
|
||
| We can gate the feature by `torch._dynamo.config.record_call_hierarchy` (default `False`). When disabled, zero additional work is performed. Or, if overhead is low enough have it on by default. | ||
|
|
||
| `call_hierarchy` is added to `_COPY_META_FIELDS` in `fx/proxy.py` so it survives graph transformations. Backward nodes receive `fwd_call_hierarchy` from their corresponding forward node, following the established `fwd_nn_module_stack` pattern in `copy_fwd_metadata_to_bw_nodes`. |
There was a problem hiding this comment.
fwd_call_hierarchy makes sense, but can we document the AOTAutograd path more explicitly?
This looks like it requires more than Dynamo-time FX node construction: the prototype also updates AOTAutograd's copy_fwd_metadata_to_bw_nodes path, where backward nodes are matched to forward nodes by seq_nr after AOTAutograd creates the joint graph. It would help to spell out which parts of the stack are responsible for producing, preserving, and copying call_hierarchy: Dynamo proxy creation, FX metadata copies, AOTAutograd retracing/decomposition, partitioning, and the final forward-to-backward metadata copy.
Also, can we document fwd_call_hierarchy as forward-origin metadata rather than the origin of the backward op itself? For profiling/debugging it matters whether a backward op was generated by an autograd rule for a forward op, recomputed from the forward, or directly present in user code.
|
|
||
| We can gate the feature by `torch._dynamo.config.record_call_hierarchy` (default `False`). When disabled, zero additional work is performed. Or, if overhead is low enough have it on by default. | ||
|
|
||
| `call_hierarchy` is added to `_COPY_META_FIELDS` in `fx/proxy.py` so it survives graph transformations. Backward nodes receive `fwd_call_hierarchy` from their corresponding forward node, following the established `fwd_nn_module_stack` pattern in `copy_fwd_metadata_to_bw_nodes`. |
There was a problem hiding this comment.
Copying through _COPY_META_FIELDS handles simple node copies, but I think the RFC should define the behavior for node creation and many-to-one transforms.
What should decomposition, fusion, partitioning, and generated guard/runtime nodes do with call_hierarchy? When many source ops become one op, preserving a fused/grouped origin is different from copying one arbitrary source path.
| - Profiling: mapping lowered ops back to model structure so users can identify bottlenecks at the layer or helper-function level. | ||
| - Debugging: tracing a failed or incorrect op to its exact location in the model, e.g. `Attention.q_proj > apply_rotary_pos_emb > rotate_half` | ||
| - Visualization: grouping ops by their origin in the model hierarchy when displaying FX graphs or lowered IR alongside model structure. | ||
| - Compiler heuristics: backends that partition, fuse, schedule, etc. based on model structure need structured scope information |
There was a problem hiding this comment.
This bullet makes the saved field sound like a compiler behavior contract, not just debug/profiling metadata.
Can we either define the stability/preservation guarantees needed for compiler heuristics, or narrow this bullet to diagnostics/profiling/visualization for now?
5 participants
RFC for call hierarchy metadata