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.
5 #ifndef BASE_PROFILER_STACK_SAMPLING_PROFILER_H_
6 #define BASE_PROFILER_STACK_SAMPLING_PROFILER_H_
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"
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.
26 // Sample StackStackSamplingProfiler usage:
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()),
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);
41 // // ... work being done on the target thread here ...
42 // profiler.Stop(); // optional, stops collection before complete per params
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
51 class BASE_EXPORT StackSamplingProfiler
{
53 // Module represents the module (DLL or exe) corresponding to a stack frame.
54 struct BASE_EXPORT Module
{
56 Module(const void* base_address
, const std::string
& id
,
57 const FilePath
& filename
);
60 // Points to the base address of the module.
61 const void* base_address
;
62 // An opaque binary string that uniquely identifies a particular program
63 // version with high probability. This is parsed from headers of the loaded
65 // For binaries generated by GNU tools:
66 // Contents of the .note.gnu.build-id field.
68 // GUID + AGE in the debug image headers of a module.
70 // The filename of the module.
74 // Frame represents an individual sampled stack frame with module information.
75 struct BASE_EXPORT Frame
{
77 Frame(const void* instruction_pointer
, int module_index
);
80 // The sampled instruction pointer within the function.
81 const void* instruction_pointer
;
82 // Index of the module in the array of modules. We don't represent module
83 // state directly here to save space.
87 // Sample represents a set of stack frames.
88 using Sample
= std::vector
<Frame
>;
90 // Profile represents a set of samples.
91 struct BASE_EXPORT Profile
{
95 std::vector
<Module
> modules
;
96 std::vector
<Sample
> samples
;
97 // Duration of this profile.
98 TimeDelta profile_duration
;
99 // Time between samples.
100 TimeDelta sampling_period
;
101 // True if sample ordering is important and should be preserved if and when
102 // this profile is compressed and processed.
103 bool preserve_sample_ordering
;
106 // NativeStackSampler abstracts the native implementation required to record a
107 // stack sample for a given thread.
108 class NativeStackSampler
{
110 virtual ~NativeStackSampler();
112 // Create a stack sampler that records samples for |thread_handle|. Returns
113 // null if this platform does not support stack sampling.
114 static scoped_ptr
<NativeStackSampler
> Create(PlatformThreadId thread_id
);
116 // Notify the sampler that we're starting to record a new profile. This
117 // function is called on the SamplingThread.
118 virtual void ProfileRecordingStarting(Profile
* profile
) = 0;
120 // Record a stack sample. This function is called on the SamplingThread.
121 virtual void RecordStackSample(Sample
* sample
) = 0;
123 // Notify the sampler that we've stopped recording the current profile. This
124 // function is called on the SamplingThread.
125 virtual void ProfileRecordingStopped() = 0;
128 NativeStackSampler();
131 DISALLOW_COPY_AND_ASSIGN(NativeStackSampler
);
134 // Represents parameters that configure the sampling.
135 struct BASE_EXPORT SamplingParams
{
138 // Time to delay before first samples are taken. Defaults to 0.
139 TimeDelta initial_delay
;
140 // Number of sampling bursts to perform. Defaults to 1.
142 // Interval between sampling bursts. This is the desired duration from the
143 // start of one burst to the start of the next burst. Defaults to 10s.
144 TimeDelta burst_interval
;
145 // Number of samples to record per burst. Defaults to 300.
146 int samples_per_burst
;
147 // Interval between samples during a sampling burst. This is the desired
148 // duration from the start of one burst to the start of the next
149 // burst. Defaults to 100ms.
150 TimeDelta sampling_interval
;
151 // True if sample ordering is important and should be preserved if and when
152 // this profile is compressed and processed. Defaults to false.
153 bool preserve_sample_ordering
;
156 StackSamplingProfiler(PlatformThreadId thread_id
,
157 const SamplingParams
& params
);
158 ~StackSamplingProfiler();
160 // Initializes the profiler and starts sampling.
162 // Stops the profiler and any ongoing sampling. Calling this function is
163 // optional; if not invoked profiling will terminate when all the profiling
164 // bursts specified in the SamplingParams are completed.
167 // Gets the pending profiles into *|profiles| and clears the internal
168 // storage. This function is thread safe.
170 // ***This is intended for use only by UMA.*** Callers who want to process the
171 // collected profiles should use SetCustomCompletedCallback.
172 static void GetPendingProfiles(std::vector
<Profile
>* profiles
);
174 // By default, collected profiles are stored internally and can be retrieved
175 // by GetPendingProfiles. If a callback is provided via this function,
176 // however, it will be called with the collected profiles instead. Note that
177 // this call to the callback occurs *on the profiler thread*.
178 void SetCustomCompletedCallback(
179 Callback
<void(const std::vector
<Profile
>&)> callback
);
182 class SamplingThread
;
183 struct SamplingThreadDeleter
{
184 void operator() (SamplingThread
* thread
) const;
187 // The thread whose stack will be sampled.
188 PlatformThreadId thread_id_
;
190 const SamplingParams params_
;
192 scoped_ptr
<SamplingThread
, SamplingThreadDeleter
> sampling_thread_
;
193 scoped_ptr
<NativeStackSampler
> native_sampler_
;
195 Callback
<void(const std::vector
<Profile
>&)> custom_completed_callback_
;
197 DISALLOW_COPY_AND_ASSIGN(StackSamplingProfiler
);
200 // Defined to allow equality check of Samples.
201 BASE_EXPORT
bool operator==(const StackSamplingProfiler::Frame
& a
,
202 const StackSamplingProfiler::Frame
& b
);
203 // Defined to allow ordering of Samples.
204 BASE_EXPORT
bool operator<(const StackSamplingProfiler::Frame
& a
,
205 const StackSamplingProfiler::Frame
& b
);
209 #endif // BASE_PROFILER_STACK_SAMPLING_PROFILER_H_