FUTHARK-PROFILE(1)

👑 FUTHARK-PROFILE — ok so bestie, this is the manual ✨

Welcome to FUTHARK-PROFILE(1), a page from the Futhark manual. Pull up a chair, grab a boba, and let's profile some Futhark programs together 💖

---

🌸 NAME 🌸

futhark-profile — profile Futhark programs 🫶

---

✨ SYNOPSIS ✨

futhark profile JSONFILES

---

💅 DESCRIPTION 💅

Okay so real talk: this tool makes human-readable profiling information based on info that was collected with futhark bench <#futhark-bench-1>. That's it, that's the job 💁‍♀️

Futhark has basic support for profiling. The system can collect info about the runtime behaviour of your program and connect it back to the program source code as best it's able to (bless it, it's trying).

It works best for the GPU backends, and like… not at all for the sequential backends 😭. Once you've got that collected info, you can use it to estimate where your inefficiencies are coming from. Detective mode 🔍✨

---

🎀 USAGE 🎀

Step one, bestie: run futhark bench <#futhark-bench-1> on your program while passing --profile and --json. This gives you a JSON file with runtime measurements plus the collected profiling information, slay 🙌

If you neglect to pass --profile, the profiling information will just be missing. Not a vibe, not a warning, just gone. So don't forget it 💀

The info in that JSON file is complete, sure, but it's really hard for humans to read — it's giving raw unhinged data dump fr fr.

Step two: run futhark profile on that JSON file. For a JSON file called prog.json, this creates a top level directory called prog.prof that contains files with human-readable profiling info. One set of files gets created for each benchmark dataset 📁✨

Now — if the original futhark bench invocation included multiple programs, then futhark profile will create subdirectories for each program (although all inside the same top level directory). Cute little family tree 🧚

You can also pass multiple JSON files to futhark profile. Each one will produce a distinct top level directory. No merge, no chaos, just separate vibes.

---

🍓 Files produced

Let's say you've got a dataset called 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, most importantly the source locations 📍

The log file is often too verbose to be useful (it's giving novel), but the summary and timeline should be inspected — even if the latter is sometimes fairly large. Read your timeline bestie, it loves you 💖

---

🦋 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. So like… keep that in mind 👀

---

🌈 Raw reports

Alternatively, the JSON file passed to futhark profile may also be 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. Shorter, simpler, still valid 🫶

---

🔥 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

Look at that tree. Iconic. No .timeline files in this particular example, before you ask — we just list what's there 👑✨

---

💀 BUGS 💀

• Only the C-based backends currently support profiling.
• The c backend does not actually record useful profiling information. Not me exposing it 😭

---

🌟 SEE ALSO 🌟

• futhark-bench <#futhark-bench-1>

---

💜 Copyright

2013-2020, DIKU, University of Copenhagen

---

Ok that's the whole page bestie, you ate it 💅✨ This was version 0.25.32 from Mar 11, 2026, of the Futhark manual — go profile something and slay 🫶💖🎀🌈⭐👑