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