Skip to content

Add profiling with perf chapter OCaml manual - #13751

Merged
gasche merged 2 commits into
ocaml:trunkfrom
tmcgilchrist:perf_manual
Apr 17, 2025
Merged

gasche merged 2 commits into
ocaml:trunkfrom
tmcgilchrist:perf_manual

Conversation

@tmcgilchrist

Copy link
Copy Markdown
Contributor

This covers the use of Linux perf to profile OCaml native code including the overlap with frame pointers and DWARF CFI information.

The intention is to gather information from various sources (0, 1, 2) and provide clear documentation on using Linux perf with OCaml programs. Hopefully this PR accurately summarises those sources. Please read and comment if I've missed something that should be included.

Comment thread manual/src/allfiles.etex Resolved
Comment thread manual/src/cmds/Makefile Resolved
@gasche

gasche commented Jan 23, 2025

Copy link
Copy Markdown
Member

I read the documentation and found it clear and helpful. I think it would have been useful for me a few years ago, and I'm sure it will help many programmers in the future. I would be in favor of merging this -- and would not be against reading other similar guides from @tmcgilchrist.

I could see a discussion of whether this really fits well with the rest of the user manual -- it is less about OCaml and more about linux perf tooling. I don't have a strong opinion there, and still believe this document is useful to have somewhere. One downside is that it is going to become stale sensibly faster than other parts of the manual, at a pace that we may not control.

I wonder if @xavierleroy has a preference about this -- he has a clearer view of what the reference manual should and should not have.

@xavierleroy

xavierleroy commented Jan 27, 2025 •

Copy link
Copy Markdown
Contributor

Generally speaking, this is the kind of material that I would expect to find in a guide on https://ocaml.org/docs . Indeed, there is a "Profiling" page here that mentions ocamlcp, Linux perf, and macOS Instrument, but with little details and after a long essay on the assembly code produced by ocamlopt that doesn't belong in a page titled "Profiling". So, I think we should discuss with the ocaml.org people to choose between:

  • incorporate @tmcgilchrist 's detailed explanations of how to use perf in a better Profiling guide on ocaml.org;
  • put these explanations in the reference manual, as proposed in this PR.

In the latter case, I'd argue to add the material to the existing Profiling chapter of the manual, and to add instructions for using Instrument on macOS.

@dbuenzli

Copy link
Copy Markdown
Contributor

the manual, and to add instructions for using Instrument on macOS.

Note that these instructions can be provided as a cli invocation which is often more convenient than using the user interface, especially for invoking your binary with different arguments.

The impossible to remember rune is:

xcrun xctrace record --template='Time Profiler' --launch -- myprog ARG…

@tmcgilchrist

Copy link
Copy Markdown
Contributor Author

I can see arguments for including this in either location.

The reason why I went for a chapter in the manual is the details about needing frame pointers to get accurate profiling are compiler specific. In future when we get better DWARF information then the parts that apply to profiling belong alongside that information. Plus this material feels equivalent to the bytecode profiling chapter https://ocaml.org/manual/5.3/profil.html.

The existing Profiling guide on ocaml.org doesn't address how I would approach profiling an application and seems more suited for a newcomer to the language. As an Ops person, who might not have written the application or know OCaml, I just want to know how to make it work with existing profilers.

@dbuenzli Cli invocation of Instruments is the right way to do it. I've used this invocation:

xcrun xctrace record --output . --template "Time Profiler" \
--target-stdout - --launch -- PROGRAM

I suspect that Instruments works best with frame pointer support but I haven't spent enough time to find where it breaks for OCaml programs. The fact that macOS ABI documentation recommend maintaining frame pointers strongly suggests we should too.

@OlivierNicole

Copy link
Copy Markdown
Contributor

Given the importance of the topic and the compiler-specific details involved, it would make sense to me if the page was in the OCaml manual, especially given that there is already a page about ocamlprof.

@tmcgilchrist
tmcgilchrist force-pushed the perf_manual branch 2 times, most recently from 7e4f5ed to e8854da Compare February 11, 2025 01:00
@gasche

gasche commented Feb 11, 2025

Copy link
Copy Markdown
Member

Okay, I would propose to move forward with the idea of integrating this content in the existing Profiling chapter. This may require some reorganization of the existing chapter, moving sections into subsections to make space. Maybe something like this?

  1. Execution counts with ocamlprof
  2. Linux profiling with perf
  3. OSX profiling with Instruments
    (This would be only a fairly small blurb for now, filling it out is outside the scope of this PR.)

From a distance my impression is that few people (if any) use ocamlprof anymore (case in point, there is no support for using ocamlprof in Dune, see ocaml/dune#398 ), so we might even want to discuss eventually removing that subsection and the tool itself. But this is a larger discussion and orthogonal to the present PR, so for now I would focus on finding a good place for the newly proposed content.

Comment thread manual/src/cmds/profile-perf.etex Resolved
@tmcgilchrist

Copy link
Copy Markdown
Contributor Author

Thank you @gasche. I'll reorganise things into a single chapter on Profiling with sub-sections. For Instruments, it has the same requirements from the compiler that perf does so it will just be a brief paragraph. Anything more detailed deserves a blog post or page on ocaml.org somewhere.

Regarding ocamlprof there are better ways (using eBPF/Dtrace) to get this information without needing to recompile the binary. That is what I use instead of ocamlprof.

@dra27 dra27 added this to the 5.4 features milestone Feb 12, 2025
@tmcgilchrist
tmcgilchrist force-pushed the perf_manual branch 2 times, most recently from 6023940 to 8760567 Compare February 17, 2025 04:03
@tmcgilchrist

Copy link
Copy Markdown
Contributor Author

@gasche I've merged the sections and added a brief section on Instruments. Please have a look.

@gasche gasche left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry for the long delay in looking at this. Personally I am happy with the new state of the PR, where the documentation on perf is included in the Profiling chapter. There is also some new documentation on Instruments for osx users.

I approve. I will not merge immediately to give an opportunity to others to give their opinion if they wish.

This covers the use of Linux perf to profile OCaml native code
including the overlap with frame pointers and DWARF CFI information
@gasche
gasche merged commit 197fb86 into ocaml:trunk Apr 17, 2025
@gasche

gasche commented Apr 17, 2025

Copy link
Copy Markdown
Member

Thanks for the subtle reminder. Merged!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

7 participants