doc: Add eval-profiler documentation and release note

doc/manual/rl-next/eval-profiler.md

@@ -0,0 +1,13 @@
+---
+synopsis: Add stack sampling evaluation profiler
+prs: [13220]
+---
+
+Nix evaluator now supports stack sampling evaluation profiling via `--eval-profiler flamegraph` setting.
+It collects collapsed call stack information to output file specified by
+`--eval-profile-file` (`nix.profile` by default) in a format directly consumable
+by `flamegraph.pl` and compatible tools like [speedscope](https://speedscope.app/).
+Sampling frequency can be configured via `--eval-profiler-frequency` (99 Hz by default).
+
+Unlike existing `--trace-function-calls` this profiler includes the name of the function
+being called when it's available.

doc/manual/source/SUMMARY.md.in

@@ -57,6 +57,7 @@
   - [Tuning Cores and Jobs](advanced-topics/cores-vs-jobs.md)
   - [Verifying Build Reproducibility](advanced-topics/diff-hook.md)
   - [Using the `post-build-hook`](advanced-topics/post-build-hook.md)
+  - [Evaluation profiler](advanced-topics/eval-profiler.md)
 - [Command Reference](command-ref/index.md)
   - [Common Options](command-ref/opt-common.md)
   - [Common Environment Variables](command-ref/env-common.md)

doc/manual/source/advanced-topics/eval-profiler.md

@@ -0,0 +1,33 @@
+# Using the `eval-profiler`
+
+Nix evaluator supports [evaluation](@docroot@/language/evaluation.md)
+[profiling](<https://en.wikipedia.org/wiki/Profiling_(computer_programming)>)
+compatible with `flamegraph.pl`. The profiler samples the nix
+function call stack at regular intervals. It can be enabled with the
+[`eval-profiler`](@docroot@/command-ref/conf-file.md#conf-eval-profiler)
+setting:
+
+```console
+$ nix-instantiate "<nixpkgs>" -A hello --eval-profiler flamegraph
+```
+
+Stack sampling frequency and the output file path can be configured with
+[`eval-profile-file`](@docroot@/command-ref/conf-file.md#conf-eval-profile-file)
+and [`eval-profiler-frequency`](@docroot@/command-ref/conf-file.md#conf-eval-profiler-frequency).
+By default the collected profile is saved to `nix.profile` file in the current working directory.
+
+The collected profile can be directly consumed by `flamegraph.pl`:
+
+```console
+$ flamegraph.pl nix.profile > flamegraph.svg
+```
+
+The line information in the profile contains the location of the [call
+site](https://en.wikipedia.org/wiki/Call_site) position and the name of the
+function being called (when available). For example:
+
+```
+/nix/store/x9wnkly3k1gkq580m90jjn32q9f05q2v-source/pkgs/top-level/default.nix:167:5:primop import
+```
+
+Here `import` primop is called at `/nix/store/x9wnkly3k1gkq580m90jjn32q9f05q2v-source/pkgs/top-level/default.nix:167:5`.