Improve documentation for new allocation profiler

[gdalle]

Hi, and thank you for the awesome new allocation profiler!

I feel like it is not obvious from the documentation (manual page and API reference) how to retrieve and visualize the results from Profile.Allocs.@profile.

PProf.jl is mentioned, but not the specific function we need to call (PProf.Allocs.pprof). I think it would make sense to describe an example workflow in the manual (see below).

In addition, I guess users would be interested to know if there is any visualization (eg. @profview) or pretty-printing (eg. Profile.print()) method that works directly in the REPL / VSCode / Pluto.

julia> using Profile, PProf

julia> Profile.Allocs.clear()

julia> peakflops(); Profile.Allocs.@profile sample_rate=1 peakflops()
6.474132101420371e10

julia> results = Profile.Allocs.fetch();

julia> PProf.Allocs.pprof(results; from_c=false)
Analyzing 11 allocation samples... 100%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| Time: 0:00:00
Main binary filename not available.
Serving web UI on http://localhost:62261
"alloc-profile.pb.gz"

[gdalle]

Related discussions:

• Julia allocation profiler PR (https://github.com/JuliaLang/julia/pull/42768)
• PProf support PR (https://github.com/JuliaPerf/PProf.jl/pull/46)
• ProfileView issue (https://github.com/timholy/ProfileView.jl/issues/166)
• FlameGraphs issue (https://github.com/timholy/FlameGraphs.jl/issues/52)

[kongdd]

I am using Julia v1.7.3. Why I have no function Profile.Allocs.@profile?

[gbaraldi]

It's 1.8 and up only unfortunately

[vchuravy]

cc: @vilterp @NHDaly

[KristofferC]

👍 . Was trying to use this today and the docs are quite underwhelming in describing how it should be used.

[gdalle]

Pinging @pfitzseb since the easiest visualization tool might soon be the VSCode extension

[pfitzseb]

The allocation profile viewer should already be in the latest release of the extension (if I didn't mess up while writing the changelog). Should be as simple as a @profview_allocs (but of course we don't have any real documentation either).

[NHDaly]

There are a few things that I would like to see added to the documentation:

• there are multiple visualization tools now (just like with CPU profiles), including:
  • PProf
  • VSCode profile viewer
  • viewing the results directly in the REPL
  • ... others?
• the sample_rate has to be considered carefully (just like with CPU profiling)

Is there anything else that people feel is missing?

[NHDaly]

cc: @bergel

[IanButterworth]

Just a bump because of confusion in the wild https://discourse.julialang.org/t/what-is-wrong-with-this-code/86695

[IanButterworth]

Just a note that the docs should mention clearly shortcomings related to https://github.com/JuliaLang/julia/issues/43688

[vtjnash]

I wrote some code that users can load into Profile.Allocs which works to complete the API with a builtin print function mostly identical to Profile.print, which doesn't need an external tool to be available (though is less interactive than those tools already mentioned here) and can convert from Allocs-format to flat or tree format (including support for most configuration flags): https://gist.github.com/vtjnash/c6aa4db9dafccb0fd28a65f87d6b1adb

[IanButterworth]

@fingolfin helped with https://github.com/JuliaLang/julia/pull/47144

[nickrobinson251]

Maybe we could add the JuliaCon talk by @NHDaly and @vilterp to the docs? e.g. include it at https://docs.julialang.org/en/v1/manual/profile/#Allocation-Profiler

[ojwoodford]

👍 . Was trying to use this today and the docs are quite underwhelming in describing how it should be used.

This section of the docs is still very underwhelming. Some example code is needed.

[NHDaly]

HOKAY - i'm finally taking a stab at improving this, while I'm editing the docs in #50337.

Can you all please take a look and see what else you'd like to add? Thank you! https://github.com/JuliaLang/julia/pull/50337/files#diff-5daf211b5059d9eebb3cea99608a874dfd552ea395cfde31a229141b7720ea90

[NHDaly]

Here's the current Profiling docs page as of that PR: Profiling docs page.zip