components/rappor/rappor_metric.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_METRIC_H_
   6 #define COMPONENTS_RAPPOR_RAPPOR_METRIC_H_
   7
   8 #include <string>
   9
  10 #include "base/basictypes.h"
  11 #include "base/macros.h"
  12 #include "components/rappor/bloom_filter.h"
  13 #include "components/rappor/byte_vector_utils.h"
  14 #include "components/rappor/rappor_parameters.h"
  15
  16 namespace rappor {
  17
  18 // A RapporMetric is an object that collects string samples into a Bloom filter,
  19 // and generates randomized reports about the collected data.
  20 //
  21 // This class should not be used directly by metrics clients.  Record metrics
  22 // using RapporService::RecordSample instead.
  23 //
  24 // For a full description of the rappor metrics, see
  25 // http://www.chromium.org/developers/design-documents/rappor
  26 class RapporMetric {
  27  public:
  28   // Takes the |metric_name| that this will be reported to the server with,
  29   // a |parameters| describing size and probability weights used in recording
  30   // this metric, and a |cohort| value, which determines the hash functions
  31   // used in the Bloom filter.
  32   RapporMetric(const std::string& metric_name,
  33                const RapporParameters& parameters,
  34                int32_t cohort);
  35   ~RapporMetric();
  36
  37   // Records an additional sample in the Bloom filter.
  38   // A random sample will be used when reporting this metric when more than one
  39   // sample is collected in the same reporting interval.
  40   void AddSample(const std::string& str);
  41
  42   // Retrieves the current Bloom filter bits.
  43   const ByteVector& bytes() const { return bloom_filter_.bytes(); }
  44
  45   // Gets the parameter values this metric was constructed with.
  46   const RapporParameters& parameters() const { return parameters_; }
  47
  48   // Generates the bits to report for this metric.  Using the secret as a seed,
  49   // randomly selects bits for redaction.  Then flips coins to generate the
  50   // final report bits.
  51   ByteVector GetReport(const std::string& secret) const;
  52
  53   // Specify the bytes to generate a report from, for testing purposes.
  54   void SetBytesForTesting(const ByteVector& bytes);
  55
  56  private:
  57   const std::string metric_name_;
  58   const RapporParameters parameters_;
  59   uint32_t sample_count_;
  60   BloomFilter bloom_filter_;
  61
  62   DISALLOW_COPY_AND_ASSIGN(RapporMetric);
  63 };
  64
  65 }  // namespace rappor
  66
  67 #endif  // COMPONENTS_RAPPOR_RAPPOR_METRIC_H_