base/metrics/statistics_recorder.h

   1 // Copyright (c) 2012 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 // StatisticsRecorder holds all Histograms and BucketRanges that are used by
   6 // Histograms in the system. It provides a general place for
   7 // Histograms/BucketRanges to register, and supports a global API for accessing
   8 // (i.e., dumping, or graphing) the data.
   9
  10 #ifndef BASE_METRICS_STATISTICS_RECORDER_H_
  11 #define BASE_METRICS_STATISTICS_RECORDER_H_
  12
  13 #include <list>
  14 #include <map>
  15 #include <string>
  16 #include <vector>
  17
  18 #include "base/base_export.h"
  19 #include "base/basictypes.h"
  20 #include "base/callback.h"
  21 #include "base/gtest_prod_util.h"
  22 #include "base/lazy_instance.h"
  23 #include "base/metrics/histogram_base.h"
  24
  25 namespace base {
  26
  27 class BucketRanges;
  28 class Lock;
  29
  30 class BASE_EXPORT StatisticsRecorder {
  31  public:
  32   typedef std::vector<HistogramBase*> Histograms;
  33
  34   // Initializes the StatisticsRecorder system. Safe to call multiple times.
  35   static void Initialize();
  36
  37   // Find out if histograms can now be registered into our list.
  38   static bool IsActive();
  39
  40   // Register, or add a new histogram to the collection of statistics. If an
  41   // identically named histogram is already registered, then the argument
  42   // |histogram| will deleted.  The returned value is always the registered
  43   // histogram (either the argument, or the pre-existing registered histogram).
  44   static HistogramBase* RegisterOrDeleteDuplicate(HistogramBase* histogram);
  45
  46   // Register, or add a new BucketRanges. If an identically BucketRanges is
  47   // already registered, then the argument |ranges| will deleted. The returned
  48   // value is always the registered BucketRanges (either the argument, or the
  49   // pre-existing one).
  50   static const BucketRanges* RegisterOrDeleteDuplicateRanges(
  51       const BucketRanges* ranges);
  52
  53   // Methods for appending histogram data to a string.  Only histograms which
  54   // have |query| as a substring are written to |output| (an empty string will
  55   // process all registered histograms).
  56   static void WriteHTMLGraph(const std::string& query, std::string* output);
  57   static void WriteGraph(const std::string& query, std::string* output);
  58
  59   // Returns the histograms with |query| as a substring as JSON text (an empty
  60   // |query| will process all registered histograms).
  61   static std::string ToJSON(const std::string& query);
  62
  63   // Method for extracting histograms which were marked for use by UMA.
  64   static void GetHistograms(Histograms* output);
  65
  66   // Method for extracting BucketRanges used by all histograms registered.
  67   static void GetBucketRanges(std::vector<const BucketRanges*>* output);
  68
  69   // Find a histogram by name. It matches the exact name. This method is thread
  70   // safe.  It returns NULL if a matching histogram is not found.
  71   static HistogramBase* FindHistogram(const std::string& name);
  72
  73   // GetSnapshot copies some of the pointers to registered histograms into the
  74   // caller supplied vector (Histograms). Only histograms which have |query| as
  75   // a substring are copied (an empty string will process all registered
  76   // histograms).
  77   static void GetSnapshot(const std::string& query, Histograms* snapshot);
  78
  79   typedef base::Callback<void(HistogramBase::Sample)> OnSampleCallback;
  80
  81   // SetCallback sets the callback to notify when a new sample is recorded on
  82   // the histogram referred to by |histogram_name|. The call to this method can
  83   // be be done before or after the histogram is created. This method is thread
  84   // safe. The return value is whether or not the callback was successfully set.
  85   static bool SetCallback(const std::string& histogram_name,
  86                           const OnSampleCallback& callback);
  87
  88   // ClearCallback clears any callback set on the histogram referred to by
  89   // |histogram_name|. This method is thread safe.
  90   static void ClearCallback(const std::string& histogram_name);
  91
  92   // FindCallback retrieves the callback for the histogram referred to by
  93   // |histogram_name|, or a null callback if no callback exists for this
  94   // histogram. This method is thread safe.
  95   static OnSampleCallback FindCallback(const std::string& histogram_name);
  96
  97  private:
  98   // HistogramNameRef holds a weak const ref to the name field of the associated
  99   // Histogram object, allowing re-use of the underlying string storage for the
 100   // map keys. The wrapper is required as using "const std::string&" as the key
 101   // results in compile errors.
 102   struct HistogramNameRef {
 103     explicit HistogramNameRef(const std::string& name) : name_(name) {};
 104
 105     // Operator < is necessary to use this type as a std::map key.
 106     bool operator<(const HistogramNameRef& other) const {
 107       return name_ < other.name_;
 108     }
 109
 110     // Weak, owned by the associated Histogram object.
 111     const std::string& name_;
 112   };
 113
 114   // We keep all registered histograms in a map, from name to histogram.
 115   typedef std::map<HistogramNameRef, HistogramBase*> HistogramMap;
 116
 117   // We keep a map of callbacks to histograms, so that as histograms are
 118   // created, we can set the callback properly.
 119   typedef std::map<std::string, OnSampleCallback> CallbackMap;
 120
 121   // We keep all |bucket_ranges_| in a map, from checksum to a list of
 122   // |bucket_ranges_|.  Checksum is calculated from the |ranges_| in
 123   // |bucket_ranges_|.
 124   typedef std::map<uint32, std::list<const BucketRanges*>*> RangesMap;
 125
 126   friend struct DefaultLazyInstanceTraits<StatisticsRecorder>;
 127   friend class HistogramBaseTest;
 128   friend class HistogramSnapshotManagerTest;
 129   friend class HistogramTest;
 130   friend class JsonPrefStoreTest;
 131   friend class SparseHistogramTest;
 132   friend class StatisticsRecorderTest;
 133   FRIEND_TEST_ALL_PREFIXES(HistogramDeltaSerializationTest,
 134                            DeserializeHistogramAndAddSamples);
 135
 136   // The constructor just initializes static members. Usually client code should
 137   // use Initialize to do this. But in test code, you can friend this class and
 138   // call destructor/constructor to get a clean StatisticsRecorder.
 139   StatisticsRecorder();
 140   ~StatisticsRecorder();
 141
 142   static void DumpHistogramsToVlog(void* instance);
 143
 144   static HistogramMap* histograms_;
 145   static CallbackMap* callbacks_;
 146   static RangesMap* ranges_;
 147
 148   // Lock protects access to above maps.
 149   static base::Lock* lock_;
 150
 151   DISALLOW_COPY_AND_ASSIGN(StatisticsRecorder);
 152 };
 153
 154 }  // namespace base
 155
 156 #endif  // BASE_METRICS_STATISTICS_RECORDER_H_