Profiling

Compiling oxlint in release mode with debug information

For profiling, you will need to compile the oxlint binary in release mode with debug information enabled. You can do that by passing --profile release-with-debug to cargo build:

cargo build --profile release-with-debug --bin oxlint

After building, the binary is located at ./target/release-with-debug/oxlint. This is the binary that should be used for profiling.

CPU - Samply

Samply is a command line CPU profiler which uses the Firefox profiler as its UI. Works on macOS and Linux.

To use Samply with oxlint, run samply record followed by the oxlint command and arguments:

samply record ./target/release-with-debug/oxlint .

To improve the profiling experience, you might consider some of the following options:

• oxlint: --silent will suppress diagnostics output and keep the profile more focused.
• oxlint: --threads 1 will run the linter single threaded, which is slower, but makes it easier to analyze the profile for single-threaded performance.
• samply record: --rate <number> will sample the profile at a higher rate. The default is 1000Hz (1ms), but increasing this will provide more detailed information at the cost of a larger profile file.

For example, running oxlint single-threaded with a 0.1ms sample rate:

samply record --rate 10000 ./target/release-with-debug/oxlint --silent --threads 1 .

CPU - Mac Xcode Instruments

cargo instruments is the tool of choice to bridge Mac Xcode instruments.

The following instruction replicates the procedure of cargo instruments.

First, install Xcode Instruments command-line tools:

xcode-select --install

Then, if you haven't already, ensure that the oxlint binary is compiled.

Under the hood, cargo instruments invokes the xcrun xctrace command, which is equivalent to

xcrun xctrace record --template 'Time Profile' --output . --launch -- /path/to/oxc/target/release-with-debug/oxlint

Running the command above produces the following output

Starting recording with the Time Profiler template. Launching process: oxlint.
Ctrl-C to stop the recording
Target app exited, ending recording...
Recording completed. Saving output file...
Output file saved as: Launch_oxlint_2023-09-03_4.41.45 PM_EB179B85.trace

Open the trace file open Launch_oxlint_2023-09-03_4.41.45\ PM_EB179B85.trace.

To see a top down trace:

1. On the top panel, click CPUs
2. On the left input box, click x then select Time Profiler
3. At the bottom panel, click "Call Tree", turn on "Invert Call Tree" and turn off separate by thread.

For memory and disk operations, use --template 'Allocations' and --template 'File Activity'.

For more detailed CPU profiling, such as L1/L2 cache misses, cycle and instruction counts, and branch prediction info, you need to use a custom "CPU Counters" template:

1. Open Instruments and select the "CPU Counters" template.
2. In the "CPU Counters" settings:
   1. Turn on the "High Frequency Sampling" option.
   2. Below the "High Frequency Sampling" option, click the plus icon and select an event type. Some suggested event types:
      • Cycles - for getting a rough idea of how many CPU cycles are spent in each function.
      • Instructions - for getting a rough idea of how many CPU instructions are executed in each function and how many cycles that takes
      • L1D_CACHE_MISS_LD - count of L1 cache misses from loading data from memory
3. Once you have enabled the events you are interested in, save the template in "File > Save as Template ..." and give it a name.
4. Now you can use this with xctrace by passing the template name to the --template option: xcrun xctrace record --template 'My Custom CPU Counters' --output . --launch -- /path/to/oxc/target/release-with-debug/oxlint

Heap Allocation - dhat

dhat is a heap profiler that can help identify memory leaks and analyze heap allocation patterns.

Setup

Add dhat as a dependency to your Cargo.toml:

[dependencies]
dhat = "0.3"

Then add a global allocator at the top of your binary crate:

#[global_allocator]
static ALLOC: dhat::Alloc = dhat::Alloc;

Profiling

Create a profiler in the scope you want to profile. The profiler will track allocations from when it's created until it's dropped:

fn main() {
    let _profiler = dhat::Profiler::new_heap();
    // Your code here - all heap allocations will be tracked
}

You can also add _profiler to any function to track memory only for that specific function:

fn my_function() {
    let _profiler = dhat::Profiler::new_heap();
    // Only allocations within this function scope will be tracked
}

The profiler will automatically generate a dhat-heap.json file when it's dropped.

Loading and Reading the Profile

After running your program, a dhat-heap.json file will be created in your working directory.

To analyze the profile:

1. Open the dhat viewer at https://nnethercote.github.io/dh_view/dh_view.html
2. Load the dhat-heap.json file
3. Select a metric in "Sort metrics" to analyze different aspects of memory usage:
   • "At t-gmax (bytes)": Shows allocations at the point of peak memory usage. Use this to identify what's consuming the most memory when your program reaches its maximum heap size.
   • "At t-end (bytes)": Shows memory that was not dropped before the profiler was destroyed. This is particularly useful for identifying memory leaks, as it reveals allocations that remain at the end of the profiled scope.
   • "Total (bytes)": Shows the total number of bytes allocated over the entire execution. Use this to identify which parts of your code are performing the most allocations, even if the memory is later freed.

Advanced: Controlling Profiler Lifetime

For more control over when profiling stops, you can explicitly manage the profiler's lifetime. For example, to profile only the core logic and exclude cleanup:

struct MyApp {
    profiler: Option<dhat::Profiler>,
    // other fields
}

impl MyApp {
    fn close(&mut self) {
        // Drop the profiler here to capture the heap state before cleanup
        self.profiler = None;
        // cleanup code
    }
}

This pattern helps identify which data structures are holding memory at a specific point in your program's execution.