OLD | NEW |
(Empty) | |
| 1 // Copyright 2015 The Chromium Authors. All rights reserved. |
| 2 // Use of this source code is governed by a BSD-style license that can be |
| 3 // found in the LICENSE file. |
| 4 |
| 5 #ifndef BASE_PROFILER_STACK_SAMPLING_PROFILER_H_ |
| 6 #define BASE_PROFILER_STACK_SAMPLING_PROFILER_H_ |
| 7 |
| 8 #include <string> |
| 9 #include <vector> |
| 10 |
| 11 #include "base/base_export.h" |
| 12 #include "base/callback.h" |
| 13 #include "base/files/file_path.h" |
| 14 #include "base/memory/scoped_ptr.h" |
| 15 #include "base/strings/string16.h" |
| 16 #include "base/threading/platform_thread.h" |
| 17 #include "base/time/time.h" |
| 18 |
| 19 namespace base { |
| 20 |
| 21 // StackSamplingProfiler periodically stops a thread to sample its stack, for |
| 22 // the purpose of collecting information about which code paths are |
| 23 // executing. This information is used in aggregate by UMA to identify hot |
| 24 // and/or janky code paths. |
| 25 // |
| 26 // Sample StackStackSamplingProfiler usage: |
| 27 // |
| 28 // // Create and customize params as desired. |
| 29 // base::StackStackSamplingProfiler::SamplingParams params; |
| 30 // // Any thread's ID may be passed as the target. |
| 31 // base::StackSamplingProfiler profiler(base::PlatformThread::CurrentId()), |
| 32 // params); |
| 33 // |
| 34 // // To process the profiles within Chrome rather than via UMA, set a custom |
| 35 // // completed callback: |
| 36 // base::Callback<void(const std::vector<Profile>&)> |
| 37 // thread_safe_callback = ...; |
| 38 // profiler.SetCustomCompletedCallback(thread_safe_callback); |
| 39 // |
| 40 // profiler.Start(); |
| 41 // // ... work being done on the target thread here ... |
| 42 // profiler.Stop(); // optional, stops collection before complete per params |
| 43 // |
| 44 // When all profiles are complete or the profiler is stopped, if the custom |
| 45 // completed callback was set it will be called from the profiler thread with |
| 46 // the completed profiles. If no callback was set, the profiles are stored |
| 47 // internally and retrieved for UMA through |
| 48 // GetPendingProfiles(). GetPendingProfiles() should never be called by other |
| 49 // code; to retrieve profiles for in-process processing, set a completed |
| 50 // callback. |
| 51 class BASE_EXPORT StackSamplingProfiler { |
| 52 public: |
| 53 // Module represents the module (DLL or exe) corresponding to a stack frame. |
| 54 struct Module { |
| 55 Module(); |
| 56 ~Module(); |
| 57 |
| 58 // Points to the base address of the module. |
| 59 const void* base_address; |
| 60 // An opaque binary string that uniquely identifies a particular program |
| 61 // version with high probability. This is parsed from headers of the loaded |
| 62 // module. |
| 63 // For binaries generated by GNU tools: |
| 64 // Contents of the .note.gnu.build-id field. |
| 65 // On Windows: |
| 66 // GUID + AGE in the debug image headers of a module. |
| 67 std::string id; |
| 68 // The filename of the module. |
| 69 FilePath filename; |
| 70 }; |
| 71 |
| 72 // Frame represents an individual sampled stack frame with module information. |
| 73 struct Frame { |
| 74 Frame(); |
| 75 ~Frame(); |
| 76 |
| 77 // The sampled instruction pointer within the function. |
| 78 const void* instruction_pointer; |
| 79 // Index of the module in the array of modules. We don't represent module |
| 80 // state directly here to save space. |
| 81 int module_index; |
| 82 }; |
| 83 |
| 84 // Sample represents a set of stack frames. |
| 85 using Sample = std::vector<Frame>; |
| 86 |
| 87 // Profile represents a set of samples. |
| 88 struct BASE_EXPORT Profile { |
| 89 Profile(); |
| 90 ~Profile(); |
| 91 |
| 92 std::vector<Module> modules; |
| 93 std::vector<Sample> samples; |
| 94 // Duration of this profile. |
| 95 TimeDelta profile_duration; |
| 96 // Time between samples. |
| 97 TimeDelta sampling_period; |
| 98 // True if sample ordering is important and should be preserved if and when |
| 99 // this profile is compressed and processed. |
| 100 bool preserve_sample_ordering; |
| 101 }; |
| 102 |
| 103 // NativeStackSampler abstracts the native implementation required to record a |
| 104 // stack sample for a given thread. |
| 105 class NativeStackSampler { |
| 106 public: |
| 107 virtual ~NativeStackSampler(); |
| 108 |
| 109 // Create a stack sampler that records samples for |thread_handle|. Returns |
| 110 // null if this platform does not support stack sampling. |
| 111 static scoped_ptr<NativeStackSampler> Create(PlatformThreadId thread_id); |
| 112 |
| 113 // Notify the sampler that we're starting to record a new profile. This |
| 114 // function is called on the SamplingThread. |
| 115 virtual void ProfileRecordingStarting(Profile* profile) = 0; |
| 116 |
| 117 // Record a stack sample. This function is called on the SamplingThread. |
| 118 virtual void RecordStackSample(Sample* sample) = 0; |
| 119 |
| 120 // Notify the sampler that we've stopped recording the current profile. This |
| 121 // function is called on the SamplingThread. |
| 122 virtual void ProfileRecordingStopped() = 0; |
| 123 |
| 124 protected: |
| 125 NativeStackSampler(); |
| 126 |
| 127 private: |
| 128 DISALLOW_COPY_AND_ASSIGN(NativeStackSampler); |
| 129 }; |
| 130 |
| 131 // Represents parameters that configure the sampling. |
| 132 struct BASE_EXPORT SamplingParams { |
| 133 SamplingParams(); |
| 134 |
| 135 // Time to delay before first samples are taken. Defaults to 0. |
| 136 TimeDelta initial_delay; |
| 137 // Number of sampling bursts to perform. Defaults to 1. |
| 138 int bursts; |
| 139 // Interval between sampling bursts. This is the desired duration from the |
| 140 // start of one burst to the start of the next burst. Defaults to 10s. |
| 141 TimeDelta burst_interval; |
| 142 // Number of samples to record per burst. Defaults to 300. |
| 143 int samples_per_burst; |
| 144 // Interval between samples during a sampling burst. This is the desired |
| 145 // duration from the start of one burst to the start of the next |
| 146 // burst. Defaults to 100ms. |
| 147 TimeDelta sampling_interval; |
| 148 // True if sample ordering is important and should be preserved if and when |
| 149 // this profile is compressed and processed. Defaults to false. |
| 150 bool preserve_sample_ordering; |
| 151 }; |
| 152 |
| 153 StackSamplingProfiler(PlatformThreadId thread_id, |
| 154 const SamplingParams& params); |
| 155 ~StackSamplingProfiler(); |
| 156 |
| 157 // Initializes the profiler and starts sampling. |
| 158 void Start(); |
| 159 // Stops the profiler and any ongoing sampling. Calling this function is |
| 160 // optional; if not invoked profiling will terminate when all the profiling |
| 161 // bursts specified in the SamplingParams are completed. |
| 162 void Stop(); |
| 163 |
| 164 // Gets the pending profiles into *|profiles| and clears the internal |
| 165 // storage. This function is thread safe. |
| 166 // |
| 167 // ***This is intended for use only by UMA.*** Callers who want to process the |
| 168 // collected profiles should use SetCustomCompletedCallback. |
| 169 static void GetPendingProfiles(std::vector<Profile>* profiles); |
| 170 |
| 171 // By default, collected profiles are stored internally and can be retrieved |
| 172 // by GetPendingProfiles. If a callback is provided via this function, |
| 173 // however, it will be called with the collected profiles instead. Note that |
| 174 // this call to the callback occurs *on the profiler thread*. |
| 175 void SetCustomCompletedCallback( |
| 176 Callback<void(const std::vector<Profile>&)> callback); |
| 177 |
| 178 private: |
| 179 class SamplingThread; |
| 180 struct SamplingThreadDeleter { |
| 181 void operator() (SamplingThread* thread) const; |
| 182 }; |
| 183 |
| 184 // The thread whose stack will be sampled. |
| 185 PlatformThreadId thread_id_; |
| 186 |
| 187 const SamplingParams params_; |
| 188 |
| 189 scoped_ptr<SamplingThread, SamplingThreadDeleter> sampling_thread_; |
| 190 scoped_ptr<NativeStackSampler> native_sampler_; |
| 191 |
| 192 Callback<void(const std::vector<Profile>&)> custom_completed_callback_; |
| 193 |
| 194 DISALLOW_COPY_AND_ASSIGN(StackSamplingProfiler); |
| 195 }; |
| 196 |
| 197 // Defined to allow equality check of Samples. |
| 198 BASE_EXPORT bool operator==(const StackSamplingProfiler::Frame& a, |
| 199 const StackSamplingProfiler::Frame& b); |
| 200 // Defined to allow ordering of Samples. |
| 201 BASE_EXPORT bool operator<(const StackSamplingProfiler::Frame& a, |
| 202 const StackSamplingProfiler::Frame& b); |
| 203 |
| 204 } // namespace base |
| 205 |
| 206 #endif // BASE_PROFILER_STACK_SAMPLING_PROFILER_H_ |
OLD | NEW |