Stage 5

Author: tzanko-matev

codetracer-python-recorder/CHANGELOG.md

@@ -9,7 +9,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 - Balanced call-stack handling for generators, coroutines, and unwinding frames by subscribing to `PY_YIELD`, `PY_UNWIND`, `PY_RESUME`, and `PY_THROW`, mapping resume/throw events to `TraceWriter::register_call`, yield/unwind to `register_return`, and capturing `PY_THROW` arguments as `exception` using the existing value encoder. Added Python + Rust integration tests that drive `.send()`/`.throw()` on coroutines and generators to guarantee the trace stays balanced and that exception payloads are recorded.
 
 ### Changed
-- Module-level call events now prefer the frame's `__name__`, fall back to filter hints, `sys.path`, and package markers, and no longer depend on the legacy resolver/cache. This keeps `<__main__>` for direct scripts while package imports continue to emit `<pkg.mod>`. Updated Rust + Python tests and documentation to describe the new semantics and opt-in flag.
+- Module-level call events now prefer the frame's `__name__`, fall back to filter hints, `sys.path`, and package markers, and no longer depend on the legacy resolver/cache. The globals-derived naming flag now defaults to enabled so direct scripts record `<__main__>` while package imports emit `<pkg.mod>`, with CLI and environment overrides available for the legacy resolver.
 
 ## [0.2.0] - 2025-10-17
 ### Added

codetracer-python-recorder/README.md

@@ -85,6 +85,7 @@ action = "drop"
 ## Trace naming semantics
 
 - Module-level activations no longer appear as the ambiguous `<module>` label. When the recorder sees `co_qualname == "<module>"`, it first reuses the frame's `__name__`, then falls back to trace-filter hints, `sys.path` roots, and package markers so scripts report `<__main__>` while real modules keep their dotted names (e.g., `<my_pkg.mod>` or `<boto3.session>`).
+- The globals-derived naming flow ships enabled by default; disable it temporarily with `--no-module-name-from-globals`, `codetracer.configure_policy(module_name_from_globals=False)`, or `CODETRACER_MODULE_NAME_FROM_GLOBALS=0` if you need to compare against the legacy resolver.
 - The angle-bracket convention remains for module entries so downstream tooling can distinguish top-level activations at a glance.
 - Traces will still emit `<module>` for synthetic filenames (`<stdin>`, `<string>`), frozen/importlib bootstrap frames, or exotic loaders that omit filenames entirely. This preserves previous behaviour when no reliable name exists.
 

codetracer-python-recorder/codetracer_python_recorder/cli.py

@@ -122,10 +122,11 @@ def _parse_args(argv: Sequence[str]) -> RecorderCLIConfig:
     )
     parser.add_argument(
         "--module-name-from-globals",
-        action="store_true",
+        action=argparse.BooleanOptionalAction,
+        default=None,
         help=(
-            "Derive module names from the Python frame's __name__ attribute. "
-            "Intended for early opt-in while the feature flag is experimental."
+            "Derive module names from the Python frame's __name__ attribute (default: enabled). "
+            "Use '--no-module-name-from-globals' to fall back to the legacy resolver."
         ),
     )
 
@@ -189,8 +190,8 @@ def _parse_args(argv: Sequence[str]) -> RecorderCLIConfig:
                 policy["io_capture_fd_fallback"] = True
             case other:  # pragma: no cover - argparse choices block this
                 parser.error(f"unsupported io-capture mode '{other}'")
-    if known.module_name_from_globals:
-        policy["module_name_from_globals"] = True
+    if known.module_name_from_globals is not None:
+        policy["module_name_from_globals"] = known.module_name_from_globals
 
     return RecorderCLIConfig(
         trace_dir=trace_dir,

codetracer-python-recorder/resources/trace_filters/builtin_default.toml

@@ -34,7 +34,7 @@ exec = "skip"
 reason = "Skip builtins module instrumentation"
 
 [[scope.rules]]
-selector = 'pkg:glob:*_distutils_hack*'
+selector = 'pkg:literal:_distutils_hack'
 exec = "skip"
 reason = "Skip setuptools shim module"
 

codetracer-python-recorder/src/policy.rs

@@ -42,7 +42,7 @@ mod tests {
         assert!(snap.log_file.is_none());
         assert!(snap.io_capture.line_proxies);
         assert!(!snap.io_capture.fd_fallback);
-        assert!(!snap.module_name_from_globals);
+        assert!(snap.module_name_from_globals);
     }
 
     #[test]

codetracer-python-recorder/src/policy/env.rs

@@ -165,6 +165,17 @@ mod tests {
         assert!(snap.module_name_from_globals);
     }
 
+    #[test]
+    fn configure_policy_from_env_disables_module_name_from_globals() {
+        let _guard = EnvGuard;
+        reset_policy_for_tests();
+        std::env::set_var(ENV_MODULE_NAME_FROM_GLOBALS, "false");
+
+        configure_policy_from_env().expect("configure from env");
+        let snap = policy_snapshot();
+        assert!(!snap.module_name_from_globals);
+    }
+
     #[test]
     fn parse_capture_io_handles_aliases() {
         assert_eq!(parse_capture_io("proxies+fd").unwrap(), (true, true));

codetracer-python-recorder/src/policy/model.rs

@@ -84,7 +84,7 @@ impl Default for RecorderPolicy {
             log_file: None,
             json_errors: false,
             io_capture: IoCapturePolicy::default(),
-            module_name_from_globals: false,
+            module_name_from_globals: true,
         }
     }
 }

codetracer-python-recorder/tests/python/test_monitoring_events.py

@@ -227,15 +227,13 @@ def test_module_name_follows_globals_policy(tmp_path: Path) -> None:
     script.write_text("VALUE = 1\n", encoding="utf-8")
 
     out_dir = ensure_trace_dir(tmp_path)
-    codetracer.configure_policy(module_name_from_globals=True)
-
     session = codetracer.start(out_dir, format=codetracer.TRACE_JSON, start_on_enter=script)
     try:
         runpy.run_path(str(script), run_name="__main__")
     finally:
         codetracer.flush()
         codetracer.stop()
-        codetracer.configure_policy(module_name_from_globals=False)
+        codetracer.configure_policy(module_name_from_globals=True)
 
     parsed = _parse_trace(out_dir)
     names = [f["name"] for f in parsed.functions]

codetracer-python-recorder/tests/python/unit/test_cli.py

@@ -172,3 +172,19 @@ def test_parse_args_enables_module_name_from_globals(tmp_path: Path) -> None:
     assert config.policy_overrides == {
         "module_name_from_globals": True,
     }
+
+
+def test_parse_args_disables_module_name_from_globals(tmp_path: Path) -> None:
+    script = tmp_path / "entry.py"
+    _write_script(script)
+
+    config = _parse_args(
+        [
+            "--no-module-name-from-globals",
+            str(script),
+        ]
+    )
+
+    assert config.policy_overrides == {
+        "module_name_from_globals": False,
+    }

codetracer-python-recorder/tests/python/unit/test_policy_configuration.py

@@ -18,7 +18,7 @@ def reset_policy() -> None:
         log_level="",
         log_file="",
         json_errors=False,
-        module_name_from_globals=False,
+        module_name_from_globals=True,
     )
     yield
     codetracer.configure_policy(
@@ -28,7 +28,7 @@ def reset_policy() -> None:
         log_level="",
         log_file="",
         json_errors=False,
-        module_name_from_globals=False,
+        module_name_from_globals=True,
     )