diff --git a/docs/src/development/linux.md b/docs/src/development/linux.md
index a6799378bc00b5c992fd99562b6446729de22559..df3b840fa17a547efd4324f3bdaa119b8ade8738 100644
--- a/docs/src/development/linux.md
+++ b/docs/src/development/linux.md
@@ -165,6 +165,58 @@ $ cargo heaptrack -b zed
 
 When this zed instance is exited, terminal output will include a command to run `heaptrack_interpret` to convert the `*.raw.zst` profile to a `*.zst` file which can be passed to `heaptrack_gui` for viewing.
 
+## Perf recording
+
+How to get a flamegraph with resolved symbols from a running zed instance. Use
+when zed is using a lot of CPU. Not useful for hangs.
+
+### During the incident
+
+- Find the PID (process ID) using:
+  `ps -eo size,pid,comm | grep zed | sort | head -n 1 | cut -d ' ' -f 2`
+  Or find the pid of the command zed-editor with the most ram usage in something
+  like htop/btop/top.
+
+- Install perf:
+  On Ubuntu (derivatives) run `sudo apt install linux-tools`.
+
+- Perf Record:
+  run `sudo perf record -p <pid you just found>`, wait a few seconds to gather data then press Ctrl+C. You should now have a perf.data file
+
+- Make the output file user owned:
+  run `sudo chown $USER:$USER perf.data`
+
+- Get build info:
+  Run zed again and type `zed: about` in the command pallet to get the exact commit.
+
+The `data.perf` file can be send to zed together with the exact commit.
+
+### Later
+
+This can be done by Zed staff.
+
+- Build Zed with symbols:
+  Check out the commit found previously and modify `Cargo.toml`.
+  Apply the following diff then make a release build.
+
+```diff
+[profile.release]
+-debug = "limited"
++debug = "full"
+```
+
+- Add the symbols to perf database:
+  `pref buildid-cache -v -a <path to release zed binary>`
+
+- Resolve the symbols from the db:
+  `perf inject -i perf.data -o perf_with_symbols.data`
+
+- Install flamegraph:
+  `cargo install cargo-flamegraph`
+
+- Render the flamegraph:
+  `flamegraph --perfdata perf_with_symbols.data`
+
 ## Troubleshooting
 
 ### Cargo errors claiming that a dependency is using unstable features