Add a performance measuring top-level user guide page

[malteneuss]

Another step of the user guide improvement initiative #9214:

Add a simple profiling user-guide page based on https://discourse.haskell.org/t/ghc-profiling-a-cabal-project-with-an-interactive-application/10465/2?u=malteneuss, which the author allowed us to use.

Feel free to modify yourself if that is faster.

• Patches conform to the coding conventions.
• Is this a PR that fixes CI? If so, it will need to be backported to older cabal release branches (ask maintainers for directions).

[Kleidukos]

Thanks a bunch for starting this. Several things:

• I would recommend that you make use of the ghc-prof-options key, which is used like this:

ghc-prof-options: -fprof-auto -fno-prof-count-entries -fprof-auto-calls

• You mention Speedscope and the -pj format. Is the JSON produced by -pj natively understood by Speedscope? Or do you still need something like https://github.com/mpickering/hs-speedscope ?

[malteneuss]

Thanks for the quick review @Kleidukos and @geekosaur. I've added all your review remarks. Yes, the json output can be loaded into speedscope directly. This https://github.com/mpickering/hs-speedscope only deals with eventlog files, which irrc is another profiling report format to analyze memory consumption (some topic for a future section in this guide), although it also measures cpu performance.

[tchoutri]

@malteneuss Much better, only two more changes to make and we should be good to go! :)

[jasagredo]

My understanding is that eventlog profiling is far superior than just -pj, and it is (for recent GHCs) just a matter of passing -l -p instead (or if a smaller eventlog is wanted -l-agu -p). I have personally never used the json profiling report.

[malteneuss]

@jasagredo Do you have a link to a post or blog that discusses the differences? I have never used it. Would you like to add a second section showing how to use it in another MR? I think we should add another section for profiling memory, where eventlog should be discussed after all.

[ulysses4ever]

Thank you for taking this on! It's amazing to see efforts in expanding the guide section! I have certain critique below but, please, realize that documentation is a matter where reasonable people can disagree. I can survive the current version, especially given that you already got the mandatory two approvals.

IMO the text uses a cabal workflow that is suboptimal. In particular:

1. It advocates for explicit cabal build, while you never need an explicit build in simple scenarios (including profiling). You should use cabal run where possible and rely on cabal to manage (re)compilation.

2. (In part, because of (1)) it has to use $(cabal list-bin my-app) in an earlier, supposedly lighter subsection. This is long (i.e. annoying), quite platform-dependent (i.e. it assumes bash; I normally don't use bash even under Linux, for instance), and perfectly avoidable (see below).

3. In an earlier, supposedly lighter subsection, it mentions adding profiling-related GHC options in a cabal file. Even though it's done as a note, this idea comes too early (advanced options should come later) and also gives a bad advice (you shouldn'g use cabal file for it -- a project file is the right place).

I propose solving most (all) of these with the following reformatting.

• Start with cabal configure and explain that it creates cabal.project.local with local configuration.
• Now, simply cabal run works.
• Now you can mention the advanced GHC options. You are able to put them in the local project file at this point. Optionally, you could have a little subsection at the very end instead of here. You could also say two words why these options are good in there.
• Now comes the section Profiling your dependencies too.

[ulysses4ever]

I temporarily block it to make sure you have enough time to respond.

[jasagredo]

Re-reading the document again I am unsure this describes Cabal's job on profiling. I think the section should be more about what options does cabal need to enable profiling than how to produce a profiling report, therefore I think the title is misleading and we are stepping into GHC's User Guide territory.

My suggestion would be to leave most of the description and RTS options to the GHC User guide and describe only the following in the text:

• A brief explanation on why building for profiling is different (one has to link to the profiling RTS and insert cost-centres)
• How to enable profiling (either via flag or via cabal.project)
• The different options to enable profiling (library-vanilla for example)
• The different customizations cabal provides (like profiling-detail which uses different names than GHC) and how they map to GHC options
• How to pass other GHC profiling options.
• How to enable profiling for specific dependencies or for all dependencies.
• The usual caveats (for example I build with --enable-profiling, then using only run will re-build without profiling because the flags used during building are not persistent)

This way the choice of p vs pj, or what files are produced or where to load them is deferred to the User Guide, as it is GHC-specific business.

This way we don't mix "How to profile" and "How to configure for profiling". The latter is Cabal's job, but the former is GHC or general Haskell information which should not live in Cabal's docs I think. It will always be too specific or too general what you can say there and it might depend on GHC versions and so on.

[Mikolaj]

OTOH, for some users a full example session of profiling would be immensely valuable and precisely what they are looking for, in despair reaching even for the cabal documentation. So maybe at least link to the original discourse post, saying it contains practical examples, including how to tweak GHC to profile best, which is out of scope of the cabal guide?

[malteneuss]

I fixed the typos. Further changes, especially to other pages, should go to separate MRs.

[AndreasPK]

I've left some comments for accuracy/brevity. But this is good work!

[ulysses4ever]

@AndreasPK I don't see your comments.

[geekosaur]

Nor do I. Did you actually submit them, or leave them pending?

[AndreasPK]

Seems they were pending :)

[ulysses4ever]

Thanks!

I remove the merge label until the comments are resolved.

[geekosaur]

That's not really necessary; since they're conversations on specific lines, they count as unresolved and GitHub won't allow merging (see the big red "Unresolved conversations" box). It's comments like this one that don't count because they're not considered review comments.

[ulysses4ever]

@geekosaur i thought it’s only respected by GitHub, not Mergify. But good to know, thanks.

[geekosaur]

It's part of the branch protection rules, which Mergify copies into its own rules. See the first checkbox in the "merge+no rebase" ruleset in the Mergify summary check. (ETA: whoops, wrong PR, it's the "squash+merge me" ruleset in this case.)

[AndreasPK]

Seems all my points have been addressed. It seems I can't resolve the conversation as it's outdated perhaps? Anyway from my POV this looks good now :)