# Trace Tool

The Trace Tool is a utility for parsing and converting Mina's internal trace logs 
into a format compatible with the Chrome Trace Viewer. This allows developers to 
visualize thread execution, timing, and events within the Mina daemon for performance 
analysis and debugging.

## Features

- Parses Mina's binary trace format
- Converts trace data to Chrome Trace Event Format (JSON)
- Tracks thread creation, thread switching, and cycle information
- Handles recurring threads and thread mapping
- Supports merging multiple trace files
- Optional raw trace dump for debugging

## Prerequisites

- Rust development environment
- Trace files generated by the Mina daemon

## Compilation

To build the utility:

```
cd src/app/trace-tool
cargo build --release
```

The compiled binary will be available at `target/release/trace-tool`.

## Usage

```
trace-tool [OPTIONS] INPUT_FILES...
```

### Arguments:

- `INPUT_FILES`: One or more trace files to process (required)

### Options:

- `-d, --dump-raw`: Dump the raw trace event debug representation and quit

### Example:

```
trace-tool trace1.bin trace2.bin > trace_output.json
```

This command processes two trace files and outputs the combined Chrome Trace Viewer 
compatible JSON to `trace_output.json`.

## Output Format

The tool outputs data in the [Chrome Trace Event Format](https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU), 
which can be loaded into Chrome's `chrome://tracing` or other compatible trace viewers.

The format captures:

- Thread creation and naming
- Thread execution spans
- Instant events
- Start/end event pairs
- Cycle boundaries

## Viewing Traces

To view the generated trace file:

1. Open Chrome and navigate to `chrome://tracing`
2. Click "Load" and select the generated JSON file
3. Explore the trace visualization

## Technical Notes

The Trace Tool processes several types of trace events:

- `New`: Thread creation with ID and name
- `Switch`: Thread context switch
- `CycleStart`/`CycleEnd`: Marks the beginning and end of execution cycles
- `Pid`: Process identifier
- `Event`: Instant event
- `Start`/`End`: Duration event boundaries
- `TraceEnd`: End of trace marker

The tool handles thread mapping for recurring threads, allowing for proper 
visualization of threads that appear multiple times in the trace.