WS6-2

Justfile: 
README.md: 
codetracer-python-recorder/README.md: 
codetracer-python-recorder/tests/python/perf/__init__.py: 
codetracer-python-recorder/tests/python/perf/test_trace_filter_perf.py: 
design-docs/configurable-trace-filters-implementation-plan.status.md: 
docs/onboarding/trace-filters.md: 

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

Author: tzanko-matev

Justfile

@@ -51,7 +51,12 @@ bench:
         echo "Python interpreter not found. Run 'just venv <version>' first."; \
         exit 1; \
     fi; \
-    PYO3_PYTHON="$PYTHON_BIN" uv run cargo bench --manifest-path codetracer-python-recorder/Cargo.toml --no-default-features --bench trace_filter
+    PERF_DIR="$ROOT/codetracer-python-recorder/target/perf"; \
+    mkdir -p "$PERF_DIR"; \
+    PYO3_PYTHON="$PYTHON_BIN" uv run cargo bench --manifest-path codetracer-python-recorder/Cargo.toml --no-default-features --bench trace_filter && \
+    CODETRACER_TRACE_FILTER_PERF=1 \
+    CODETRACER_TRACE_FILTER_PERF_OUTPUT="$PERF_DIR/trace_filter_py.json" \
+    uv run --group dev --group test pytest codetracer-python-recorder/tests/python/perf/test_trace_filter_perf.py -q
 
 py-test:
     uv run --group dev --group test pytest codetracer-python-recorder/tests/python codetracer-pure-python-recorder

README.md

@@ -137,6 +137,7 @@ Basic workflow:
 - Run the full split test suite (Rust nextest + Python pytest): `just test`
 - Run only Rust integration/unit tests: `just cargo-test`
 - Run only Python tests (including the pure-Python recorder to guard regressions): `just py-test`
+- Exercise the trace-filter benchmarks (Rust Criterion + Python smoke, JSON output under `codetracer-python-recorder/target/perf`): `just bench`
 - Collect coverage artefacts locally (LCOV + Cobertura/JSON): `just coverage`
 
 The CI workflow mirrors these commands. Pull requests get an automated comment with the latest Rust/Python coverage tables and downloadable artefacts (`lcov.info`, `coverage.xml`, `coverage.json`).

codetracer-python-recorder/README.md

@@ -51,6 +51,33 @@ All additional arguments are forwarded to the target script unchanged. The CLI
 reuses whichever interpreter launches it so wrappers such as `uv run`, `pipx`,
 or activated virtual environments behave identically to `python script.py`.
 
+## Trace filter configuration
+- Filter files are TOML with `[meta]`, `[scope]`, and `[[scope.rules]]` tables. Rules evaluate in declaration order and can tweak both execution (`exec`) and value decisions (`value_default`).
+- Supported selector domains: `pkg`, `file`, `obj` for scopes; `local`, `global`, `arg`, `ret`, `attr` for value policies. Match types default to `glob` and also accept `regex` or `literal` (e.g. `local:regex:^(metric|masked)_\w+$`).
+- Default discovery: `.codetracer/trace-filter.toml` next to the traced script. Chain additional files via CLI (`--trace-filter path_a --trace-filter path_b`), environment variable (`CODETRACER_TRACE_FILTER=path_a//path_b`), or Python helpers (`trace(..., trace_filter=[path_a, path_b])`). Later entries override earlier ones when selectors overlap.
+- Runtime metadata captures the active chain under `trace_metadata.json -> trace_filter`, including per-kind redaction counters. See `docs/onboarding/trace-filters.md` for the full DSL reference and examples.
+
+Example snippet:
+```toml
+[meta]
+name = "local-redaction"
+version = 1
+
+[scope]
+default_exec = "trace"
+default_value_action = "allow"
+
+[[scope.rules]]
+selector = "pkg:my_app.services.*"
+value_default = "deny"
+[[scope.rules.value_patterns]]
+selector = "local:glob:public_*"
+action = "allow"
+[[scope.rules.value_patterns]]
+selector = 'local:regex:^(metric|masked)_\w+$'
+action = "allow"
+```
+
 ## Packaging expectations
 
 Desktop installers add the wheel to `PYTHONPATH` before invoking the user’s
@@ -61,3 +88,8 @@ with the interpreter you want to trace.
 The CLI writes recorder metadata into `trace_metadata.json` describing the wheel
 version, target script, and diff preference so downstream tooling can make
 decisions without re-running the trace.
+
+## Development benchmarks
+- Rust microbench: `cargo bench --bench trace_filter --no-default-features` exercises baseline, glob-heavy, and regex-heavy selector chains.
+- Python smoke benchmark: `pytest codetracer-python-recorder/tests/python/perf/test_trace_filter_perf.py -q` when the environment variable `CODETRACER_TRACE_FILTER_PERF=1` is set.
+- Run both together with `just bench`. The helper seeds a virtualenv, runs Criterion, then executes the Python smoke test while writing `target/perf/trace_filter_py.json` (per-scenario durations and redaction statistics).

codetracer-python-recorder/tests/python/perf/__init__.py

@@ -0,0 +1 @@
+"""Performance-oriented smoke tests for the Python surface."""