Profiling API Documentation: ELT APIs (SetEnterLeaveFunctionHooks*, etc.) do not work on MacOSX

[mjsabby]

I couldn't find any evidence of the stubs that are required for ELT to function properly in Linux and/or MacOSX x64

It's best if we document that this can/will fail the target process spectacularly, i.e. the profiler author must not pass COR_PRF_MONITOR_ENTERLEAVE to SetEventMask. Particularly because SetEventMask may succeed (I vaguely remember it did in fact succeed in my testing) and that the program from then on may be exhibiting undefined behavior.

I'll open a separate issue to track the fact this work needs to happen for our currently supported platforms.

[mjsabby]

cc @noahfalk @kspawa

[mjsabby]

Actually the JIT issue is being tracked as #5032

[noahfalk]

Thanks for the heads up!

@kspawa commented in #4033 that we only support a small subset of the flags so far. She was planning to get that statement of support posted as a doc so it will be a little more obvious... I have no expectation that all our profiler devs are going to read every comment on every issue with profiler in the title : )

Unfortunately one of the dangers of letting devs use APIs before we've thoroughly tested them is that you can accidentally wander into failures like this one. We are hoping on balance the danger is a reasonable cost to pay for that freedom to explore, but certainly I want to keep an eye on it and feedback is encouraged. If it causes too much trouble we can be more aggresive about blocking profiler APIs until testing has proven they are functional on .Net Core.

[lt72]

This work item requires at least a few preliminary explorations and activities

• frame exactly what is working and what is not working for profiling on MacOS
• define a target and add appropriate test set
• implement missing features as needed, ELT callbacks being one of them

[sywhang]

I am in progress of testing the profiler APIs on macOS. Here is a list of the tests in the process of being brought up: (checked means they've been brought up AND are all passing the internal profiler tests)

• CEE
• LTS
• ReJIT
• ELT
• InjectMetaData
• Unit
• JIT

[sywhang]

Internal testing revealed an issue with ReJIT on MacOS, but apart from that, the ELT APIs are fully functional and have been tested on macOS. The change that enabled this is dotnet/coreclr#12603, which enabled it for AMD64/Linux, but macOS is thankfully only on x64 architecture so this enabled the ELT callbacks on macOS as well.

I will follow up with a PR to update the Profiler API documentation on this repo to update this recent progress.

[EDIT] ReJIT issue is actually an issue with our testing infra.

Will be marking this issue as solved, since ELT callbacks are fully functional.

[dotnetjt]

@sywhang - any code sample for using the ELT callbacks? I'm not great with assembler....

[sywhang]

Hey @dotnetjt,

Here is a sample profiler that uses the Enter/Leave callbacks: https://github.com/Microsoft/clr-samples/tree/master/ProfilingAPI/ReJITEnterLeaveHooks.

[noahfalk]

The sample you mentioned is using ReJIT to simulate the same effect as ELT, but it doesn't use the ELT APIs actually. Unfortunately I'm not aware of a good sample for ELT itself, but using ReJIT to accomplish the same task might still work well for you if you want to stay clear of writing your own assembly.

[sywhang]

dotnet/coreclr#15659 updated the outdated docs. Closing the issue.

[tig66208]

Yes @noahfalk you are right. But it's ok, I figured it out using the ELT hooks.

The challenge is that I maintain a profiler that has been based on Windows only for a long time. There were plenty of examples to go off of for that, and MASM integrated with VS/MSBUILD was the way to go.

In the examples given to me prior on different issues in this repo ("look at asmhelpers.S"), there is a huge gap: I don't know the coreclr repo / build process well. The example made sense on paper, but I've been used to using MASM on Windows, and took me a lot of trial, error, and digging to realize that the file suggested for reference was using intel syntax with GCC (rather than NASM or GAS; not to mention this sample profiler above referenced uses clang). But, I now have it working.

All that to say; for those of us that have built tooling around the APIs provided in the original, full framework, the tools were at least familiar and we could make it work. In this new world, some of us are having to learn a lot of new things - and I think this entire repo could use a lot more "how to" for people like myself (I can pull it and build it..... and use the output). But the build process / tool chain / test projects, etc are a steep learning curve. I've learned a lot more from 3rd parties / bloggers than I have from the project itself. I think you'd have a lot more people contributing if they understood these things better - .net developers are fairly stuck in a certain ecosystem, and getting them to contribute to something where they have little to no knowledge of the tooling, etc, is difficult.

[mattwarren]

@noahfalk

Unfortunately I'm not aware of a good sample for ELT itself,

What about the CLR Profiler sample (previously on CodePlex) or is that too out of date?

After a quick glance is seems to have the ELT hooks implemented, i.e.

• https://github.com/MicrosoftArchive/clrprofiler/tree/master/CLRProfiler/profilerOBJ/amd64
• https://github.com/MicrosoftArchive/clrprofiler/blob/master/CLRProfiler/profilerOBJ/ProfilerCallback.cpp#L173-L188