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 (Allocation profiler #42768)
• PProf support PR (Add support for the Allocs profiles produced by Julia's Allocs Profiler JuliaPerf/PProf.jl#46)
• ProfileView issue (Feature request: memory flame graphs timholy/ProfileView.jl#166)
• FlameGraphs issue (FlameGraphs for memory profiler? timholy/FlameGraphs.jl#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 #43688