| // Copyright 2015 The Chromium Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| |
| #ifndef BASE_PROFILER_STACK_SAMPLING_PROFILER_H_ |
| #define BASE_PROFILER_STACK_SAMPLING_PROFILER_H_ |
| |
| #include <string> |
| #include <vector> |
| |
| #include "base/base_export.h" |
| #include "base/callback.h" |
| #include "base/files/file_path.h" |
| #include "base/memory/scoped_ptr.h" |
| #include "base/strings/string16.h" |
| #include "base/threading/platform_thread.h" |
| #include "base/time/time.h" |
| |
| namespace base { |
| |
| // StackSamplingProfiler periodically stops a thread to sample its stack, for |
| // the purpose of collecting information about which code paths are |
| // executing. This information is used in aggregate by UMA to identify hot |
| // and/or janky code paths. |
| // |
| // Sample StackStackSamplingProfiler usage: |
| // |
| // // Create and customize params as desired. |
| // base::StackStackSamplingProfiler::SamplingParams params; |
| // // Any thread's ID may be passed as the target. |
| // base::StackSamplingProfiler profiler(base::PlatformThread::CurrentId()), |
| // params); |
| // |
| // // To process the profiles within Chrome rather than via UMA, set a custom |
| // // completed callback: |
| // base::Callback<void(const std::vector<Profile>&)> |
| // thread_safe_callback = ...; |
| // profiler.SetCustomCompletedCallback(thread_safe_callback); |
| // |
| // profiler.Start(); |
| // // ... work being done on the target thread here ... |
| // profiler.Stop(); // optional, stops collection before complete per params |
| // |
| // When all profiles are complete or the profiler is stopped, if the custom |
| // completed callback was set it will be called from the profiler thread with |
| // the completed profiles. If no callback was set, the profiles are stored |
| // internally and retrieved for UMA through |
| // GetPendingProfiles(). GetPendingProfiles() should never be called by other |
| // code; to retrieve profiles for in-process processing, set a completed |
| // callback. |
| class BASE_EXPORT StackSamplingProfiler { |
| public: |
| // Module represents the module (DLL or exe) corresponding to a stack frame. |
| struct BASE_EXPORT Module { |
| Module(); |
| ~Module(); |
| |
| // Points to the base address of the module. |
| const void* base_address; |
| // An opaque binary string that uniquely identifies a particular program |
| // version with high probability. This is parsed from headers of the loaded |
| // module. |
| // For binaries generated by GNU tools: |
| // Contents of the .note.gnu.build-id field. |
| // On Windows: |
| // GUID + AGE in the debug image headers of a module. |
| std::string id; |
| // The filename of the module. |
| FilePath filename; |
| }; |
| |
| // Frame represents an individual sampled stack frame with module information. |
| struct BASE_EXPORT Frame { |
| Frame(); |
| ~Frame(); |
| |
| // The sampled instruction pointer within the function. |
| const void* instruction_pointer; |
| // Index of the module in the array of modules. We don't represent module |
| // state directly here to save space. |
| int module_index; |
| }; |
| |
| // Sample represents a set of stack frames. |
| using Sample = std::vector<Frame>; |
| |
| // Profile represents a set of samples. |
| struct BASE_EXPORT Profile { |
| Profile(); |
| ~Profile(); |
| |
| std::vector<Module> modules; |
| std::vector<Sample> samples; |
| // Duration of this profile. |
| TimeDelta profile_duration; |
| // Time between samples. |
| TimeDelta sampling_period; |
| // True if sample ordering is important and should be preserved if and when |
| // this profile is compressed and processed. |
| bool preserve_sample_ordering; |
| }; |
| |
| // NativeStackSampler abstracts the native implementation required to record a |
| // stack sample for a given thread. |
| class NativeStackSampler { |
| public: |
| virtual ~NativeStackSampler(); |
| |
| // Create a stack sampler that records samples for |thread_handle|. Returns |
| // null if this platform does not support stack sampling. |
| static scoped_ptr<NativeStackSampler> Create(PlatformThreadId thread_id); |
| |
| // Notify the sampler that we're starting to record a new profile. This |
| // function is called on the SamplingThread. |
| virtual void ProfileRecordingStarting(Profile* profile) = 0; |
| |
| // Record a stack sample. This function is called on the SamplingThread. |
| virtual void RecordStackSample(Sample* sample) = 0; |
| |
| // Notify the sampler that we've stopped recording the current profile. This |
| // function is called on the SamplingThread. |
| virtual void ProfileRecordingStopped() = 0; |
| |
| protected: |
| NativeStackSampler(); |
| |
| private: |
| DISALLOW_COPY_AND_ASSIGN(NativeStackSampler); |
| }; |
| |
| // Represents parameters that configure the sampling. |
| struct BASE_EXPORT SamplingParams { |
| SamplingParams(); |
| |
| // Time to delay before first samples are taken. Defaults to 0. |
| TimeDelta initial_delay; |
| // Number of sampling bursts to perform. Defaults to 1. |
| int bursts; |
| // Interval between sampling bursts. This is the desired duration from the |
| // start of one burst to the start of the next burst. Defaults to 10s. |
| TimeDelta burst_interval; |
| // Number of samples to record per burst. Defaults to 300. |
| int samples_per_burst; |
| // Interval between samples during a sampling burst. This is the desired |
| // duration from the start of one burst to the start of the next |
| // burst. Defaults to 100ms. |
| TimeDelta sampling_interval; |
| // True if sample ordering is important and should be preserved if and when |
| // this profile is compressed and processed. Defaults to false. |
| bool preserve_sample_ordering; |
| }; |
| |
| StackSamplingProfiler(PlatformThreadId thread_id, |
| const SamplingParams& params); |
| ~StackSamplingProfiler(); |
| |
| // Initializes the profiler and starts sampling. |
| void Start(); |
| // Stops the profiler and any ongoing sampling. Calling this function is |
| // optional; if not invoked profiling will terminate when all the profiling |
| // bursts specified in the SamplingParams are completed. |
| void Stop(); |
| |
| // Gets the pending profiles into *|profiles| and clears the internal |
| // storage. This function is thread safe. |
| // |
| // ***This is intended for use only by UMA.*** Callers who want to process the |
| // collected profiles should use SetCustomCompletedCallback. |
| static void GetPendingProfiles(std::vector<Profile>* profiles); |
| |
| // By default, collected profiles are stored internally and can be retrieved |
| // by GetPendingProfiles. If a callback is provided via this function, |
| // however, it will be called with the collected profiles instead. Note that |
| // this call to the callback occurs *on the profiler thread*. |
| void SetCustomCompletedCallback( |
| Callback<void(const std::vector<Profile>&)> callback); |
| |
| private: |
| class SamplingThread; |
| struct SamplingThreadDeleter { |
| void operator() (SamplingThread* thread) const; |
| }; |
| |
| // The thread whose stack will be sampled. |
| PlatformThreadId thread_id_; |
| |
| const SamplingParams params_; |
| |
| scoped_ptr<SamplingThread, SamplingThreadDeleter> sampling_thread_; |
| scoped_ptr<NativeStackSampler> native_sampler_; |
| |
| Callback<void(const std::vector<Profile>&)> custom_completed_callback_; |
| |
| DISALLOW_COPY_AND_ASSIGN(StackSamplingProfiler); |
| }; |
| |
| // Defined to allow equality check of Samples. |
| BASE_EXPORT bool operator==(const StackSamplingProfiler::Frame& a, |
| const StackSamplingProfiler::Frame& b); |
| // Defined to allow ordering of Samples. |
| BASE_EXPORT bool operator<(const StackSamplingProfiler::Frame& a, |
| const StackSamplingProfiler::Frame& b); |
| |
| } // namespace base |
| |
| #endif // BASE_PROFILER_STACK_SAMPLING_PROFILER_H_ |