-## Tizen Profiler for CoreCLR
-
-This project provdes profiler facility for CoreCLR. It is an implementation of ICorProfilerCallback3 interface.
-Currently tested on ARM, x86-64 and i586 platforms.
-
-## Prerequisites
-In oder to build cross platform CoreCLR on Ubuntu 14.0 one need to follow prerequisites instructions on CoreCLR site:
-https://github.com/dotnet/coreclr/blob/master/Documentation/building/linux-instructions.md
-
-## Build
-The profiler loadable module (libcoreprof.so) is built with gbs.
-
-## Use
-In order to obtain sampling information the Lttng (the same version as in coreclr cross rootfs) should be installed on target.
-
-$ CORECLR_PROFILER={101DA8FE-FDCA-4D0E-9712-7639CDE48EBA} CORECLR_ENABLE_PROFILING=1 CORECLR_PROFILER_PATH=./libcoreprof.so PROF_EXECUTION_TRACE=1 PROF_COLLECT_METHOD=Sampling PROF_LINE_TRACE=1 PROF_TRACE_FILENAME=trace.log ./corerun Program.exe
-
-### Options
-1. PROF_EXECUTION_TRACE=1 – turns tracing on
- a. PROF_COLLECT_METHOD=<Instrumentation|Sampling> – set the trace mode
- i. Instrumentation - trace all ELT events (instrumentation)
- ii. Sampling – aggregate ELT events into samples (stack snapshots, sampling)
- 1. PROF_SAMPLING_TIMEOUT=<time in ms> – sampling time interval (default - 10)
- 2. PROF_HIGH_GRAN=<0|1> – a mode, where (default 1):
- a. if 1, all samples are printed out to a log file with a rate defined in PROF_SAMPLING_TIMEOUT (high-granularity sampling)
- 3. if 0, samples are printed out to a log file in ELT-events only (low-granularity sampling)
- b. PROF_LINE_TRACE=<0|1> – turns the collection on the source lines level on (default 1)
- i. when (PROF_COLLECT_METHOD= Sampling && PROF_HIGH_GRAN=1) , every sample has a source line information for each stack call element
- ii. when (PROF_COLLECT_METHOD=Instrumentation || PROF_COLLECT_METHOD=Sampling && PROF_HIGH_GRAN=0), there is no source line information for top stack element
-2. PROF_MEMORY_TRACE=<0|1> turns on memory tracing (not yet implemented, default 0).
-3. PROF_TRACE_STREAM=<output> - set the output channel of the profiling information, where <output> is:
- a. Stdout – out to stdout (default)
- b. Stderr - out to stderr
- c. File – out to a file
- i. PROF_TRACE_FILENAME=<name of the profiling information file>
-4. PROF_LOG_STREAM=<output> - set the output channel of the log information, where <output> is:
- a. Stdout - out to stdout (default)
- b. Stderr - out to stderr
- c. File - out to a file
- i. PROF_LOG_FILENAME=<name of the log information file>
-5. PROF_LOG_LEVEL=<level> - set the log level, where <level> is:
- a. None – nothing to print
- b. Fatal – print out fatal errors only
- c. Error - print out all errors
- d. Warn – print out warnings
- e. Info - print out info messages
- f. Debug - print out debug messages
- g. Trace - print out all messages
- h. All – same as Trace.
+# Managed code profiler library for .NET Core runtime
+
+This project provides profiling library for CoreCLR that can be used
+to generate tracing data with performance information during managed
+application execution. File with tracing data than can be analyzed using
+compatible profiling tool.
+
+The library uses `ICorProfilerCallback3` and `ICorProfilerInfo4` interfaces
+of CoreCLR to control profilability and obtain profiling information. It also
+uses Linux real-time signals (from `SIGRTMIN + 4` to `SIGRTMIN + 10`)
+for control and communication purposes.
+
+CoreProfiler library currently tested on Linux (x86-64) and Tizen (ARM, x86)
+platforms.
+
+## Building the Repository (Ubuntu 16.04)
+
+In order to build CoreProfiler on Ubuntu 16.04 one need to build CoreCLR
+at first. Follow prerequisites from
+[documentation](https://github.com/dotnet/coreclr/blob/master/Documentation/building/linux-instructions.md)
+on CoreCLR site.
+
+Next instructions describes building of debug and release versions of CoreCLR
+and CoreProfiler. Result of building is `libcoreprof.so` in `install`
+subdirectory (default location can be changed using
+`CMAKE_INSTALL_PREFIX_OVERRIDE` CMake variable).
+
+### Debug Build
+
+```console
+~$ cd ~/coreclr
+~/coreclr$ ./build debug skiptests skipnuget
+~/coreclr$ cd ~/coreprofiler
+~/coreprofiler$ mkdir -p build/debug
+~/coreprofiler$ cd build/debug
+~/coreprofiler/build/debug$ CC=clang-3.9 CXX=clang++-3.9 \
+ cmake ../.. \
+ -DCMAKE_BUILD_TYPE=Debug \
+ -DCLR_SRC_DIR=~/coreclr
+~/coreprofiler/build/debug$ make -j install
+```
+
+### Release Build
+
+```console
+~$ cd ~/coreclr
+~/coreclr$ ./build release skiptests skipnuget
+~/coreclr$ cd ~/coreprofiler
+~/coreprofiler$ mkdir -p build/release
+~/coreprofiler$ cd build/release
+~/coreprofiler/build/release$ CC=clang-3.9 CXX=clang++-3.9 \
+ cmake ../.. \
+ -DCMAKE_BUILD_TYPE=Release \
+ -DCLR_SRC_DIR=~/coreclr
+~/coreprofiler/build/release$ make -j install
+```
+
+## Building the Repository (GBS)
+
+GBS tool should be installed on the system. GBS installation instructions
+can be found
+[here](https://source.tizen.org/documentation/developer-guide/getting-started-guide/installing-development-tools).
+For the following commands it is assumed that the correct `.gbs.conf` file
+can be found by utility in the default location.
+
+Default building configuration is `Release`. You can add
+`--define "buildtype Debug"` to `gbs` options to change building
+configuration type. Additionally use `--overwrite` flag to rebuild previous
+results.
+
+GBS store resulted RPMs and SRPMs at
+`~/GBS-ROOT/local/repos/<distro>/<arch>` directories.
+
+### Build for ARM Tizen TM1 target
+
+```
+~/coreprofiler$ gbs build -P profile.target-TM1.unified -A armv7l
+```
+
+### Build for x86 Tizen emulator
+
+```
+~/coreprofiler$ gbs build -P profile.emulator32.unified -A i586
+```
+
+## Configuration
+
+CoreProfiler is controlled by set of parameters. Currently configuration file
+and/or environment variables can be used as source of the configuration.
+Environment variables takes precedence over parameters specified by the file.
+Environment variables can specify additional parameters to configuration or
+override defined options. Unsetting of configuration parameters
+by environment variables is not supported.
+
+Path to configuration file can be defined by special environment variable
+`PROF_CONFIG_FILENAME`. If parameter is omitted, only environment variables
+and default settings is used.
+
+Configuration file have following syntax: `<name>=<value>`. Configuration
+file use same names of parameters as configuration environment variables.
+Spaces before `=` character is not permitted. Spaces after `=` character
+is part of `<value>`. Quotation is not supported. Empty lines is ignored.
+There is not support for commentaries in configuration file.
+
+For boolean flags values `1`, `true`, `on`, `yes`, `enabled` and empty string
+can be used as True and `0`, `false`, `no`, `disabled` as False.
+
+Here description of different set of parameters.
+
+### Tracing Subsystems
+
+CoreProfiler have different tracing subsystems each of them can be enabled
+separately. By default all subsystems is disabled, and no tracing data is
+dumped (only timestamp of execution and configuration parameters is stored).
+
+ - `PROF_EXECUTION_TRACE` - enables Execution Trace subsystem. The main purpose
+ of this subsystem is to track changes of execution stack.
+ `PROF_EXECUTION_TRACE` is defaulted to `false`.
+
+ - `PROF_MEMORY_TRACE` - enables Memory Trace subsystem. This subsystem
+ collects data about allocations. `PROF_MEMORY_TRACE` is defaulted to
+ `false`.
+
+ - `PROF_STACK_TRACK` - enables tracking of execution stack state for
+ memory allocations. With this option additional samples with stack
+ changes between allocations will be recorded.
+
+ If `PROF_EXECUTION_TRACE` is disabled, only stack states for allocations
+ will be stored.
+
+ If `PROF_EXECUTION_TRACE` is enabled and `PROF_STACK_TRACK` is disabled,
+ no additional samples will be generated.
+
+ This option is enabled by default if `PROF_EXECUTION_TRACE` and
+ `PROF_MEMORY_TRACE` turned on in conjunction for sampling mode (see
+ below).
+
+ - `PROF_GC_TRACE` - enables tracking of GC events. Value of this options is
+ used as default for following options. However, each following
+ option can be turned on or off manually. `PROF_GC_TRACE` is defaulted to
+ `false`.
+
+ - `PROF_GC_TRACE_ALT` - enables tracking of 'Heap Allocation Tables'
+ for each GC invocation. Heap Allocation Table is set of records
+ containing information about objects count and summary memory usage for
+ all classes.
+
+ _Current limitation: `PROF_MEMORY_TRACE` should be enabled to use this
+ option._
+
+ - `PROF_CPU_TRACE` - enables tracking of CPU usage by process and/or managed
+ threads. Value of this options is used as default for both process and
+ threads CPU tracking. However, each of this can be turned on or off
+ manually. `PROF_CPU_TRACE` is defaulted to `false`.
+
+ - `PROF_CPU_TRACE_PROC` - enables tracking of CPU usage by
+ application process.
+ - `PROF_CPU_TRACE_THREAD` - enables tracking of CPU usage by
+ application managed threads.
+ - `PROF_CPU_TRACE_TIMEOUT` - timeout between CPU usage measurements
+ in milliseconds. Default value is `10`.
+
+ _Current limitation: `PROF_EXECUTION_TRACE` or `PROF_MEMORY_TRACE`
+ should also be enabled to use this options._
+
+### Collection Methods
+
+ - `PROF_COLLECT_METHOD` - defines profiler mode for collecting data. Possible
+ values is:
+
+ - `None` - only basic information from runtime collected by subsystems.
+ No stack and allocations tracking is performed. (It is default.)
+ - `Instrumentation` - each event dumped to trace log as separate record.
+ It is slow, but provides detailed information.
+ - `Sampling` - events is grouped to samples. The higher the sampling
+ rate, the lower detailing level and the less application slowdown.
+
+ When `PROF_STACK_TRACK` is enabled, samples can be generated more often
+ than sampling rate (see option description), that can be slow.
+
+ - `PROF_SAMPLING_TIMEOUT` - timeout between samples generation
+ (within the same managed thread) in milliseconds.
+ Default value is `10`.
+
+ - `PROF_HIGH_GRAN` - enables signals generation for better granularity
+ of sampling. If option is disabled, samples dumped only on
+ allocation and stack changing events. This option is enabled by
+ default for `Sampling` mode. Disabling is not recommended
+ (but can be rarely useful for testing purposes).
+
+ _Current limitation: `Instrumentation` mod is not well tested and can cause
+ crashes._
+
+### Obtain information about source lines
+
+ - `PROF_LINE_TRACE` - enables collection of instruction pointers (IP) for
+ samples. Profiler generates information about IL to native code mapping,
+ that can be used for matching between IP and source code fragments.
+
+ This option requires execution and/or memory tracing enabled and sampling or
+ instrumentation profiling mode activated. Default value is `false`.
+
+ CoreProfiler itself doesn't have information about sources,
+ so matching should be done by external tool that requires PDB files with
+ information about symbols.
+
+ CoreProfiler try to collect IP (according to enabled subsystems) when one
+ function calls another, when allocations is occurred, and for the time of
+ sample generation (for high granularity sampling - see `PROF_HIGH_GRAN`
+ option description). Profiler uses context information from signal handlers
+ and stack frames when it is possible.
+
+ _Current limitations: line tracing is not implemented very well and can be
+ issued by ABI changes and other limitations. We need more research for this
+ area._
+
+### Control tracing data stream
+
+ - `PROF_TRACE_STREAM` - defines the output channel for tracing data. Can be
+ one of:
+
+ - `Stdout` - use `stdout` (default);
+ - `Stderr` - use `stderr`;
+ - `File` - use file (see `PROF_TRACE_FILENAME`).
+
+ - `PROF_TRACE_FILENAME` - defines path to output file. `PROF_TRACE_STREAM`
+ should be `File` or unspecified.
+
+### Control logging
+
+ - `PROF_LOG_STREAM` - defines the output channel for log messages. Can be
+ one of:
+
+ - `Stdout` - use `stdout` (default);
+ - `Stderr` - use `stderr`;
+ - `File` - use file (see `PROF_LOG_FILENAME`).
+
+ - `PROF_LOG_FILENAME` - defines path to output file. `PROF_LOG_STREAM`
+ should be `File` or unspecified.
+
+ - `PROF_LOG_LEVEL` - defines minimal log level to printed messages. Possibles
+ values (from maximum to minimum):
+
+ - `None` - nothing to print;
+ - `Fatal` - print out fatal errors only;
+ - `Error` - print out all errors;
+ - `Warn` - print out warning too (default);
+ - `Info` - print out information messages too;
+ - `Debug` - print out debug messages too (not available for Release
+ version);
+ - `Trace` - print out trace messages too (not available for Release
+ version);
+ - `All` - print out all available messages.
+
+### Examples
+
+#### Stack Sampling
+
+```
+PROF_COLLECT_METHOD=Sampling
+PROF_EXECUTION_TRACE=1
+PROF_CPU_TRACE=1
+PROF_LINE_TRACE=1
+PROF_TRACE_FILENAME=trace.log
+```
+
+#### Memory Sampling
+
+```
+PROF_COLLECT_METHOD=Sampling
+PROF_MEMORY_TRACE=1
+PROF_GC_TRACE=1
+PROF_LINE_TRACE=1
+PROF_TRACE_FILENAME=trace.log
+```
+
+#### Complex Sampling
+
+```
+PROF_COLLECT_METHOD=Sampling
+PROF_EXECUTION_TRACE=1
+PROF_CPU_TRACE=1
+PROF_MEMORY_TRACE=1
+PROF_GC_TRACE=1
+PROF_LINE_TRACE=1
+PROF_TRACE_FILENAME=trace.log
+```
+
+## Usage
+
+CoreProfiler is a library loaded by .NET Core Runtime. CoreCLR loads
+profiler if environment variable `CORECLR_ENABLE_PROFILING` is set to `1`.
+`CORECLR_PROFILER_PATH` should define path to `libcoreprof.so` and
+`CORECLR_PROFILER` variable should have value
+`{101DA8FE-FDCA-4D0E-9712-7639CDE48EBA}` (it is GUID of CoreProfiler).
+
+CoreProfiler uses environment variables, files and signals to communicate
+with 'world'. See above detailed description how to control profiler work.
+If no files specified, CoreProfiler outputs tracing data and log messages
+to `stdout`.
+
+### Usage with console apps
+
+To build a console application use dotnet CLI. Its version should be compatible
+with compiled CoreCLR. For example (Ubutntu 16.04):
+
+```console
+~$ curl https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > microsoft.gpg
+~$ sudo mv microsoft.gpg /etc/apt/trusted.gpg.d/microsoft.gpg
+~$ sudo sh -c 'echo "deb [arch=amd64] https://packages.microsoft.com/repos/microsoft-ubuntu-xenial-prod xenial main" > /etc/apt/sources.list.d/dotnetdev.list'
+~$ sudo apt-get update
+~$ sudo apt-get install dotnet-sdk-2.1.300-preview1-008174
+```
+
+Then try to create and build simple application:
+
+```console
+~$ mkdir -p ~/demo/hello && cd ~/demo/hello
+~/demo/hello$ dotnet new console
+~/demo/hello$ dotnet build
+~/demo/hello$ cd bin/Debug/netcoreapp2.1/
+```
+
+You can use bash aliases to simplify run of profiling. Add this lines to
+`~/.bash_aliases` and restart shell:
+
+```bash
+alias corerun_prof='\
+CORE_LIBRARIES=/usr/share/dotnet/shared/Microsoft.NETCore.App/2.1.0-preview1-26216-03/ \
+CORECLR_ENABLE_PROFILING=1 \
+CORECLR_PROFILER={101DA8FE-FDCA-4D0E-9712-7639CDE48EBA} \
+CORECLR_PROFILER_PATH=~/coreprofiler/build/release/install/libcoreprof.so \
+~/coreclr/bin/Product/Linux.x64.Release/corerun'
+
+alias corerun_prof_debug='\
+CORE_LIBRARIES=/usr/share/dotnet/shared/Microsoft.NETCore.App/2.1.0-preview1-26216-03/ \
+CORECLR_ENABLE_PROFILING=1 \
+CORECLR_PROFILER={101DA8FE-FDCA-4D0E-9712-7639CDE48EBA} \
+CORECLR_PROFILER_PATH=~/coreprofiler/build/debug/install/libcoreprof.so \
+~/coreclr/bin/Product/Linux.x64.Debug/corerun'
+```
+
+You can start profiling with command like this:
+
+```console
+~/demo/hello/bin/Debug/netcoreapp2.1$ PROF_CONFIG_FILENAME=~/profiler.cfg corerun_prof hello.dll
+```
+
+If you stored one of exampled above configuration to `~/profiler.cfg`, you
+would get tracing log in `trace.log` file.
projects / sdk / tools / coreprofiler.git / commitdiff