components/rappor/rappor_service.h

   1 // Copyright 2014 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 #ifndef COMPONENTS_RAPPOR_RAPPOR_SERVICE_H_
   6 #define COMPONENTS_RAPPOR_RAPPOR_SERVICE_H_
   7
   8 #include <map>
   9 #include <string>
  10
  11 #include "base/basictypes.h"
  12 #include "base/callback.h"
  13 #include "base/macros.h"
  14 #include "base/memory/scoped_ptr.h"
  15 #include "base/threading/thread_checker.h"
  16 #include "base/timer/timer.h"
  17 #include "components/metrics/daily_event.h"
  18 #include "components/rappor/rappor_parameters.h"
  19 #include "components/rappor/sample.h"
  20 #include "components/rappor/sampler.h"
  21
  22 class PrefRegistrySimple;
  23 class PrefService;
  24
  25 namespace net {
  26 class URLRequestContextGetter;
  27 }
  28
  29 namespace rappor {
  30
  31 class LogUploaderInterface;
  32 class RapporMetric;
  33 class RapporReports;
  34
  35 // The type of data stored in a metric.
  36 enum RapporType {
  37   // Generic metrics from UMA opt-in users.
  38   UMA_RAPPOR_TYPE = 0,
  39   // Generic metrics for SafeBrowsing users.
  40   SAFEBROWSING_RAPPOR_TYPE,
  41   // Deprecated: Use UMA_RAPPOR_TYPE for new metrics
  42   ETLD_PLUS_ONE_RAPPOR_TYPE,
  43   NUM_RAPPOR_TYPES,
  44   COARSE_RAPPOR_TYPE = SAFEBROWSING_RAPPOR_TYPE,
  45 };
  46
  47 // This class provides an interface for recording samples for rappor metrics,
  48 // and periodically generates and uploads reports based on the collected data.
  49 class RapporService {
  50  public:
  51   // Constructs a RapporService.
  52   // Calling code is responsible for ensuring that the lifetime of
  53   // |pref_service| is longer than the lifetime of RapporService.
  54   // |is_incognito_callback| will be called to test if incognito mode is active.
  55   RapporService(PrefService* pref_service,
  56                 const base::Callback<bool(void)> is_incognito_callback);
  57   virtual ~RapporService();
  58
  59   // Add an observer for collecting daily metrics.
  60   void AddDailyObserver(scoped_ptr<metrics::DailyEvent::Observer> observer);
  61
  62   // Initializes the rappor service, including loading the cohort and secret
  63   // preferences from disk.
  64   void Initialize(net::URLRequestContextGetter* context);
  65
  66   // Updates the settings for metric recording and uploading.
  67   // The RapporService must be initialized before this method is called.
  68   // |recording_groups| should be set of flags, e.g.
  69   //    UMA_RECORDING_GROUP | SAFEBROWSING_RECORDING_GROUP
  70   // If it contains any enabled groups, periodic reports will be
  71   // generated and queued for upload.
  72   // If |may_upload| is true, reports will be uploaded from the queue.
  73   void Update(int recording_groups, bool may_upload);
  74
  75   // Constructs a Sample object for the caller to record fields in.
  76   scoped_ptr<Sample> CreateSample(RapporType);
  77
  78   // Records a Sample of rappor metric specified by |metric_name|.
  79   //
  80   // TODO(holte): Rename RecordSample to RecordString and then rename this
  81   // to RecordSample.
  82   //
  83   // example:
  84   // scoped_ptr<Sample> sample = rappor_service->CreateSample(MY_METRIC_TYPE);
  85   // sample->SetStringField("Field1", "some string");
  86   // sample->SetFlagsValue("Field2", SOME|FLAGS);
  87   // rappor_service->RecordSample("MyMetric", sample.Pass());
  88   //
  89   // This will result in a report setting two metrics "MyMetric.Field1" and
  90   // "MyMetric.Field2", and they will both be generated from the same sample,
  91   // to allow for correllations to be computed.
  92   void RecordSampleObj(const std::string& metric_name,
  93                        scoped_ptr<Sample> sample);
  94
  95   // Records a sample of the rappor metric specified by |metric_name|.
  96   // Creates and initializes the metric, if it doesn't yet exist.
  97   virtual void RecordSample(const std::string& metric_name,
  98                             RapporType type,
  99                             const std::string& sample);
 100
 101   // Registers the names of all of the preferences used by RapporService in the
 102   // provided PrefRegistry. This should be called before calling Start().
 103   static void RegisterPrefs(PrefRegistrySimple* registry);
 104
 105  protected:
 106   // Initializes the state of the RapporService.
 107   void InitializeInternal(scoped_ptr<LogUploaderInterface> uploader,
 108                           int32_t cohort,
 109                           const std::string& secret);
 110
 111   // Cancels the next call to OnLogInterval.
 112   virtual void CancelNextLogRotation();
 113
 114   // Schedules the next call to OnLogInterval.
 115   virtual void ScheduleNextLogRotation(base::TimeDelta interval);
 116
 117   // Logs all of the collected metrics to the reports proto message and clears
 118   // the internal map. Exposed for tests. Returns true if any metrics were
 119   // recorded.
 120   bool ExportMetrics(RapporReports* reports);
 121
 122  private:
 123   // Records a sample of the rappor metric specified by |parameters|.
 124   // Creates and initializes the metric, if it doesn't yet exist.
 125   // Exposed for tests.
 126   void RecordSampleInternal(const std::string& metric_name,
 127                             const RapporParameters& parameters,
 128                             const std::string& sample);
 129
 130   // Checks if the service has been started successfully.
 131   bool IsInitialized() const;
 132
 133   // Called whenever the logging interval elapses to generate a new log of
 134   // reports and pass it to the uploader.
 135   void OnLogInterval();
 136
 137   // Check if recording of the metric is allowed, given it's parameters.
 138   // This will check that we are not in incognito mode, and that the
 139   // appropriate recording group is enabled.
 140   bool RecordingAllowed(const RapporParameters& parameters);
 141
 142   // Finds a metric in the metrics_map_, creating it if it doesn't already
 143   // exist.
 144   RapporMetric* LookUpMetric(const std::string& metric_name,
 145                              const RapporParameters& parameters);
 146
 147   // A weak pointer to the PrefService used to read and write preferences.
 148   PrefService* pref_service_;
 149
 150   // A callback for testing if incognito mode is active;
 151   const base::Callback<bool(void)> is_incognito_callback_;
 152
 153   // Client-side secret used to generate fake bits.
 154   std::string secret_;
 155
 156   // The cohort this client is assigned to. -1 is uninitialized.
 157   int32_t cohort_;
 158
 159   // Timer which schedules calls to OnLogInterval().
 160   base::OneShotTimer<RapporService> log_rotation_timer_;
 161
 162   // A daily event for collecting metrics once a day.
 163   metrics::DailyEvent daily_event_;
 164
 165   // A private LogUploader instance for sending reports to the server.
 166   scoped_ptr<LogUploaderInterface> uploader_;
 167
 168   // The set of recording groups that metrics are being recorded, e.g.
 169   //     UMA_RECORDING_GROUP | SAFEBROWSING_RECORDING_GROUP
 170   int recording_groups_;
 171
 172   // We keep all registered metrics in a map, from name to metric.
 173   // The map owns the metrics it contains.
 174   std::map<std::string, RapporMetric*> metrics_map_;
 175
 176   internal::Sampler sampler_;
 177
 178   base::ThreadChecker thread_checker_;
 179
 180   DISALLOW_COPY_AND_ASSIGN(RapporService);
 181 };
 182
 183 }  // namespace rappor
 184
 185 #endif  // COMPONENTS_RAPPOR_RAPPOR_SERVICE_H_