Trace filters (#53)

# Configurable Trace Filters

## Overview
- Implements user story **US0028 – Configurable Python trace filters**
(see `design-docs/US0028 - Configurable Python trace filters.md`).
- Trace filters let callers decide which modules execute under tracing
and which values are redacted before the recorder writes events.
- Each filter file is TOML. Files can be chained to layer product
defaults with per-project overrides. The runtime records the active
filter summary in `trace_metadata.json`.
- The recorder always prepends a built-in **builtin-default** filter
that (a) skips CPython standard-library frames (including
`asyncio`/concurrency internals) while still allowing third-party
packages under `site-packages` (except helper shims like
`_virtualenv.py`) and (b) redacts common sensitive identifiers
(passwords, tokens, API keys, etc.) across
locals/globals/args/returns/attributes. Project filters and explicit
overrides append after this baseline and can relax rules where needed.

## Filter Files
- Filters live alongside the project (default:
`.codetracer/trace-filter.toml`). Any other file can be supplied via
CLI, environment variable, or Python API.
- Required sections:
  - `[meta]` – `name`, `version` (integer), optional `description`.
- `[scope]` – `default_exec` (`"trace"`/`"skip"`),
`default_value_action` (`"allow"`/`"redact"`/`"drop"`).
- Rules appear under `[[scope.rules]]` in declaration order. Each rule
has:
- `selector` – matches a package, file, or object (see selector syntax).
  - Optional `exec` override (`"trace"`/`"skip"`).
  - Optional `value_default` override (`"allow"`/`"redact"`/`"drop"`).
  - Optional `reason` string stored in telemetry.
- `[[scope.rules.value_patterns]]` entries that refine value capture by
selector.
- Example:
  ```toml
  [meta]
  name = "example-filter"
  version = 1
  description = "Protect secrets while allowing metrics."

  [scope]
  default_exec = "trace"
  default_value_action = "allow"

  [[scope.rules]]
  selector = "pkg:my_app.services.*"
  value_default = "redact"
  [[scope.rules.value_patterns]]
  selector = "local:glob:public_*"
  action = "allow"
  [[scope.rules.value_patterns]]
  selector = 'local:regex:^(metric|masked)_\w+$'
  action = "allow"
  [[scope.rules.value_patterns]]
  selector = "local:glob:secret_*"
  action = "redact"
  [[scope.rules.value_patterns]]
  selector = "arg:literal:debug_payload"
  action = "drop"
  ```

## Selector Syntax
- Domains (`selector` prefix before the first colon):
  - `pkg` – fully-qualified module name (`package.module`).
- `file` – source path relative to the project root (POSIX separators).
  - `obj` – module-qualified object (`package.module.func`).
  - `local`, `global`, `arg`, `ret`, `attr` – value-level selectors.
- Match types (second segment in `kind:match:pattern`):
- `glob` *(default)* – wildcard matching with `/` treated as a
separator.
- `regex` – Rust/RE2-style regular expressions; invalid patterns log a
single warning and fall back to configuration errors.
  - `literal` – exact string match.
- Value selectors inherit the match type when omitted (e.g.,
`local:token_*` uses glob). Declare the match type explicitly when
combining separators or anchors.

## Loading and Chaining Filters
- Default discovery: `RuntimeTracer` searches for
`.codetracer/trace-filter.toml` near the target script.
- CLI: `--trace-filter path/to/filter.toml`. Provide multiple times or
use `::` within one argument to append more files.
- Environment:
`CODETRACER_TRACE_FILTER=filters/prod.toml::filters/hotfix.toml`.
Respected by the auto-start hook and the CLI.
- Python API: `trace(..., trace_filter=[path1, path2])` or pass a
`::`-delimited string. Paths are expanded to absolute locations and must
exist.
- The recorder loads filters in the order discovered: the built-in
`builtin-default` filter first, then project defaults, CLI/env entries,
and explicit Python API arguments. Later rules override earlier ones
when selectors overlap.

## Runtime Metadata
- `trace_metadata.json` now exposes a `trace_filter` object containing:
- `filters` – ordered list of filter summaries (`name`, `version`,
SHA-256 digest, absolute path).
- `stats.scopes_skipped` – total number of code objects blocked by `exec
= "skip"`.
- `stats.value_redactions` – per-kind counts for redacted values
(`argument`, `local`, `global`, `return`, `attribute`).
- `stats.value_drops` – per-kind counts for values removed entirely from
the trace.
- These counters help CI/quality tooling detect unexpectedly aggressive
filters.

## Benchmarks and Guard Rails
- Rust microbench: `cargo bench --bench trace_filter
--no-default-features` exercises baseline vs glob/regex-heavy rule sets.
- Python smoke benchmark: `pytest
codetracer-python-recorder/tests/python/perf/test_trace_filter_perf.py`
runs end-to-end tracing with synthetic workloads when
`CODETRACER_TRACE_FILTER_PERF=1`.
- `just bench` orchestrates both:
  1. Ensures the development virtualenv exists (`just venv`).
2. Runs the Criterion bench with `PYO3_PYTHON` pinned to the virtualenv
interpreter.
3. Executes the Python smoke benchmark, writing
`codetracer-python-recorder/target/perf/trace_filter_py.json` (durations
plus redaction/drop stats per scenario).
- Use the JSON artefact to feed dashboards or simple regression checks
while longer-term gating thresholds are defined.

Author: tzanko-matev

Justfile

@@ -40,6 +40,24 @@ test: cargo-test py-test
 cargo-test:
     uv run cargo nextest run --manifest-path codetracer-python-recorder/Cargo.toml --workspace --no-default-features
 
+bench:
+    just venv
+    ROOT="$(pwd)"; \
+    PYTHON_BIN="$ROOT/.venv/bin/python"; \
+    if [ ! -x "$PYTHON_BIN" ]; then \
+        PYTHON_BIN="$ROOT/.venv/Scripts/python.exe"; \
+    fi; \
+    if [ ! -x "$PYTHON_BIN" ]; then \
+        echo "Python interpreter not found. Run 'just venv <version>' first."; \
+        exit 1; \
+    fi; \
+    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/CHANGELOG.md

@@ -5,7 +5,13 @@ All notable changes to `codetracer-python-recorder` will be documented in this f
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+
+## [0.2.0] - 2025-10-17
 ### Added
+- Added configurable trace filters backed by layered TOML files with glob/regex/literal selectors for packages, files, objects, and value domains, strict schema validation via `TraceFilterConfig::from_paths`, and explicit `allow`/`redact`/`drop` value policies summarised with SHA-256 digests.
+- Added `TraceFilterEngine` and runtime wiring that cache scope resolutions, gate tracing, substitute `<redacted>` for filtered payloads, drop suppressed variables entirely, and emit per-kind redaction/drop counters alongside filter summaries in `trace_metadata.json`.
+- Exposed configurable filters through the Python API, auto-start hook, CLI (`--trace-filter`), and `CODETRACER_TRACE_FILTER` environment variable while always prepending the built-in default filter that skips stdlib noise and redacts common secrets before layering project overrides.
+- Added filter-focused documentation and benchmarking coverage, including onboarding and README guides plus Criterion + Python smoke benchmarks orchestrated by `just bench`.
 - Introduced a line-aware IO capture pipeline that records stdout/stderr chunks with `{path_id, line, frame_id}` attribution via the shared `LineSnapshotStore` and multi-threaded `IoEventSink`.
 - Added `LineAwareStdout`, `LineAwareStderr`, and `LineAwareStdin` proxies that forward to the original streams while batching writes on newline, explicit `flush()`, 5 ms idle gaps, and step boundaries.
 - Added policy, CLI, and environment toggles for IO capture (`--io-capture`, `configure_policy(io_capture_line_proxies=..., io_capture_fd_fallback=...)`, `CODETRACER_CAPTURE_IO`) alongside the `ScopedMuteIoCapture` guard that suppresses recursive recorder logging.
@@ -22,5 +28,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 - Support for generating `trace_metadata.json` and `trace_paths.json` artefacts compatible with the Codetracer db-backend importer.
 - Cross-platform packaging targeting CPython 3.12 and 3.13 on Linux (manylinux2014 `x86_64`/`aarch64`), macOS universal2, and Windows `amd64`.
 
-[Unreleased]: https://github.com/metacraft-labs/cpr-main/compare/recorder-v0.1.0...HEAD
+[Unreleased]: https://github.com/metacraft-labs/cpr-main/compare/recorder-v0.2.0...HEAD
+[0.2.0]: https://github.com/metacraft-labs/cpr-main/compare/recorder-v0.1.0...recorder-v0.2.0
 [0.1.0]: https://github.com/metacraft-labs/cpr-main/releases/tag/recorder-v0.1.0