Home | History | Annotate | Download | only in metrics 
      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.
     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 with names matching
     74   // query are returned. The query must be a substring of histogram name for its
     75   // pointer to be copied.
     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 HistogramTest;
     90   friend class SparseHistogramTest;
     91   friend class StatisticsRecorderTest;
     92   FRIEND_TEST_ALL_PREFIXES(HistogramDeltaSerializationTest,
     93                            DeserializeHistogramAndAddSamples);
     94 
     95   // The constructor just initializes static members. Usually client code should
     96   // use Initialize to do this. But in test code, you can friend this class and
     97   // call destructor/constructor to get a clean StatisticsRecorder.
     98   StatisticsRecorder();
     99   ~StatisticsRecorder();
    100 
    101   static void DumpHistogramsToVlog(void* instance);
    102 
    103   static HistogramMap* histograms_;
    104   static RangesMap* ranges_;
    105 
    106   // Lock protects access to above maps.
    107   static base::Lock* lock_;
    108 
    109   DISALLOW_COPY_AND_ASSIGN(StatisticsRecorder);
    110 };
    111 
    112 }  // namespace base
    113 
    114 #endif  // BASE_METRICS_STATISTICS_RECORDER_H_
    115