Repository navigation
Add profiling with perf chapter OCaml manual - #13751
Conversation
fc82d6e to
ab7577c
Compare
|
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. |
|
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:
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. |
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: |
|
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 -- PROGRAMI 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. |
|
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. |
7e4f5ed to
e8854da
Compare
|
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?
From a distance my impression is that few people (if any) use ocamlprof anymore (case in point, there is no support for using |
|
Thank you @gasche. I'll reorganise things into a single chapter on Regarding |
6023940 to
8760567
Compare
8760567 to
51431df
Compare
|
@gasche I've merged the sections and added a brief section on Instruments. Please have a look. |
51431df to
8acbd6c
Compare
gasche
left a comment
There was a problem hiding this comment.
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
8acbd6c to
a4bc947
Compare
|
Thanks for the subtle reminder. Merged! |
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.