---
title: "Trace & Optimize E2E Workflows"
description: "End-to-end optimization of entire workflows with execution tracing"
icon: "route"
sidebarTitle: "Optimize E2E Workflows"
keywords:
[
"tracing",
"workflow optimization",
"replay tests",
"end-to-end",
"script optimization",
"context manager",
"javascript",
"typescript",
"jest",
"vitest",
"java",
"jfr",
"maven",
"gradle",
]
---
Codeflash can optimize an entire script or test suite end-to-end by tracing its execution and generating Replay Tests.
Tracing follows the execution of your code, profiles it and captures inputs to all functions it called, allowing them to be replayed during optimization.
Codeflash uses these Replay Tests to optimize the most important functions called in the workflow, delivering the best performance.
To optimize a script, `python myscript.py`, simply replace `python` with `codeflash optimize`:
```bash
codeflash optimize myscript.py
```
You can also optimize code called by pytest tests:
```bash
codeflash optimize -m pytest tests/
```
To trace and optimize your Jest or Vitest tests:
```bash
# Jest
codeflash optimize --jest
# Vitest
codeflash optimize --vitest
# Or trace a specific script
codeflash optimize --language javascript script.js
```
To trace and optimize a running Java program, replace your `java` command with `codeflash optimize java`:
```bash
# Class with classpath (recommended — works with any compiled project)
codeflash optimize java -cp target/classes com.example.Main
# Executable JAR (requires maven-jar-plugin or equivalent with Main-Class manifest)
codeflash optimize java -jar target/my-app.jar --app-args
# Maven exec
codeflash optimize mvn exec:java -Dexec.mainClass="com.example.Main"
```
For long-running programs (servers, benchmarks), use `--timeout` to limit each tracing stage:
```bash
codeflash optimize --timeout 30 java -cp target/classes com.example.Main
```
The `codeflash optimize` command creates high-quality optimizations, making it ideal when you need to optimize a workflow or script. The initial tracing process can be slow, so try to limit your script's runtime to under 1 minute for best results.
The generated replay tests and the trace file are for the immediate optimization use, don't add them to git.
## Codeflash optimize 1 min demo
## What is the codeflash optimize command?
`codeflash optimize` tries to do everything that an expert engineer would do while optimizing a workflow. It profiles your code, traces the execution of your workflow and generates a set of test cases that are derived from how your code is actually run.
Codeflash Tracer works by recording the inputs of your functions as they are called in your codebase, and generating
regression tests with those inputs.
We call these generated test cases "Replay Tests" because they replay the inputs that were recorded during the tracing phase.
These replay tests are representative of the real-world usage of your functions.
Using Replay Tests, Codeflash can verify that the optimized functions produce the same output as the original function and also measure the performance gains of the optimized function on the real-world inputs.
This way you can be _sure_ that the optimized function causes no changes of behavior for the traced workflow and also, that it is faster than the original function. To get more confidence on the correctness of the code, we also generate several LLM generated test cases and discover any existing unit cases you may have.
## Using codeflash optimize
Codeflash script optimizer can be used in three ways:
1. **As an integrated command**
If you run a Python script as follows
```bash
python path/to/your/file.py --your_options
```
You can start tracing and optimizing your code with the following command
```bash
codeflash optimize path/to/your/file.py --your_options
```
The above command should suffice in most situations.
To customize the trace file location you can specify it like `codeflash optimize --output trace_file_path.trace`. Otherwise, it defaults to `codeflash.trace` in the current working directory.
2. **Trace and optimize as two separate steps**
If you want more control over the tracing and optimization process. You can trace first and then optimize with the replay tests later. Each replay test is associated with a trace file.
To create just the trace file first, run
```bash
codeflash optimize --output trace_file.trace --trace-only path/to/your/file.py --your_options
```
This will create a replay test file. To optimize with the replay test, run the
```bash
codeflash --replay-test /path/to/test_replay_test_0.py
```
More Options:
- `--timeout`: The maximum time in seconds to trace the entire workflow. Default is indefinite. This is useful while tracing really long workflows.
3. **As a Context Manager**
To trace only specific sections of your code, you can use the Codeflash Tracer as a context manager.
You can wrap the code you want to trace in a `with` statement as follows:
```python
from codeflash.tracer import Tracer
with Tracer(output="codeflash.trace"):
model.predict() # Your code here
```
This is much faster than tracing the whole script. It can also help if tracing the whole script fails.
After this finishes, you can optimize using the generated replay tests.
```bash
codeflash --replay-test /path/to/test_replay_test_0.py
```
More Options for the Tracer Context Manager:
- `disable`: If set to `True`, the tracer will not trace the code. Default is `False`.
- `max_function_count`: The maximum number of times to trace a single function. More calls to a function will not be traced. Default is 100.
- `timeout`: The maximum time in seconds to trace the entire workflow. Default is indefinite. This is useful while tracing really long workflows, to not wait indefinitely.
- `output`: The file to save the trace to. Default is `codeflash.trace`.
- `config_file_path`: The path to the `pyproject.toml` file which stores the Codeflash config. This is auto-discovered by default.
You can also disable the tracer in the code by setting the `disable=True` option in the `Tracer` constructor.
The JavaScript tracer uses Babel instrumentation to capture function calls during your test suite execution.
1. **Trace your test suite**
```bash
# Jest projects
codeflash optimize --jest
# Vitest projects
codeflash optimize --vitest
# Trace a specific script
codeflash optimize --language javascript src/main.js
```
2. **Trace specific functions only**
```bash
codeflash optimize --jest --only-functions processData,transformInput
```
3. **Trace and optimize as two separate steps**
```bash
# Step 1: Create trace file
codeflash optimize --trace-only --jest --output trace_file.sqlite
# Step 2: Optimize with replay tests
codeflash --replay-test /path/to/test_replay_test_0.test.js
```
More Options:
- `--timeout`: Maximum tracing time in seconds.
- `--max-function-count`: Maximum traces per function (default: 256).
- `--only-functions`: Comma-separated list of function names to trace.
The Java tracer uses a **two-stage approach**: JFR (Java Flight Recorder) for accurate profiling, then a bytecode instrumentation agent for argument capture.
1. **Trace and optimize a Java program**
Replace your `java` command with `codeflash optimize java`:
```bash
# Class with classpath (recommended — works with any compiled project)
codeflash optimize java -cp target/classes com.example.Main
# Executable JAR (requires maven-jar-plugin or equivalent with Main-Class manifest)
codeflash optimize java -jar target/my-app.jar --app-args
```
The `-cp` approach works with any project after `mvn compile` or `gradle build`. The `-jar` approach requires your project to produce an executable JAR with a `Main-Class` entry in the manifest — this is not the default Maven behavior.
Codeflash will run your program twice (once for profiling, once for argument capture), generate JUnit replay tests, then optimize the most impactful functions.
2. **Long-running programs**
For servers, benchmarks, or programs that don't terminate on their own, use `--timeout` to limit each tracing stage:
```bash
codeflash optimize --timeout 30 java -cp target/classes com.example.Main
```
Each stage runs for at most 30 seconds, then the program is terminated and captured data is processed.
3. **Trace only (no optimization)**
```bash
codeflash optimize --trace-only java -jar target/my-app.jar
```
This generates replay tests in `src/test/java/codeflash/replay/` without running the optimizer.
More Options:
- `--timeout`: Maximum time (seconds) for each tracing stage.
- `--max-function-count`: Maximum captures per method (default: 100).
**How the Java tracer works:**
- **Stage 1 (JFR)**: Runs your program with Java Flight Recorder enabled. JFR is built into the JVM (Java 11+), has ~1% overhead, and doesn't interfere with JIT compilation. This produces accurate method-level CPU profiling data.
- **Stage 2 (Agent)**: Runs your program with a bytecode instrumentation agent injected via `JAVA_TOOL_OPTIONS`. The agent intercepts method entry points, serializes arguments using Kryo, and writes them to an SQLite database. A 500ms timeout per serialization prevents hangs on complex object graphs.
- **Replay Tests**: Generated JUnit 5 test classes that deserialize captured arguments and invoke the original methods via reflection. These tests exercise your code with real-world inputs.