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
23namespace base {
24
25class BucketRanges;
26class HistogramBase;
27class Lock;
28
29class 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_
116