Skip to content
Permalink
Browse files

Update profiling API status (#14644)

We've been making progress testing APIs and fixing issues. The description in this doc had gotten well out of date.
  • Loading branch information
noahfalk committed Oct 21, 2017
1 parent 3efcbe5 commit d33b8ea1e95412108c0a2d56143356f0a5a51709
Showing with 10 additions and 69 deletions.
  1. +10 −69 Documentation/project-docs/profiling-api-status.md
@@ -1,80 +1,21 @@
# Status of CoreCLR Profiler APIs

The notes below will help you determine what profiling APIs are safe to use. The .NET Core project started with the codebase from the desktop CoreCLR/Silverlight so all the profiler APIs present there are also present in the code here. However that doesn't automatically imply that they are all working or being actively tested right now. Our goal is to eventually have everything tested and working across all the supported OSes. As we make progress we'll document it here. If you want to use APIs that we haven't tested yet you are welcome to do so, but you need to do your own testing to determine whether they work. If you do test APIs we haven't gotten to yet, we hope you'll add a note below in the Community Tested API section so that everyone can benefit.
The .NET Core project started with the codebase from the desktop CoreCLR/Silverlight so all the profiler APIs present there are also present in the code here. This is the status of our testing and porting efforts for these APIs.

# Microsoft Tested APIs:
## Platform test coverage

### Windows
Windows and Linux x86/x64 have been covered. Arm32 is in progress at this time, OSX coming soon (please let us know if you have a pressing issue)

* ICorProfilerCallback:
* `Initialize`
* `ModuleLoadFinished`
* `ModuleUnloadStarted`
* `ModuleUnloadFinished`
* `ModuleAttachedToAssembly`
* `JITCompilationStarted`
## Known issues

* ICorProfilerInfo:
* `GetModuleInfo`
* `GetModuleMetaData`*
* `GetModuleInfo`
* `GetModuleInfo2`
* `GetFunctionInfo`
* `SetILFunctionBody`*
* `SetILInstrumentedCodeMap`*
* `GetILFunctionBodyAllocator`*
* `GetRuntimeInformation`
* `SetEventMask`
### DoStackSnapshot

* The flags tested for SetEventMask are:
* `COR_PRF_MONITOR_MODULE_LOADS`
* `COR_PRF_MONITOR_JIT_COMPILATION`
* `COR_PRF_DISABLE_INLINING`
The implementation of this API was making some questionable assumptions about Windows OS API behavior in order to walk callstacks asynchronously. When operating in this async mode we aren't yet confident we can produce reasonable implementations for other platforms. Our understanding is that most users of this API are attempting to do sample based profiling. If so we think it may be easier to offer a runtime provided event stream of sample callstacks to accomplish the same scenario without needing the API, but we also haven't heard any demand for it. Feedback welcome!

\* Instrumentation APIs have not been tested on assemblies compiled with Ready2Run technology. Ready2Run is currently used
for all Framework assemblies.

### Linux
### OS X
### Profiler does not disable Concurrent GC

# Community Tested APIs (please include GitHub handle)
See github issue [#13153](https://github.com/dotnet/coreclr/issues/13153) for more details.

### Windows
* IProfilerCallback
* ModuleLoadStarted (noahfalk on behalf of one of our vendors)
* JITCompilationStarted (noahfalk on behalf of one of our vendors)
* IMetaDataEmit
* various DefineXXX methods (noahfalk on behalf of one of our vendors)
* IMetadataDataDispenserEx
* OpenScopeOnMemory (noahfalk on behalf of one of our vendors)
* IMetaDataTables (noahfalk on behalf of one of our vendors)
* IMetaDataAssemblyEmit
* DefineAssemblyRef (noahfalk on behalf of one of our vendors)

### Linux
### OS X
### Any issues we missed?

# APIs definitely known not to work yet
### Windows
### Linux

* ICorProfilerInfo:
* `SetEnterLeaveFunctionHooks`

* ICorProfilerInfo2:
* `SetEnterLeaveFunctionHooks2`

* SetEventMask Flags that currently result in undefined behavior :
* `COR_PRF_USE_PROFILE_IMAGES`
* `COR_PRF_REQUIRE_PROFILE_IMAGE`

### OS X
* ICorProfilerInfo:
* `SetEnterLeaveFunctionHooks`

* ICorProfilerInfo2:
* `SetEnterLeaveFunctionHooks2`

* SetEventMask Flags that currently result in undefined behavior :
* `COR_PRF_USE_PROFILE_IMAGES`
* `COR_PRF_REQUIRE_PROFILE_IMAGE`
Please let us know and we will get it addressed. Thanks!

0 comments on commit d33b8ea

Please sign in to comment.
You can’t perform that action at this time.