OracleTrace v3.0.0 - Release Notes 🎉

[KaykCaputo]

OracleTrace v3.0.0 — Release Notes

Date: 2026-06-16

This major release focuses on enhancing CI workflows and testing integration, introducing robust statistical tracing, native test framework support, and much more accurate internal file filtering.

Summary

OracleTrace 3.0.0 introduces:

• Native pytest integration via the new run subcommand
• Statistical trace aggregation to reduce noise (--repeat)
• Overhauled and highly accurate user-code detection logic (ignoring venv, stdlib, etc.)
• Internal memory and performance optimizations using set for call graphs
• Expanded test coverage for the new CLI behaviors

Changelog

Added

• New oracletrace run subcommand to trace commands in-process (e.g., oracletrace run -- pytest tests/).
• Trace execution repeat flag (--repeat) which runs the target multiple times and computes the median of execution times and call counts, significantly reducing OS-level variance.
• Dedicated test suites for the new repeat behavior and run subcommand logic.

Improved

• Internal FunctionData optimized to use set instead of List for callees, guaranteeing uniqueness and improving performance when building logic flows.
• Introduced FunctionAggregate internals to seamlessly process multi-run calculations and math.
• Exit code prioritization refined: if --fail-on-regression is active, a regression will correctly exit with code 2, successfully overriding standard pytest exit codes.

Fixes / Maintenance

• Bugfix (User Code Detection): Completely overhauled the is_user_code logic. It now uses os.path.realpath and os.path.commonpath to resolve symlinks accurately, natively ignores the Python standard library, filters dynamic site-packages, and automatically excludes virtual environment folders (venv, .venv, env, etc.).
• Resolved typing and rebase errors during the internal tracer restructuring.

Compatibility and Migration Notes

• ⚠️ BREAKING CHANGE: Support for Python 3.10 has been officially dropped.
• Requirement is now: Python >= 3.11
• Existing baseline + compare workflows remain valid. Traces generated in older versions can still be compared.
• For testing pipelines, you can now trace your existing test suite instead of a standalone script.

Recommended CI Command

With the new pytest integration, you can use OracleTrace as a performance guardrail directly over your test suite:

oracletrace run --json current.json --compare baseline.json --fail-on-regression --threshold 10 -- pytest tests/

Upgrade

pip install --upgrade oracletrace

Thanks

Thanks to all contributors who helped improve reliability, statistical tracing, and CI testing capabilities in this major release.