Documentation/project-docs/linux-performance-tracing.md

   1 Performance Tracing on Linux
   2 ============================
   3
   4 When a performance problem is encountered on Linux, these instructions can be used to gather detailed information about what was happening on the machine at the time of the performance problem.
   5
   6 #Required Tools#
   7 - **perfcollect**: Bash script that automates data collection.
   8         - Available at <http://aka.ms/perfcollect>.
   9 - **PerfView**: Windows-based performance tool that can also analyze trace files collected with Perfcollect.
  10         - Available at <http://aka.ms/perfview>.
  11
  12 #Preparing Your Machine#
  13 Follow these steps to prepare your machine to collect a performance trace.
  14
  15 1. Download Perfcollect.
  16
  17         > ```bash
  18         > curl -OL http://aka.ms/perfcollect
  19         > ```
  20
  21 2. Make the script executable.
  22
  23         > ```bash
  24         > chmod +x perfcollect
  25         > ```
  26
  27 3. Install tracing prerequisites - these are the actual tracing libraries.  For details on prerequisites, see [below](#prerequisites).
  28
  29         > ```bash
  30         > sudo ./perfcollect install
  31         > ```
  32
  33 #Collecting a Trace#
  34 1. Have two shell windows available - one for controlling tracing, referred to as **[Trace]**, and one for running the application, referred to as **[App]**.
  35 2. **[App]** Setup the application shell - this enables tracing configuration inside of CoreCLR.
  36
  37         > ```bash
  38         > export COMPlus_PerfMapEnabled=1
  39         > export COMPlus_EnableEventLog=1
  40         > ```
  41
  42 3. **[Trace]** Start collection.
  43
  44         > ```bash
  45         > sudo ./perfcollect collect sampleTrace
  46         > ```
  47
  48         Expected Output:
  49
  50         > ```bash
  51         > Collection started.  Press CTRL+C to stop.
  52         > ```
  53
  54 4. **[App]** Run the app - let it run as long as you need to in order to capture the performance problem.  Generally, you don't need very long.  As an example, for a CPU investigation, 5-10 seconds of the high CPU situation is usually enough.
  55
  56         > ```bash
  57         > dotnet run
  58         > ```
  59
  60 5. **[Trace]** Stop collection - hit CTRL+C.
  61
  62         > ```bash
  63         > ^C
  64         > ...STOPPED.
  65         >
  66         > Starting post-processing. This may take some time.
  67         >
  68         > Generating native image symbol files
  69         > ...SKIPPED
  70         > Saving native symbols
  71         > ...FINISHED
  72         > Exporting perf.data file
  73         > ...FINISHED
  74         > Compressing trace files
  75         > ...FINISHED
  76         > Cleaning up artifacts
  77         > ...FINISHED
  78         >
  79         > Trace saved to sampleTrace.trace.zip
  80         > ```
  81
  82         The compressed trace file is now stored in the current working directory.
  83
  84 #Collecting in a Docker Container#
  85 Perfcollect can be used to collect data for an application running inside a Docker container.  The main thing to know is that collecting a trace requires elevated privileges because the [default seccomp profile](https://docs.docker.com/engine/security/seccomp/) blocks a required syscall - perf_events_open.
  86
  87 In order to use the instructions in this document to collect a trace, spawn a new shell inside the container that is privileged.
  88
  89 >```bash
  90 >docker exec -it --privileged <container_name> /bin/bash
  91 >```
  92
  93 Even though the application hosted in the container isn't privileged, this new shell is, and it will have all the privileges it needs to collect trace data.  Now, simply follow the instructions in [Collecting a Trace](#collecting-a-trace) using the privileged shell.
  94
  95 If you want to try tracing in a container, we've written a [demo Dockerfile](https://raw.githubusercontent.com/dotnet/corefx-tools/master/src/performance/perfcollect/docker-demo/Dockerfile) that installs all of the performance tracing pre-requisites, sets the environment up for tracing, and starts a sample CPU-bound app.
  96
  97 #Filtering#
  98 Filtering is implemented on Windows through the latest mechanisms provided with the [EventSource](https://msdn.microsoft.com/en-us/library/system.diagnostics.tracing.eventsource(v=vs.110).aspx) class.
  99
 100 On Linux those mechanisms are not available yet. Instead, there are two environment variables that exist just on linux to do some basic filtering.
 101
 102 * COMPLUS_EventSourceFilter – filter event sources by name
 103 * COMPLUS_EventNameFilter – filter events by name
 104
 105 Setting one or both of these variables will only enable collecting events that contain the name you specify as a substring. Strings are treated as case insensitive.
 106
 107 #Viewing a Trace#
 108 Traces are best viewed using PerfView on Windows.  Note that we're currently looking into porting the analysis pieces of PerfView to Linux so that the entire investigation can occur on Linux.
 109
 110 ##Open the Trace File##
 111 1. Copy the trace.zip file from Linux to a Windows machine.
 112 2. Download PerfView from <http://aka.ms/perfview>.
 113 3. Run PerfView.exe
 114
 115         > ```cmd
 116         > PerfView.exe <path to trace.zip file>
 117         > ```
 118
 119 ##Select a View##
 120 PerfView will display the list of views that are supported based on the data contained in the trace file.
 121
 122 - For CPU investigations, choose **CPU stacks**.
 123 - For very detailed GC information, choose **GCStats**.
 124 - For per-process/module/method JIT information, choose **JITStats**.
 125 - If there is not a view for the information you need, you can try looking for the events in the raw events view.  Choose **Events**.
 126
 127 For more details on how to interpret views in PerfView, see help links in the view itself, or from the main window in PerfView choose **Help->Users Guide**.
 128
 129 #Extra Information#
 130 This information is not strictly required to collect and analyze traces, but is provided for those who are interested.
 131
 132 ##Prerequisites##
 133 Perfcollect will alert users to any prerequisites that are not installed and offer to install them.  Prerequisites can be installed automatically by running:
 134
 135 >```bash
 136 >sudo ./perfcollect install
 137 >```
 138
 139 The current prerequisites are:
 140
 141 1. perf: Also known as perf_event, the Linux Performance Events sub-system and companion user-mode collection/viewer application.  perf is part of the Linux kernel source, but is not usually installed by default.
 142 2. LTTng: Stands for "Linux Tracing Toolkit Next Generation", and is used to capture event data emitted at runtime by CoreCLR.  This data is then used to analyze the behavior of various runtime components such as the GC, JIT and thread pool.