Skip to content

CLI Reference

Complete command reference for OracleTrace.

Command syntax

oracletrace <target> [--json OUTPUT.json] [--csv OUTPUT.csv] [--html OUTPUT.html] [--compare BASELINE.json]
oracletrace <target> [--ignore REGEX [REGEX ...]]
oracletrace <target> [--top NUMBER]
oracletrace <target> [--compare BASELINE.json] [--fail-on-regression] [--threshold PERCENT] [--only-regressions]
oracletrace --version

Required argument

target

Path to the Python script you want to trace.

Example:

oracletrace my_app.py

Optional arguments

--json

Exports trace results to a JSON file.

oracletrace my_app.py --json run.json

Use this when you want to keep historical traces or compare later.

--csv

Exports the trace results to a csv file.

oracletrace my_app.py --csv run.csv

--html

Exports the trace results to an interactive HTML file.

oracletrace my_app.py --html report.html

The generated report includes a sortable table with function timing data and a call graph visualization.

--compare

Compares the current run against a previous JSON trace.

oracletrace my_app.py --json current.json --compare baseline.json

Comparison output includes:

  • Functions with performance increase or decrease
  • Newly added functions
  • Removed functions

--fail-on-regression

Makes OracleTrace return a non-zero exit code when a regression exceeds the configured threshold.

Use this together with --compare.

Example:

oracletrace my_app.py --json current.json --compare baseline.json --fail-on-regression --threshold 25

--threshold

Sets the percentage threshold used with --fail-on-regression.

Default value: 5.0

oracletrace my_app.py --compare baseline.json --fail-on-regression --threshold 25

---only-regressions

Shows only the regressions in the diff output when comparing traces.

Use with --compare.

Default value: False

oracletrace my_app.py --compare baseline.json --only-regressions

--ignore

Specify file paths and function names to ignore using regular expression syntax.

oracletrace my_app.py --ignore ".*test.*" ".*helpers.py:debug_.*"

The ignored files and functions will not appear in the summary table neither the logic flow output.

Ignore matching is applied on function keys in the form relative_path.py:qualified_function_name.

--top

Limit the summary table output to a maximum number of results.

oracletrace my_app.py --top 10

--version

Prints version information and exit with a zero code.

oracletrace --version

Exit behavior

OracleTrace returns a non-zero exit code when:

  • The target script does not exist
  • The compare JSON file does not exist
  • --fail-on-regression is enabled and at least one function regresses above the threshold

Non-zero exit codes can also happen when the target script fails at runtime or when the compare JSON file cannot be parsed.

Typical workflows

Local development workflow

oracletrace app.py --json baseline.json
# change code
oracletrace app.py --json current.json --compare baseline.json

CI regression workflow

oracletrace app.py --json current.json --compare baseline.json --fail-on-regression --threshold 10

Store baseline.json as a known-good artifact.

Tips

  • Run from your project root so filtering focuses on your app code
  • Keep baseline and current runs as similar as possible
  • Use deterministic input data for reliable comparisons