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. | |
zturner
2015/03/18 23:04:37
Is the GUID + AGE always available even for for re
danduong
2015/03/18 23:20:47
This needs to be the same Module ID that breakpad
| |
67 std::string id; | |
68 // The filename of the module. | |
69 FilePath filename; | |
cpu_(ooo_6.6-7.5)
2015/03/19 02:49:04
are you getting the full path or just the name?
danduong
2015/03/19 03:09:45
This should be full path.
Mike Wittman
2015/03/19 20:27:17
Yes, this is the full path.
When sending to UMA w
| |
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>; | |
zturner
2015/03/18 23:04:36
I'm not sure what the Chromium's build requirement
Mike Wittman
2015/03/19 00:15:43
Guideline is to use "using" instead of typedef.
W
| |
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); | |
zturner
2015/03/18 23:04:36
It's a little odd to see a scoped_ptr returned by
Mike Wittman
2015/03/19 00:15:43
We don't have unique_ptr in Chrome yet. scoped_ptr
| |
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; | |
zturner
2015/03/18 23:04:36
Is there any reason to expect the user might pass
Mike Wittman
2015/03/19 00:15:43
Only const objects may be passed by reference acco
| |
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); | |
cpu_(ooo_6.6-7.5)
2015/03/19 02:49:04
feels strange to get them all ... why not the last
danduong
2015/03/19 03:09:45
Are you suggesting we should call the callback on
Mike Wittman
2015/03/19 20:27:17
For providing data to UMA I don't think it matters
| |
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 |