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/gtest_prod_util.h"
  21 #include "base/lazy_instance.h"
  22
  23 namespace base {
  24
  25 class BucketRanges;
  26 class HistogramBase;
  27 class Lock;
  28
  29 class BASE_EXPORT StatisticsRecorder {
  30  public:
  31   typedef std::vector<HistogramBase*> Histograms;
  32
  33   // Initializes the StatisticsRecorder system. Safe to call multiple times.
  34   static void Initialize();
  35
  36   // Find out if histograms can now be registered into our list.
  37   static bool IsActive();
  38
  39   // Register, or add a new histogram to the collection of statistics. If an
  40   // identically named histogram is already registered, then the argument
  41   // |histogram| will deleted.  The returned value is always the registered
  42   // histogram (either the argument, or the pre-existing registered histogram).
  43   static HistogramBase* RegisterOrDeleteDuplicate(HistogramBase* histogram);
  44
  45   // Register, or add a new BucketRanges. If an identically BucketRanges is
  46   // already registered, then the argument |ranges| will deleted. The returned
  47   // value is always the registered BucketRanges (either the argument, or the
  48   // pre-existing one).
  49   static const BucketRanges* RegisterOrDeleteDuplicateRanges(
  50       const BucketRanges* ranges);
  51
  52   // Methods for appending histogram data to a string.  Only histograms which
  53   // have |query| as a substring are written to |output| (an empty string will
  54   // process all registered histograms).
  55   static void WriteHTMLGraph(const std::string& query, std::string* output);
  56   static void WriteGraph(const std::string& query, std::string* output);
  57
  58   // Returns the histograms with |query| as a substring as JSON text (an empty
  59   // |query| will process all registered histograms).
  60   static std::string ToJSON(const std::string& query);
  61
  62   // Method for extracting histograms which were marked for use by UMA.
  63   static void GetHistograms(Histograms* output);
  64
  65   // Method for extracting BucketRanges used by all histograms registered.
  66   static void GetBucketRanges(std::vector<const BucketRanges*>* output);
  67
  68   // Find a histogram by name. It matches the exact name. This method is thread
  69   // safe.  It returns NULL if a matching histogram is not found.
  70   static HistogramBase* FindHistogram(const std::string& name);
  71
  72   // GetSnapshot copies some of the pointers to registered histograms into the
  73   // caller supplied vector (Histograms). Only histograms which have |query| as
  74   // a substring are copied (an empty string will process all registered
  75   // histograms).
  76   static void GetSnapshot(const std::string& query, Histograms* snapshot);
  77
  78  private:
  79   // HistogramNameRef holds a weak const ref to the name field of the associated
  80   // Histogram object, allowing re-use of the underlying string storage for the
  81   // map keys. The wrapper is required as using "const std::string&" as the key
  82   // results in compile errors.
  83   struct HistogramNameRef {
  84     explicit HistogramNameRef(const std::string& name) : name_(name) {};
  85
  86     // Operator < is necessary to use this type as a std::map key.
  87     bool operator<(const HistogramNameRef& other) const {
  88       return name_ < other.name_;
  89     }
  90
  91     // Weak, owned by the associated Histogram object.
  92     const std::string& name_;
  93   };
  94
  95   // We keep all registered histograms in a map, from name to histogram.
  96   typedef std::map<HistogramNameRef, HistogramBase*> HistogramMap;
  97
  98   // We keep all |bucket_ranges_| in a map, from checksum to a list of
  99   // |bucket_ranges_|.  Checksum is calculated from the |ranges_| in
 100   // |bucket_ranges_|.
 101   typedef std::map<uint32, std::list<const BucketRanges*>*> RangesMap;
 102
 103   friend struct DefaultLazyInstanceTraits<StatisticsRecorder>;
 104   friend class HistogramBaseTest;
 105   friend class HistogramSnapshotManagerTest;
 106   friend class HistogramTest;
 107   friend class JsonPrefStoreTest;
 108   friend class SparseHistogramTest;
 109   friend class StatisticsRecorderTest;
 110   FRIEND_TEST_ALL_PREFIXES(HistogramDeltaSerializationTest,
 111                            DeserializeHistogramAndAddSamples);
 112
 113   // The constructor just initializes static members. Usually client code should
 114   // use Initialize to do this. But in test code, you can friend this class and
 115   // call destructor/constructor to get a clean StatisticsRecorder.
 116   StatisticsRecorder();
 117   ~StatisticsRecorder();
 118
 119   static void DumpHistogramsToVlog(void* instance);
 120
 121   static HistogramMap* histograms_;
 122   static RangesMap* ranges_;
 123
 124   // Lock protects access to above maps.
 125   static base::Lock* lock_;
 126
 127   DISALLOW_COPY_AND_ASSIGN(StatisticsRecorder);
 128 };
 129
 130 }  // namespace base
 131
 132 #endif  // BASE_METRICS_STATISTICS_RECORDER_H_