Statistical stack profiler for Windows x64

base/profiler/stack_sampling_profiler.h

+// 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 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.

[zturner, 2015/03/18 23:04:37]

Is the GUID + AGE always available even for for release / optimized builds?  Why
not just a SHA1 of the binary, which would be the same for all platforms.

[danduong, 2015/03/18 23:20:47]

This needs to be the same Module ID that breakpad uses for identifying a symbol.

+    std::string id;
+    // The filename of the module.
+    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 we only consider the basename.

+  };
+
+  // Frame represents an individual sampled stack frame with module information.
+  struct 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>;

[zturner, 2015/03/18 23:04:36]

I'm not sure what the Chromium's build requirements are these days, but are
template aliases ok?  I thought they miscompiled on versions of MSVC prior to
2015.

[Mike Wittman, 2015/03/19 00:15:43]

Guideline is to use "using" instead of typedef.

We've only seen breakage when used with template template functions:
https://groups.google.com/a/chromium.org/d/msg/chromium-dev/8dOAMzgR4ao/mOR2G...

+
+  // 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);

[zturner, 2015/03/18 23:04:36]

It's a little odd to see a scoped_ptr returned by value.  Should this be
unique_ptr?

[Mike Wittman, 2015/03/19 00:15:43]

We don't have unique_ptr in Chrome yet. scoped_ptr is the standard for ownership
transfer.

+
+    // 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;

[zturner, 2015/03/18 23:04:36]

Is there any reason to expect the user might pass nullptr?  It might makes the
function kind of useless if so, and a reference seems better if not.  Similar
comment applies to other subsequent functions in this file.

[Mike Wittman, 2015/03/19 00:15:43]

Only const objects may be passed by reference according to the C++ style guide.

+
+    // 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);

[cpu_(ooo_6.6-7.5), 2015/03/19 02:49:04]

feels strange to get them all ... why not the last one only?

[danduong, 2015/03/19 03:09:45]

Are you suggesting we should call the callback on completion of each burst? That
might be reasonable. What do you think Mike?

[Mike Wittman, 2015/03/19 20:27:17]

For providing data to UMA I don't think it matters much either way (although
that pathway doesn't use a custom callback anyway).

For ad hoc use within Chrome, returning all profiles has the nice property that
once you get the callback you know the profiling is complete. This allows
threads to profile themselves and process the results, without executing
profile-processing code while being profiled.

+
+ 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_