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 Histogram;
  27 class Lock;
  28
  29 class BASE_EXPORT StatisticsRecorder {
  30  public:
  31   typedef std::vector<Histogram*> Histograms;
  32
  33   // Initializes the StatisticsRecorder system.
  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 Histogram* RegisterOrDeleteDuplicate(Histogram* 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   // Method for collecting stats about histograms created in browser and
  53   // renderer processes. |suffix| is appended to histogram names. |suffix| could
  54   // be either browser or renderer.
  55   static void CollectHistogramStats(const std::string& suffix);
  56
  57   // Methods for printing histograms.  Only histograms which have query as
  58   // a substring are written to output (an empty string will process all
  59   // registered histograms).
  60   static void WriteHTMLGraph(const std::string& query, std::string* output);
  61   static void WriteGraph(const std::string& query, std::string* output);
  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 Histogram* FindHistogram(const std::string& name);
  72
  73   static bool dump_on_exit() { return dump_on_exit_; }
  74
  75   static void set_dump_on_exit(bool enable) { dump_on_exit_ = enable; }
  76
  77   // GetSnapshot copies some of the pointers to registered histograms into the
  78   // caller supplied vector (Histograms).  Only histograms with names matching
  79   // query are returned. The query must be a substring of histogram name for its
  80   // pointer to be copied.
  81   static void GetSnapshot(const std::string& query, Histograms* snapshot);
  82
  83  private:
  84   // We keep all registered histograms in a map, from name to histogram.
  85   typedef std::map<std::string, Histogram*> HistogramMap;
  86
  87   // We keep all |bucket_ranges_| in a map, from checksum to a list of
  88   // |bucket_ranges_|.  Checksum is calculated from the |ranges_| in
  89   // |bucket_ranges_|.
  90   typedef std::map<uint32, std::list<const BucketRanges*>*> RangesMap;
  91
  92   friend struct DefaultLazyInstanceTraits<StatisticsRecorder>;
  93   friend class HistogramBaseTest;
  94   friend class HistogramTest;
  95   friend class StatisticsRecorderTest;
  96
  97   // The constructor just initializes static members. Usually client code should
  98   // use Initialize to do this. But in test code, you can friend this class and
  99   // call destructor/constructor to get a clean StatisticsRecorder.
 100   StatisticsRecorder();
 101   ~StatisticsRecorder();
 102
 103   static HistogramMap* histograms_;
 104   static RangesMap* ranges_;
 105
 106   // Lock protects access to above maps.
 107   static base::Lock* lock_;
 108
 109   // Dump all known histograms to log.
 110   static bool dump_on_exit_;
 111
 112   DISALLOW_COPY_AND_ASSIGN(StatisticsRecorder);
 113 };
 114
 115 }  // namespace base
 116
 117 #endif  // BASE_METRICS_STATISTICS_RECORDER_H_