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