WS5-1

codetracer-python-recorder/codetracer_python_recorder/auto_start.py: 
codetracer-python-recorder/codetracer_python_recorder/cli.py: 
codetracer-python-recorder/codetracer_python_recorder/session.py: 
codetracer-python-recorder/src/session/bootstrap.rs: 
codetracer-python-recorder/src/session.rs: 
codetracer-python-recorder/tests/python/test_cli_integration.py: 
codetracer-python-recorder/tests/python/unit/test_backend_exceptions.py: 
codetracer-python-recorder/tests/python/unit/test_cli.py: 
codetracer-python-recorder/tests/python/unit/test_session_helpers.py: 
design-docs/configurable-trace-filters-implementation-plan.status.md: 

Signed-off-by: Tzanko Matev <[email protected]>

Author: tzanko-matev

codetracer-python-recorder/codetracer_python_recorder/auto_start.py

@@ -9,6 +9,7 @@
 
 ENV_TRACE_PATH = "CODETRACER_TRACE"
 ENV_TRACE_FORMAT = "CODETRACER_FORMAT"
+ENV_TRACE_FILTER = "CODETRACER_TRACE_FILTER"
 
 log = logging.getLogger(__name__)
 
@@ -18,6 +19,7 @@ def auto_start_from_env() -> None:
     path = os.getenv(ENV_TRACE_PATH)
     if not path:
         return
+    filter_spec = os.getenv(ENV_TRACE_FILTER)
 
     # Delay import to avoid boot-time circular dependencies.
     from . import session
@@ -31,13 +33,15 @@ def auto_start_from_env() -> None:
 
     fmt = os.getenv(ENV_TRACE_FORMAT, DEFAULT_FORMAT)
     log.debug(
-        "codetracer auto-start triggered", extra={"trace_path": path, "format": fmt}
+        "codetracer auto-start triggered",
+        extra={"trace_path": path, "format": fmt, "trace_filter": filter_spec},
     )
-    session.start(path, format=fmt)
+    session.start(path, format=fmt, trace_filter=filter_spec)
 
 
 __all__: Iterable[str] = (
     "ENV_TRACE_FORMAT",
     "ENV_TRACE_PATH",
+    "ENV_TRACE_FILTER",
     "auto_start_from_env",
 )

codetracer-python-recorder/codetracer_python_recorder/cli.py

@@ -23,6 +23,7 @@ class RecorderCLIConfig:
     activation_path: Path
     script: Path
     script_args: list[str]
+    trace_filter: tuple[str, ...]
     policy_overrides: dict[str, object]
 
 
@@ -65,6 +66,14 @@ def _parse_args(argv: Sequence[str]) -> RecorderCLIConfig:
             "interpreter enters this file. Defaults to the target script."
         ),
     )
+    parser.add_argument(
+        "--trace-filter",
+        action="append",
+        help=(
+            "Path to a trace filter file. Provide multiple times to chain filters; "
+            "specify multiple paths within a single argument using '//' separators."
+        ),
+    )
     parser.add_argument(
         "--on-recorder-error",
         choices=["abort", "disable"],
@@ -174,6 +183,7 @@ def _parse_args(argv: Sequence[str]) -> RecorderCLIConfig:
         activation_path=activation_path,
         script=script_path,
         script_args=script_args,
+        trace_filter=tuple(known.trace_filter or ()),
         policy_overrides=policy,
     )
 
@@ -238,6 +248,7 @@ def main(argv: Iterable[str] | None = None) -> int:
     trace_dir = config.trace_dir
     script_path = config.script
     script_args = config.script_args
+    filter_specs = list(config.trace_filter)
     policy_overrides = config.policy_overrides if config.policy_overrides else None
 
     old_argv = sys.argv
@@ -248,6 +259,7 @@ def main(argv: Iterable[str] | None = None) -> int:
             trace_dir,
             format=config.format,
             start_on_enter=config.activation_path,
+            trace_filter=filter_specs or None,
             policy=policy_overrides,
         )
     except Exception as exc:

codetracer-python-recorder/codetracer_python_recorder/session.py

@@ -7,6 +7,7 @@
 
 import contextlib
 import os
+from collections.abc import Sequence
 from pathlib import Path
 from typing import Iterator, Mapping, Optional
 
@@ -58,6 +59,7 @@ def start(
     *,
     format: str = DEFAULT_FORMAT,
     start_on_enter: str | Path | None = None,
+    trace_filter: str | os.PathLike[str] | Sequence[str | os.PathLike[str]] | None = None,
     policy: Mapping[str, object] | None = None,
     apply_env_policy: bool = True,
 ) -> TraceSession:
@@ -72,6 +74,10 @@ def start(
     start_on_enter:
         Optional path that delays trace activation until the interpreter enters
         the referenced file.
+    trace_filter:
+        Optional filter specification. Accepts a path-like object, an iterable
+        of path-like objects, or a string containing ``//``-separated paths.
+        Paths are expanded to absolute locations and must exist.
     policy:
         Optional mapping of runtime policy overrides forwarded to
         :func:`configure_policy` before tracing begins. Keys match the policy
@@ -102,13 +108,14 @@ def start(
     trace_path = _validate_trace_path(Path(path))
     normalized_format = _coerce_format(format)
     activation_path = _normalize_activation_path(start_on_enter)
+    filter_chain = _normalize_trace_filter(trace_filter)
 
     if apply_env_policy:
         _configure_policy_from_env()
     if policy:
         _configure_policy(**_coerce_policy_kwargs(policy))
 
-    _start_backend(str(trace_path), normalized_format, activation_path)
+    _start_backend(str(trace_path), normalized_format, activation_path, filter_chain)
     session = TraceSession(path=trace_path, format=normalized_format)
     _active_session = session
     return session
@@ -139,13 +146,15 @@ def trace(
     path: str | Path,
     *,
     format: str = DEFAULT_FORMAT,
+    trace_filter: str | os.PathLike[str] | Sequence[str | os.PathLike[str]] | None = None,
     policy: Mapping[str, object] | None = None,
     apply_env_policy: bool = True,
 ) -> Iterator[TraceSession]:
     """Context manager helper for scoped tracing."""
     session = start(
         path,
         format=format,
+        trace_filter=trace_filter,
         policy=policy,
         apply_env_policy=apply_env_policy,
     )
@@ -178,6 +187,58 @@ def _normalize_activation_path(value: str | Path | None) -> str | None:
     return str(Path(value).expanduser())
 
 
+def _normalize_trace_filter(
+    value: str | os.PathLike[str] | Sequence[str | os.PathLike[str]] | None,
+) -> list[str] | None:
+    if value is None:
+        return None
+
+    segments = _extract_filter_segments(value)
+    if not segments:
+        raise ValueError("trace_filter must resolve to at least one path")
+
+    resolved: list[str] = []
+    for segment in segments:
+        target = _resolve_trace_filter_path(segment)
+        resolved.append(str(target))
+    return resolved
+
+
+def _extract_filter_segments(
+    value: str | os.PathLike[str] | Sequence[str | os.PathLike[str]],
+) -> list[str]:
+    if isinstance(value, (str, os.PathLike)):
+        return _split_filter_spec(os.fspath(value))
+
+    if isinstance(value, Sequence):
+        segments: list[str] = []
+        for item in value:
+            if not isinstance(item, (str, os.PathLike)):
+                raise TypeError(
+                    "trace_filter sequence entries must be str or os.PathLike"
+                )
+            segments.extend(_split_filter_spec(os.fspath(item)))
+        return segments
+
+    raise TypeError("trace_filter must be a path, iterable of paths, or None")
+
+
+def _split_filter_spec(value: str) -> list[str]:
+    parts = [segment.strip() for segment in value.split("//")]
+    return [segment for segment in parts if segment]
+
+
+def _resolve_trace_filter_path(raw: str) -> Path:
+    candidate = Path(raw).expanduser()
+    if not candidate.exists():
+        raise FileNotFoundError(f"trace filter '{candidate}' does not exist")
+
+    resolved = candidate.resolve()
+    if not resolved.is_file():
+        raise ValueError(f"trace filter '{resolved}' is not a file")
+    return resolved
+
+
 def _coerce_policy_kwargs(policy: Mapping[str, object]) -> dict[str, object]:
     normalized: dict[str, object] = {}
     for key, raw_value in policy.items():

codetracer-python-recorder/src/session.rs

@@ -19,8 +19,13 @@ use bootstrap::TraceSessionBootstrap;
 static ACTIVE: AtomicBool = AtomicBool::new(false);
 
 /// Start tracing using sys.monitoring and runtime_tracing writer.
-#[pyfunction]
-pub fn start_tracing(path: &str, format: &str, activation_path: Option<&str>) -> PyResult<()> {
+#[pyfunction(signature = (path, format, activation_path=None, trace_filter=None))]
+pub fn start_tracing(
+    path: &str,
+    format: &str,
+    activation_path: Option<&str>,
+    trace_filter: Option<Vec<String>>,
+) -> PyResult<()> {
     ffi::wrap_pyfunction("start_tracing", || {
         // Ensure logging is ready before any tracer logs might be emitted.
         // Default our crate to warnings-only so tests stay quiet unless explicitly enabled.
@@ -33,13 +38,16 @@ pub fn start_tracing(path: &str, format: &str, activation_path: Option<&str>) ->
         }
 
         let activation_path = activation_path.map(PathBuf::from);
+        let filter_paths: Option<Vec<PathBuf>> =
+            trace_filter.map(|items| items.into_iter().map(PathBuf::from).collect());
 
         Python::with_gil(|py| {
             let bootstrap = TraceSessionBootstrap::prepare(
                 py,
                 Path::new(path),
                 format,
                 activation_path.as_deref(),
+                filter_paths.as_ref().map(|paths| paths.as_slice()),
             )
             .map_err(ffi::map_recorder_error)?;
 

codetracer-python-recorder/src/session/bootstrap.rs

@@ -54,14 +54,15 @@ impl TraceSessionBootstrap {
         trace_directory: &Path,
         format: &str,
         activation_path: Option<&Path>,
+        explicit_trace_filters: Option<&[PathBuf]>,
     ) -> Result<Self> {
         ensure_trace_directory(trace_directory)?;
         let format = resolve_trace_format(format)?;
         let metadata = collect_program_metadata(py).map_err(|err| {
             enverr!(ErrorCode::Io, "failed to collect program metadata")
                 .with_context("details", err.to_string())
         })?;
-        let trace_filter = load_default_trace_filter(&metadata.program)?;
+        let trace_filter = load_trace_filter(explicit_trace_filters, &metadata.program)?;
         Ok(Self {
             trace_directory: trace_directory.to_path_buf(),
             format,
@@ -158,14 +159,35 @@ pub fn collect_program_metadata(py: Python<'_>) -> PyResult<ProgramMetadata> {
     Ok(ProgramMetadata { program, args })
 }
 
-fn load_default_trace_filter(program: &str) -> Result<Option<Arc<TraceFilterEngine>>> {
+fn load_trace_filter(
+    explicit: Option<&[PathBuf]>,
+    program: &str,
+) -> Result<Option<Arc<TraceFilterEngine>>> {
+    let mut chain: Vec<PathBuf> = Vec::new();
+
+    if let Some(default) = discover_default_trace_filter(program)? {
+        chain.push(default);
+    }
+
+    if let Some(paths) = explicit {
+        chain.extend(paths.iter().cloned());
+    }
+
+    if chain.is_empty() {
+        return Ok(None);
+    }
+
+    let config = TraceFilterConfig::from_paths(&chain)?;
+    Ok(Some(Arc::new(TraceFilterEngine::new(config))))
+}
+
+fn discover_default_trace_filter(program: &str) -> Result<Option<PathBuf>> {
     let start_dir = resolve_program_directory(program)?;
     let mut current: Option<&Path> = Some(start_dir.as_path());
     while let Some(dir) = current {
         let candidate = dir.join(TRACE_FILTER_DIR).join(TRACE_FILTER_FILE);
         if matches!(fs::metadata(&candidate), Ok(metadata) if metadata.is_file()) {
-            let config = TraceFilterConfig::from_paths(&[candidate.clone()])?;
-            return Ok(Some(Arc::new(TraceFilterEngine::new(config))));
+            return Ok(Some(candidate));
         }
         current = dir.parent();
     }
@@ -308,6 +330,7 @@ mod tests {
                 trace_dir.as_path(),
                 "json",
                 Some(activation.as_path()),
+                None,
             );
             sys.setattr("argv", original.bind(py))
                 .expect("restore argv");
@@ -337,7 +360,7 @@ mod tests {
             sys.setattr("argv", argv).expect("set argv");
 
             let result =
-                TraceSessionBootstrap::prepare(py, trace_dir.as_path(), "json", None);
+                TraceSessionBootstrap::prepare(py, trace_dir.as_path(), "json", None, None);
             sys.setattr("argv", original.bind(py))
                 .expect("restore argv");
 
@@ -386,7 +409,7 @@ mod tests {
             sys.setattr("argv", argv).expect("set argv");
 
             let result =
-                TraceSessionBootstrap::prepare(py, trace_dir.as_path(), "json", None);
+                TraceSessionBootstrap::prepare(py, trace_dir.as_path(), "json", None, None);
             sys.setattr("argv", original.bind(py))
                 .expect("restore argv");
 
@@ -397,4 +420,83 @@ mod tests {
             assert_eq!(summary.entries[0].path, filter_path);
         });
     }
+
+    #[test]
+    fn prepare_bootstrap_merges_explicit_trace_filters() {
+        Python::with_gil(|py| {
+            let project = tempdir().expect("project");
+            let project_root = project.path();
+            let trace_dir = project_root.join("out");
+
+            let app_dir = project_root.join("src");
+            std::fs::create_dir_all(&app_dir).expect("create src dir");
+            let script_path = app_dir.join("main.py");
+            std::fs::write(&script_path, "print('run')\n").expect("write script");
+
+            let filters_dir = project_root.join(TRACE_FILTER_DIR);
+            std::fs::create_dir(&filters_dir).expect("create filter dir");
+            let default_filter_path = filters_dir.join(TRACE_FILTER_FILE);
+            std::fs::write(
+                &default_filter_path,
+                r#"
+                [meta]
+                name = "default"
+                version = 1
+
+                [scope]
+                default_exec = "trace"
+                default_value_action = "allow"
+
+                [[scope.rules]]
+                selector = "pkg:src"
+                exec = "trace"
+                value_default = "allow"
+                "#,
+            )
+            .expect("write default filter");
+
+            let override_filter_path = project_root.join("override-filter.toml");
+            std::fs::write(
+                &override_filter_path,
+                r#"
+                [meta]
+                name = "override"
+                version = 1
+
+                [scope]
+                default_exec = "trace"
+                default_value_action = "allow"
+
+                [[scope.rules]]
+                selector = "pkg:src.special"
+                exec = "skip"
+                value_default = "deny"
+                "#,
+            )
+            .expect("write override filter");
+
+            let sys = py.import("sys").expect("import sys");
+            let original = sys.getattr("argv").expect("argv").unbind();
+            let argv = PyList::new(py, [script_path.to_str().expect("utf8 path")]).expect("argv");
+            sys.setattr("argv", argv).expect("set argv");
+
+            let explicit = vec![override_filter_path.clone()];
+            let result = TraceSessionBootstrap::prepare(
+                py,
+                trace_dir.as_path(),
+                "json",
+                None,
+                Some(explicit.as_slice()),
+            );
+            sys.setattr("argv", original.bind(py))
+                .expect("restore argv");
+
+            let bootstrap = result.expect("bootstrap");
+            let engine = bootstrap.trace_filter().expect("filter engine");
+            let summary = engine.summary();
+            assert_eq!(summary.entries.len(), 2);
+            assert_eq!(summary.entries[0].path, default_filter_path);
+            assert_eq!(summary.entries[1].path, override_filter_path);
+        });
+    }
 }