Skip to content

OracleTrace v3.0.0 - Release Notes

Date: 2026-06-16

This major release brings powerful testing integrations, statistical improvements for tracing accuracy, and much more resilient internal file filtering.

Important: Please note that this release requires a Python version upgrade for some users.

⚠️ Breaking Changes & Migration

  • Python 3.11+ Required: Support for Python 3.10 has been officially dropped. You must use Python 3.11 or newer to install and run OracleTrace v3.0.0.

Summary

OracleTrace 3.0.0 introduces:

  • New oracletrace run subcommand for native pytest integration.
  • New --repeat flag to aggregate multiple runs using medians.
  • Crucial bug fixes for the is_user_code detection logic (better venv and stdlib filtering).
  • Internal refactoring optimizing function data structures.

Changelog

Added

  • Pytest Integration (run command): Introduced the oracletrace run subcommand. This allows you to trace commands like pytest directly in-process (e.g., oracletrace run [options] -- pytest tests/). It intelligently handles exit codes, ensuring that if --fail-on-regression catches a slowdown, it properly exits with code 2 even if the tests pass.
  • Repeat Flag (--repeat): Added the ability to repeat the trace execution N times. OracleTrace will now compute the median of total execution times and call counts across all runs. This significantly reduces OS-level noise, mitigates cold-start variance, and improves regression comparison accuracy.
  • Expanded Test Coverage: Added dedicated test suites for the new tracer capabilities and repeat behavior.

Improved

  • Function Data Optimization: Internally updated FunctionData and tracing structures to use set instead of List for callees. This improves performance and guarantees uniqueness when building the logic flow.
  • Data Aggregation: Implemented FunctionAggregate internal logic to smoothly handle data compilation and math when using the --repeat flag.
  • Documentation: README and CLI Reference have been completely updated to detail pytest CI workflows, the new run subcommand, and the --repeat behavior.

Fixes

  • User Code Detection (Bugfix): Completely overhauled the is_user_code logic. The previous string-matching approach was fragile. It now uses os.path.realpath and os.path.commonpath to accurately resolve symlinks, natively ignore the Python standard library, filter dynamic site-packages, and automatically exclude virtual environment folders (venv, .venv, env, .env, virtualenv).
  • Resolved internal rebase and typing errors discovered during the development of the repeat flag feature.

Upgrade

# Ensure you are on Python >= 3.11
pip install --upgrade oracletrace

Thanks

Thanks to all contributors who helped improve reliability, typing, testing, and documentation in this patch release.