# futhark-profile

## SYNOPSIS

futhark profile JSONFILES

## DESCRIPTION

This tool produces human-readable profiling information based on information collected with futhark bench. Futhark has only rudimentary support for profiling. While the system can collect information about the run-time behaviour of the program, there is currently no automatic way to connect the information to the program source code. However, the collected information can still be useful for estimating the source of inefficiencies.

## USAGE

The first step is to run futhark bench on your program, while passing `--profile` and `--json`. This will produce a JSON file containing runtime measurements, as well as collected profiling information. If you neglect to pass `--profile`, the profiling information will be missing. The information in the JSON file is complete, but it is difficult for humans to read.

The next step is to run `futhark profile` on the JSON file. For a JSON file `prog.json`, this will create a top level directory `prog.prof` that contains files with human-readable profiling information. A set of files will be created for each benchmark dataset. If the original invocation of `futhark bench` included multiple programs, then `futhark profile` will create subdirectories for each program (although all inside the same top level directory).

You can pass multiple JSON files to `futhark profile`. Each will produce a distinct top level directory.

### Files produced

Supposing a dataset `foo`, `futhark profile` will produce the following files in the top level directory.

- `foo.log`: the running log produced during execution. Contains many details on dynamic behaviour, depending on the exact backend.

- `foo.summary`: a summary of memory usage and cost centres. For the GPU backends, the cost centres are kernel executions and memory copies.

- `foo.timeline`: a list of all recorded profiling events, in the order in which they occurred, along with their runtime and other available information

### Technicalities

The profiling information, including the log, is collected from a final run performed after all the measured runs. Profiling information is not collected during the runs that contribute to the runtime measurement reported by `futhark bench`. However, enabling profiling may still affect performance, as it changes the behaviour of the run time system.

### Raw reports

Alternatively, the JSON can also contain a raw profiling report as produced by the C API function `futhark_context_report()`. A directory is still created, but it will only contain a single set of files, and it will not contain a log.

## EXAMPLES

This shows the sequence of commands one might use to profile the program `LocVolCalib.fut`, which has three datasets associated with it, using the `hip` backend:

    $ futhark bench --backend=hip --profile --json result.json LocVolCalib.fut
    $ futhark profile result.json
    $ tree result.prof/
    result.prof/
    ├── LocVolCalib-data_large.in.log
    ├── LocVolCalib-data_large.in.summary
    ├── LocVolCalib-data_medium.in.log
    ├── LocVolCalib-data_medium.in.summary
    ├── LocVolCalib-data_small.in.log
    └── LocVolCalib-data_small.in.summary

## BUGS

Only the C-based backends currently support profiling.

The `c` backend does not actually record useful profiling information.

## SEE ALSO

futhark-bench