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   // We keep all registered histograms in a map, from name to histogram.
  80   typedef std::map<std::string, HistogramBase*> HistogramMap;
  81
  82   // We keep all |bucket_ranges_| in a map, from checksum to a list of
  83   // |bucket_ranges_|.  Checksum is calculated from the |ranges_| in
  84   // |bucket_ranges_|.
  85   typedef std::map<uint32, std::list<const BucketRanges*>*> RangesMap;
  86
  87   friend struct DefaultLazyInstanceTraits<StatisticsRecorder>;
  88   friend class HistogramBaseTest;
  89   friend class HistogramSnapshotManagerTest;
  90   friend class HistogramTest;
  91   friend class SparseHistogramTest;
  92   friend class StatisticsRecorderTest;
  93   FRIEND_TEST_ALL_PREFIXES(HistogramDeltaSerializationTest,
  94                            DeserializeHistogramAndAddSamples);
  95
  96   // The constructor just initializes static members. Usually client code should
  97   // use Initialize to do this. But in test code, you can friend this class and
  98   // call destructor/constructor to get a clean StatisticsRecorder.
  99   StatisticsRecorder();
 100   ~StatisticsRecorder();
 101
 102   static void DumpHistogramsToVlog(void* instance);
 103
 104   static HistogramMap* histograms_;
 105   static RangesMap* ranges_;
 106
 107   // Lock protects access to above maps.
 108   static base::Lock* lock_;
 109
 110   DISALLOW_COPY_AND_ASSIGN(StatisticsRecorder);
 111 };
 112
 113 }  // namespace base
 114
 115 #endif  // BASE_METRICS_STATISTICS_RECORDER_H_