From 2c558fcc8ea8da75ef6a807ac93e558028e01b70 Mon Sep 17 00:00:00 2001 From: JaydenXu Date: Sat, 14 Nov 2026 20:34:00 -0500 Subject: [PATCH] fix(instrumentor): skip meta-var injection in Triton-decorated functions --- .../instrumentor/auto_meta_var_injector.py | 188 ++++++++++++---- tests/test_auto_meta_var_injector.py | 200 ++++++++++++++++++ 2 files changed, 343 insertions(+), 45 deletions(-) create mode 100644 tests/test_auto_meta_var_injector.py diff --git a/opguard/instrumentor/auto_meta_var_injector.py b/opguard/instrumentor/auto_meta_var_injector.py index 3e26474..0c2e212 100644 --- a/opguard/instrumentor/auto_meta_var_injector.py +++ b/opguard/instrumentor/auto_meta_var_injector.py @@ -7,7 +7,7 @@ import libcst as cst from libcst._exceptions import ParserSyntaxError from libcst.metadata import MetadataWrapper -from typing import Set, List, Dict, Any +from typing import Set, List, Dict, Any, Optional from datetime import datetime import json @@ -26,6 +26,67 @@ } +# Bare decorator names that count as Triton when the module does `from triton[.x] import *`. +TRITON_STAR_DECORATORS = {"jit", "autotune", "heuristics"} + + +def _dotted_name(node: cst.BaseExpression) -> Optional[str]: + """Return "a.b.c" for a Name/Attribute chain, else None.""" + if isinstance(node, cst.Name): + return node.value + if isinstance(node, cst.Attribute): + base = _dotted_name(node.value) + return f"{base}.{node.attr.value}" if base else None + return None + + +def _is_triton_path(path: str) -> bool: + # Any whole dotted segment equal to "triton": covers `triton.*` and re-exports such as + # `from vllm.triton_utils import triton` (-> vllm.triton_utils.triton.jit); + # segments like "triton_utils" or "_triton" do not count. + return "triton" in path.split(".") + + +class _ImportAliasCollector(cst.CSTVisitor): + """Collect local name -> full module path for every absolute import in a module, any scope.""" + + def __init__(self): + self.aliases: Dict[str, Set[str]] = {} + self.triton_star_import = False + + def _bind(self, local: str, full: str) -> None: + self.aliases.setdefault(local, set()).add(full) + + def visit_Import(self, node: cst.Import) -> None: + for alias in node.names: + full = _dotted_name(alias.name) + if full is None: + continue + if alias.asname is not None: + self._bind(alias.asname.name.value, full) + else: + # `import a.b.c` binds the local name `a`. + root = full.split(".", 1)[0] + self._bind(root, root) + + def visit_ImportFrom(self, node: cst.ImportFrom) -> None: + if node.relative or node.module is None: + return + module = _dotted_name(node.module) + if module is None: + return + if isinstance(node.names, cst.ImportStar): + if _is_triton_path(module): + self.triton_star_import = True + return + for alias in node.names: + name = _dotted_name(alias.name) + if name is None: + continue + local = alias.asname.name.value if alias.asname is not None else name + self._bind(local, f"{module}.{name}") + + class AutoMetaVarInjector(cst.CSTTransformer): """ Automatically finds and wraps assignments to meta variables with update_meta calls. @@ -41,6 +102,41 @@ def __init__(self, meta_var_names: Set[str]): self.meta_var_names = meta_var_names self.injected = False self.assignments_count = 0 + self.skipped_functions = 0 + self._import_aliases: Dict[str, Set[str]] = {} + self._triton_star_import = False + + def visit_Module(self, node: cst.Module) -> bool: + # Collect imports from the whole module up front: traversal is in source order, and an + # import may appear after the kernel that uses it or inside another function. + collector = _ImportAliasCollector() + node.visit(collector) + self._import_aliases = collector.aliases + self._triton_star_import = collector.triton_star_import + return True + + def _is_triton_decorator(self, decorator: cst.Decorator) -> bool: + expr = decorator.decorator + if isinstance(expr, cst.Call): + expr = expr.func + name = _dotted_name(expr) + if name is None: + return False + if self._triton_star_import and name in TRITON_STAR_DECORATORS: + return True + first, sep, rest = name.partition(".") + # An unimported first segment is kept as-is (e.g. `triton` bound some other way). + for resolved_first in self._import_aliases.get(first, {first}): + if _is_triton_path(resolved_first + sep + rest): + return True + return False + + def visit_FunctionDef(self, node: cst.FunctionDef) -> bool: + """Do not descend into Triton kernels: update_meta() cannot be compiled by Triton.""" + if any(self._is_triton_decorator(d) for d in node.decorators): + self.skipped_functions += 1 + return False + return True def leave_SimpleStatementLine( self, original_node: cst.SimpleStatementLine, updated_node: cst.SimpleStatementLine @@ -48,7 +144,7 @@ def leave_SimpleStatementLine( """Insert update_meta calls after assignments to meta variables.""" new_body = list(updated_node.body) inserted_any = False - + # Process each statement in the line for idx, stmt in enumerate(new_body): if isinstance(stmt, cst.Assign): @@ -59,7 +155,7 @@ def leave_SimpleStatementLine( var_name = target.target.value if var_name in self.meta_var_names: meta_vars_in_assignment.append(var_name) - + if meta_vars_in_assignment: # Found assignment to meta variable(s) - create update_meta calls self.injected = True @@ -72,14 +168,14 @@ def leave_SimpleStatementLine( args=[cst.Arg(keyword=cst.Name(var_name), value=cst.Name(var_name))] )) update_calls.append(update_call) - + # Insert update_meta calls after this assignment insert_pos = idx + 1 for update_call in update_calls: new_body.insert(insert_pos, update_call) insert_pos += 1 inserted_any = True - + elif isinstance(stmt, cst.AugAssign): # Handle augmented assignments (e.g., +=, -=) if isinstance(stmt.target, cst.Name): @@ -94,17 +190,17 @@ def leave_SimpleStatementLine( )) new_body.insert(idx + 1, update_call) inserted_any = True - + if inserted_any: return updated_node.with_changes(body=new_body) - + return updated_node def leave_Module(self, original_node: cst.Module, updated_node: cst.Module) -> cst.Module: """Add imports if we injected any meta variable tracking.""" if not self.injected: return updated_node - + # Check if imports already exist has_import = False for stmt in updated_node.body: @@ -126,7 +222,7 @@ def leave_Module(self, original_node: cst.Module, updated_node: cst.Module) -> c break if has_import: break - + if not has_import: # Add import statement import_stmt = cst.SimpleStatementLine([cst.ImportFrom( @@ -137,7 +233,7 @@ def leave_Module(self, original_node: cst.Module, updated_node: cst.Module) -> c names=[cst.ImportAlias(cst.Name("update_meta"))] )]) return updated_node.with_changes(body=[import_stmt] + list(updated_node.body)) - + return updated_node @@ -148,83 +244,85 @@ def instrument_file_auto_meta_vars( ) -> Dict[str, Any]: """ Instrument a file to automatically track meta variable assignments. - + Args: file_path: Path to the Python file to instrument meta_var_names: Set of variable names to track (defaults to DEFAULT_META_VARS) dry_run: If True, don't write changes, just return what would be changed - + Returns: Dict with status, assignments_found, etc. """ if meta_var_names is None: meta_var_names = DEFAULT_META_VARS - + if not os.path.exists(file_path): return {"status": "error", "error": f"File not found: {file_path}"} - + try: with open(file_path, "r", encoding="utf-8") as f: source_code = f.read() except Exception as e: return {"status": "error", "error": f"Failed to read file: {e}"} - + try: module = cst.parse_module(source_code) except ParserSyntaxError as e: return {"status": "error", "error": f"Parse error: {e}"} except Exception as e: return {"status": "error", "error": f"Failed to parse: {e}"} - + # Apply transformer transformer = AutoMetaVarInjector(meta_var_names) wrapper = MetadataWrapper(module) transformed_module = wrapper.visit(transformer) - + if not transformer.injected: return { "status": "no_changes", "file": file_path, - "assignments_found": 0 + "assignments_found": 0, + "skipped_functions": transformer.skipped_functions, } - + if not dry_run: try: with open(file_path, "w", encoding="utf-8") as f: f.write(transformed_module.code) except Exception as e: return {"status": "error", "error": f"Failed to write file: {e}"} - + return { "status": "success", "file": file_path, "assignments_found": transformer.assignments_count, - "meta_vars_tracked": list(meta_var_names) + "meta_vars_tracked": list(meta_var_names), + "skipped_functions": transformer.skipped_functions, } def extract_files_from_callstacks(callsite_file: str) -> Set[str]: """ Extract all unique file paths from callstacks in a callsite trace JSON file. - + Args: callsite_file: Path to callsite trace JSON file (e.g., callsite_trace_combined_compressed.json) - + Returns: Set of unique file paths found in callstacks """ if not os.path.exists(callsite_file): return set() - + try: with open(callsite_file, "r", encoding="utf-8") as f: data = json.load(f) except Exception as e: print(f"[WARN] Failed to load callsite file {callsite_file}: {e}", file=sys.stderr) return set() - + file_paths = set() - + # Iterate through all entries in the callsite data for key, entry in data.items(): # Each entry has a "callstacks" field containing lists of frames @@ -241,7 +339,7 @@ def extract_files_from_callstacks(callsite_file: str) -> Set[str]: else: # Try relative to current directory or base_dir file_paths.add(file_path) # Keep original for now, will filter later - + return file_paths @@ -254,23 +352,23 @@ def instrument_all_files_auto_meta_vars( ) -> Dict[str, Any]: """ Instrument all files to automatically track meta variable assignments. - + Args: file_paths: List of file paths to instrument meta_var_names: Set of variable names to track (defaults to DEFAULT_META_VARS) log_dir: Optional directory to save log file dry_run: If True, don't write changes callsite_file: Optional path to callsite trace JSON to extract additional files from callstacks - + Returns: Summary dict with results """ if meta_var_names is None: meta_var_names = DEFAULT_META_VARS - + # Collect all files to instrument all_files = set(file_paths) - + # Extract files from callstacks if provided if callsite_file: print(f"[INFO] Extracting files from callstacks in: {callsite_file}", file=sys.stderr) @@ -280,7 +378,7 @@ def instrument_all_files_auto_meta_vars( all_files.update(callstack_files) else: print(f"[WARN] No files found in callstacks from {callsite_file}", file=sys.stderr) - + # Filter to only existing Python files python_files = [] for file_path in all_files: @@ -291,20 +389,20 @@ def instrument_all_files_auto_meta_vars( abs_path = os.path.abspath(file_path) if os.path.exists(abs_path) and abs_path.endswith('.py'): python_files.append(abs_path) - + python_files = sorted(set(python_files)) # Remove duplicates and sort - + log_entries = [] total_files = len(python_files) success_count = 0 error_count = 0 no_changes_count = 0 - + print(f"[INFO] Auto-instrumenting {total_files} files for meta variables: {sorted(meta_var_names)}", file=sys.stderr) if callsite_file: print(f"[INFO] - {len(file_paths)} from instrumented files", file=sys.stderr) print(f"[INFO] - {len(python_files) - len(file_paths)} from callstacks", file=sys.stderr) - + for file_path in python_files: result = instrument_file_auto_meta_vars(file_path, meta_var_names, dry_run=dry_run) log_entries.append({ @@ -312,7 +410,7 @@ def instrument_all_files_auto_meta_vars( **result, "timestamp": datetime.now().isoformat() }) - + if result["status"] == "success": success_count += 1 print(f"[INFO] ✅ Instrumented {file_path} ({result.get('assignments_found', 0)} assignments found)", file=sys.stderr) @@ -321,7 +419,7 @@ def instrument_all_files_auto_meta_vars( else: error_count += 1 print(f"[WARN] ⚠️ Failed to instrument {file_path}: {result.get('error', 'unknown error')}", file=sys.stderr) - + summary = { "total_files": total_files, "success": success_count, @@ -330,7 +428,7 @@ def instrument_all_files_auto_meta_vars( "meta_vars": sorted(meta_var_names), "entries": log_entries } - + if log_dir: os.makedirs(log_dir, exist_ok=True) log_path = os.path.join(log_dir, "auto_meta_var_injection_log.json") @@ -340,16 +438,16 @@ def instrument_all_files_auto_meta_vars( print(f"[INFO] Log saved to: {log_path}", file=sys.stderr) except Exception as e: print(f"[WARN] Failed to save log: {e}", file=sys.stderr) - + print(f"[INFO] Auto meta-var instrumentation complete: {success_count} success, {no_changes_count} no changes, {error_count} errors", file=sys.stderr) - + return summary def main(): """CLI for auto meta variable instrumentation.""" import argparse - + parser = argparse.ArgumentParser( description="Automatically instrument meta variable assignments" ) @@ -373,11 +471,11 @@ def main(): action="store_true", help="Don't write changes, just show what would be done" ) - + args = parser.parse_args() - + meta_vars = set(args.meta_vars) if args.meta_vars else None - + instrument_all_files_auto_meta_vars( args.files, meta_var_names=meta_vars, diff --git a/tests/test_auto_meta_var_injector.py b/tests/test_auto_meta_var_injector.py new file mode 100644 index 0000000..55fdf6c --- /dev/null +++ b/tests/test_auto_meta_var_injector.py @@ -0,0 +1,200 @@ +"""AutoMetaVarInjector must not inject update_meta into Triton-decorated functions.""" +import ast +import importlib.util +import sys +import uuid + +import pytest + +from opguard.instrumentor.auto_meta_var_injector import instrument_file_auto_meta_vars + + +def _instrument(tmp_path, source, name="mod.py"): + path = tmp_path / name + path.write_bytes(source.encode("utf-8")) + original = path.read_bytes() + return instrument_file_auto_meta_vars(str(path)), original, path.read_bytes() + + +def _injected_vars(source_bytes, func_name): + tree = ast.parse(source_bytes.decode("utf-8")) + (fn,) = [n for n in ast.walk(tree) if isinstance(n, ast.FunctionDef) and n.name == func_name] + return sorted(kw.arg for c in ast.walk(fn) if isinstance(c, ast.Call) + and getattr(c.func, "id", None) == "update_meta" for kw in c.keywords) + + +KERNEL = """\ +def kernel(x_ptr, n): + batch_idx = tl.program_id(0) + step = batch_idx * n + tl.store(x_ptr + step, batch_idx) +""" +NESTED = """\ +def kernel(x_ptr): + def helper(v): + step = v + 1 + return step + class Inner: + def method(self): + global_step = 0 + global_step += 1 + return global_step + batch_idx = tl.program_id(0) + tl.store(x_ptr + batch_idx, helper(batch_idx)) +""" + + +def case(case_id, imports, decorators, injected, body=KERNEL): + source = f"import triton.language as tl\n{imports}\n\n\n" + "".join(f"{d}\n" for d in decorators) + body + return pytest.param(source, injected, id=case_id) + + +CASES = [ + # Triton decorators, resolved through imports: never injected. + case("triton.jit", "import triton", ["@triton.jit"], False), + case("triton.jit(...)", "import triton", ["@triton.jit(do_not_specialize=['n'])"], False), + case("from-triton-import-jit", "from triton import jit", ["@jit"], False), + case("jit-as-tjit", "from triton import jit as tjit", ["@tjit"], False), + case("triton-as-tr", "import triton as tr", ["@tr.jit"], False), + case("triton-as-tr-call", "import triton as tr", ["@tr.jit()"], False), + case("triton-as-t", "import triton as t", ["@t.jit"], False), + case("autotune-on-jit", "import triton", + ['@triton.autotune(configs=[triton.Config({"BLOCK": 64})], key=["n"])', "@triton.jit"], False), + case("heuristics-on-jit", "import triton", + ['@triton.heuristics({"EVEN": lambda args: args["n"] % 2 == 0})', "@triton.jit"], False), + case("libentry-above-jit", "import triton\nfrom mylib import libentry", ["@libentry()", "@triton.jit"], False), + case("libentry-below-jit", "import triton\nfrom mylib import libentry", ["@triton.jit", "@libentry"], False), + case("triton.runtime-jit", "from triton.runtime import jit", ["@jit"], False), + case("autotuner-autotune", + "from triton import Config\nfrom triton.runtime import jit\nfrom triton.runtime.autotuner import autotune", + ['@autotune(configs=[Config({"BLOCK": 32})], key=[])', "@jit"], False), + case("autotuner-heuristics", "from triton.runtime import jit\nfrom triton.runtime.autotuner import heuristics", + ['@heuristics({"B": lambda args: 16})', "@jit"], False), + case("import-triton.runtime", "import triton.runtime", ["@triton.runtime.jit"], False), + case("nested-def-and-class", "import triton", ["@triton.jit"], False, body=NESTED), + case("star-jit", "from triton import *", ["@jit"], False), + case("star-autotune-on-jit", "from triton import *", ["@autotune(configs=[], key=[])", "@jit"], False), + # Same spelling, but not Triton after import resolution: still injected. + case("local-def-jit", "def jit(f):\n return f", ["@jit"], True), + case("mylib-jit", "from mylib import jit", ["@jit"], True), + case("segment-triton_utils", "from vllm import triton_utils", ["@triton_utils.jit"], True), + case("segment-_triton", "from mypkg._triton import jit", ["@jit"], True), + case("segment-triton_heuristics", "from mypkg.triton_heuristics import autotune", ["@autotune()"], True), +] + + +@pytest.mark.parametrize("source, injected", CASES) +def test_decorator_resolution(tmp_path, source, injected): + result, original, after = _instrument(tmp_path, source) + if injected: + assert (result["status"], result.get("skipped_functions", 0)) == ("success", 0), result + assert _injected_vars(after, "kernel") == ["batch_idx", "step"] + else: + assert (result["status"], result["skipped_functions"]) == ("no_changes", 1), result + assert after == original + + +MIXED = "import functools\nimport torch\nimport triton\nimport triton.language as tl\n\n\n@triton.jit\n" + KERNEL + """ + +def train(n): + global_step = 0 + for _ in range(n): + step = 1 + global_step += 1 + return global_step + +@functools.lru_cache(maxsize=None) +def cached(n): + step = n + return step + +class Trainer: + @torch.no_grad() + def run(self): + batch_idx = 3 + return batch_idx +""" + + +def test_regular_functions_in_same_file_still_injected(tmp_path): + result, _, after = _instrument(tmp_path, MIXED) + assert (result["status"], result["assignments_found"], result["skipped_functions"]) == ("success", 5, 1) + assert _injected_vars(after, "kernel") == [] + assert _injected_vars(after, "train") == ["global_step", "global_step", "step"] + assert _injected_vars(after, "cached") == ["step"] + assert _injected_vars(after, "run") == ["batch_idx"] + assert after.startswith(b"from opguard.tracer.meta_vars import update_meta\n") + + +def test_output_is_deterministic(tmp_path): + assert _instrument(tmp_path, MIXED, "a.py")[2] == _instrument(tmp_path, MIXED, "b.py")[2] + + +def test_triton_only_file_is_byte_identical(tmp_path): + source = ("# -*- coding: utf-8 -*-\r\nimport triton\r\nimport triton.language as tl\r\n\r\n" + "@triton.jit\r\ndef kernel(x_ptr): # trailing comment\r\n batch_idx = tl.program_id(0)\r\n" + " micro_batch_idx = batch_idx; model_chunk_id = 0\r\n tl.store(x_ptr + batch_idx, 1)\r\n") + result, original, after = _instrument(tmp_path, source) + assert (result["status"], result["assignments_found"]) == ("no_changes", 0), result + assert after == original + + +def test_vllm_reexported_triton_not_injected(tmp_path): + source = ("from vllm.triton_utils import tl, triton\nfrom vllm.triton_utils import triton as t\n\n\n" + + "@triton.jit\n" + KERNEL.replace("kernel", "k1") + "\n\n" + + "@triton.jit(do_not_specialize=['n'])\n" + KERNEL.replace("kernel", "k2") + "\n\n" + + "@t.jit\n" + KERNEL.replace("kernel", "k3")) + result, original, after = _instrument(tmp_path, source) + assert (result["status"], result["skipped_functions"]) == ("no_changes", 3), result + assert after == original + + +def test_import_after_kernel_definition(tmp_path): + source = ("@tr.jit\n" + KERNEL + "\n\n@jit\n" + KERNEL.replace("kernel", "kernel_b") + + "\n\ndef _late_imports():\n from triton import jit\n\n\n" + + "import triton as tr\nimport triton.language as tl\n") + result, original, after = _instrument(tmp_path, source) + assert (result["status"], result["skipped_functions"]) == ("no_changes", 2), result + assert after == original + + +SMOKE = """\ +import torch +import triton +import triton.language as tl + +@triton.jit +def add_rows_kernel(x_ptr, y_ptr, out_ptr, n_cols, BLOCK: tl.constexpr): + batch_idx = tl.program_id(0) + offs = batch_idx * n_cols + tl.arange(0, BLOCK) + mask = tl.arange(0, BLOCK) < n_cols + x, y = tl.load(x_ptr + offs, mask=mask), tl.load(y_ptr + offs, mask=mask) + tl.store(out_ptr + offs, x + 2.0 * y, mask=mask) + +def launch(x, y): + step = 0 + out = torch.empty_like(x) + add_rows_kernel[(x.shape[0],)](x, y, out, x.shape[1], BLOCK=triton.next_power_of_2(x.shape[1])) + step += 1 + return out +""" + + +def test_gpu_smoke_instrumented_triton_kernel_runs(tmp_path): + torch = pytest.importorskip("torch") + pytest.importorskip("triton") + if not torch.cuda.is_available(): + pytest.skip("CUDA is not available") + result, _, _ = _instrument(tmp_path, SMOKE, "smoke_kernels.py") + assert result["status"] == "success", result # host-side `step` is still instrumented + name = f"opguard_triton_smoke_{uuid.uuid4().hex}" + spec = importlib.util.spec_from_file_location(name, str(tmp_path / "smoke_kernels.py")) + module = sys.modules[name] = importlib.util.module_from_spec(spec) + try: + spec.loader.exec_module(module) + x, y = torch.randn(7, 45, device="cuda"), torch.randn(7, 45, device="cuda") + out = module.launch(x, y) + torch.cuda.synchronize() + torch.testing.assert_close(out, x + 2.0 * y) + finally: + sys.modules.pop(name, None)