Add one-time randomization support for FieldTrial, and the ability to

base/metrics/field_trial.cc

 // Copyright (c) 2011 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #include "base/metrics/field_trial.h"
 
 #include "base/logging.h"
 #include "base/rand_util.h"
+#include "base/sha1.h"
+#include "base/string_util.h"
 #include "base/stringprintf.h"
 #include "base/utf_string_conversions.h"
 
 namespace base {
 
 // static
 const int FieldTrial::kNotFinalized = -1;
 
 // static
 const int FieldTrial::kDefaultGroupNumber = 0;
@@ skipping 15 matching lines @@
 
 FieldTrial::FieldTrial(const std::string& name,
                        const Probability total_probability,
                        const std::string& default_group_name,
                        const int year,
                        const int month,
                        const int day_of_month)
   : name_(name),
     divisor_(total_probability),
     default_group_name_(default_group_name),
-    random_(static_cast<Probability>(divisor_ * base::RandDouble())),
+    random_(static_cast<Probability>(divisor_ * RandDouble())),
     accumulated_group_probability_(0),
     next_group_number_(kDefaultGroupNumber+1),
-    group_(kNotFinalized) {
+    group_(kNotFinalized),
+    enable_field_trial_(true) {
   DCHECK_GT(total_probability, 0);
+  DCHECK(!name_.empty());
   DCHECK(!default_group_name_.empty());
   FieldTrialList::Register(this);
 
   DCHECK_GT(year, 1970);
   DCHECK_GT(month, 0);
   DCHECK_LT(month, 13);
   DCHECK_GT(day_of_month, 0);
   DCHECK_LT(day_of_month, 32);
 
-  base::Time::Exploded exploded;
+  Time::Exploded exploded;
   exploded.year = year;
   exploded.month = month;
   exploded.day_of_week = 0;  // Should be unused.
   exploded.day_of_month = day_of_month;
   exploded.hour = 0;
   exploded.minute = 0;
   exploded.second = 0;
   exploded.millisecond = 0;
 
-  base::Time expiration_time = Time::FromLocalExploded(exploded);
-  disable_field_trial_ = (GetBuildTime() > expiration_time) ? true : false;
+  Time expiration_time = Time::FromLocalExploded(exploded);
+  if (GetBuildTime() > expiration_time)
+    Disable();
+}
+
+void FieldTrial::UseOneTimeRandomization() {
+  DCHECK_EQ(group_, kNotFinalized);

[jar (doing other things), 2011/05/03 00:17:47]

Could you also add a DCHECK_EQ(0, next_group_number_) to show that we haven't
started adding groups (and hence haven't yet compared probabilities to the
rand() based random number).

[Jói, 2011/05/03 17:41:47]

Done.

+  if (!FieldTrialList::IsOneTimeRandomizationEnabled()) {
+    NOTREACHED();
+    Disable();
+    return;
+  }
+
+  random_ = static_cast<Probability>(
+      divisor_ * HashClientId(FieldTrialList::client_id(), name_));
+}
+
+void FieldTrial::Disable() {
+  enable_field_trial_ = false;
+
+  // In case we are disabled after initialization, we need to switch
+  // the trial to the default group.
+  if (group_ != kNotFinalized) {
+    group_ = kDefaultGroupNumber;
+    group_name_ = default_group_name_;
+  }
 }
 
 int FieldTrial::AppendGroup(const std::string& name,
                             Probability group_probability) {
   DCHECK_LE(group_probability, divisor_);
   DCHECK_GE(group_probability, 0);
 
-  if (enable_benchmarking_ || disable_field_trial_)
+  if (enable_benchmarking_ || !enable_field_trial_)
     group_probability = 0;
 
   accumulated_group_probability_ += group_probability;
 
   DCHECK_LE(accumulated_group_probability_, divisor_);
   if (group_ == kNotFinalized && accumulated_group_probability_ > random_) {
     // This is the group that crossed the random line, so we do the assignment.
     group_ = next_group_number_;
     if (name.empty())
-      base::StringAppendF(&group_name_, "%d", group_);
+      StringAppendF(&group_name_, "%d", group_);
     else
       group_name_ = name;
     FieldTrialList::NotifyFieldTrialGroupSelection(name_, group_name_);
   }
   return next_group_number_++;
 }
 
 int FieldTrial::group() {
   if (group_ == kNotFinalized) {
     accumulated_group_probability_ = divisor_;
     group_ = kDefaultGroupNumber;
     group_name_ = default_group_name_;
     FieldTrialList::NotifyFieldTrialGroupSelection(name_, group_name_);
   }
   return group_;
 }
 
 std::string FieldTrial::group_name() {
   group();  // call group() to make group assignment was done.

[jar (doing other things), 2011/05/03 00:17:47]

nit (in old code): 
"make group assignment" --> "make sure group assignment"

[Jói, 2011/05/03 17:41:47]

Done.

+  DCHECK(!group_name_.empty());
   return group_name_;
 }
 
 // static
 std::string FieldTrial::MakeName(const std::string& name_prefix,
                                  const std::string& trial_name) {
   std::string big_string(name_prefix);
   big_string.append(1, kHistogramFieldTrialSeparator);
   return big_string.append(FieldTrialList::FindFullName(trial_name));
 }
 
 // static
 void FieldTrial::EnableBenchmarking() {
   DCHECK_EQ(0u, FieldTrialList::GetFieldTrialCount());
   enable_benchmarking_ = true;
 }
 
 FieldTrial::~FieldTrial() {}
 
 // static
 Time FieldTrial::GetBuildTime() {
   Time integral_build_time;
   const char* kDateTime = __DATE__ " " __TIME__;
   bool result = Time::FromString(ASCIIToWide(kDateTime).c_str(),
                                  &integral_build_time);
   DCHECK(result);
   return integral_build_time;
 }
 
+// static
+double FieldTrial::HashClientId(const std::string& client_id,
+                                const std::string& trial_name) {
+  // SHA-1 is designed to produce a uniformly random spread in its output space,
+  // even for nearly-identical inputs, so it helps massage whatever client_id
+  // and trial_name we get into something with a uniform distribution, which
+  // is desirable so that we don't skew any part of the 0-100% spectrum.
+  std::string input(client_id + trial_name);
+  unsigned char sha1_hash[SHA1_LENGTH];
+  SHA1HashBytes(reinterpret_cast<const unsigned char*>(input.c_str()),
+                input.size(),
+                sha1_hash);
+
+  COMPILE_ASSERT(sizeof(uint64) < sizeof(sha1_hash), need_more_data);
+  uint64* bits = reinterpret_cast<uint64*>(&sha1_hash[0]);
+
+  return BitsToOpenEndedUnitInterval(*bits);
+}
+
 //------------------------------------------------------------------------------
 // FieldTrialList methods and members.
 
 // static
 FieldTrialList* FieldTrialList::global_ = NULL;
 
 // static
 bool FieldTrialList::register_without_global_ = false;
 
-FieldTrialList::FieldTrialList()
+FieldTrialList::FieldTrialList(const std::string& client_id)
     : application_start_time_(TimeTicks::Now()),
+      client_id_(client_id),
       observer_list_(ObserverList<Observer>::NOTIFY_EXISTING_ONLY) {
   DCHECK(!global_);
   DCHECK(!register_without_global_);
   global_ = this;
 
   Time::Exploded exploded;
   Time two_years_from_now =
       Time::NowFromSystemTime() + TimeDelta::FromDays(730);
   two_years_from_now.LocalExplode(&exploded);
   kExpirationYearInFuture = exploded.year;
@@ skipping 40 matching lines @@
 
 // static
 std::string FieldTrialList::FindFullName(const std::string& name) {
   FieldTrial* field_trial = Find(name);
   if (field_trial)
     return field_trial->group_name();
   return "";
 }
 
 // static
+bool FieldTrialList::TrialExists(const std::string& name) {
+  return Find(name) != NULL;
+}
+
+// static
 void FieldTrialList::StatesToString(std::string* output) {
   if (!global_)
     return;
   DCHECK(output->empty());
   AutoLock auto_lock(global_->lock_);
+
+  // First, write just the client_id plus a separator.

[jar (doing other things), 2011/05/03 00:17:47]

Please add a DCHECK() comparable to line 279 to ensure that we don't put a
separator into the client_id.

[Jói, 2011/05/03 17:41:47]

Removed this code.

+  output->append(global_->client_id_);
+  output->append(1, kPersistentStringSeparator);
+
   for (RegistrationList::iterator it = global_->registered_.begin();
        it != global_->registered_.end(); ++it) {
     const std::string name = it->first;
     std::string group_name = it->second->group_name_internal();
     if (group_name.empty())
       // No definitive winner in this trial, use default_group_name as the
       // group_name.
       group_name = it->second->default_group_name();

[jar (doing other things), 2011/05/03 00:17:47]

This is a bug (now... though not because of your code, and not that big a bug).

When there is no definitive winner yet, we should not include the field trial.
We can (now) allow it to be resolved later.  Hence I *think* the correct thing
is:
if (group_name.empty())
  continue;

Alternatively, if we did want to "default" a group, we would have to do it using
standard code, establishing the default in our process as well.  If we don't
establish the same result in the browser process, then the browser process
*could* later establish a value, which would propagate to the renderers, and
conflict with this initialization value.  Unfortunately, establishing a value
for an incompletely specified FieldTrial *might* race with the ongoing
initialization of that FieldTrial <sigh>.  

Bottom line: I think we should just have the continue.

FYI:

We currently notify all pre-existing renderer processes when we do finalize a
field trial... so the "correct" value will make its way (sooner or later) to the
renderer.  IMO, it is questionable practice to set field trials late.... but
that is what the use case (feature request) called for... and caveat developor)

[Jói, 2011/05/03 17:41:47]

Switched to a continue.

     DCHECK_EQ(name.find(kPersistentStringSeparator), std::string::npos);
     DCHECK_EQ(group_name.find(kPersistentStringSeparator), std::string::npos);
     output->append(name);
     output->append(1, kPersistentStringSeparator);
     output->append(group_name);
     output->append(1, kPersistentStringSeparator);
   }
 }
 
 // static
 bool FieldTrialList::CreateTrialsInChildProcess(
     const std::string& parent_trials) {
   DCHECK(global_);
   if (parent_trials.empty() || !global_)
     return true;
 
   size_t next_item = 0;
+
+  // Get the client_id first, before the list of trials/groups.
+  size_t id_end = parent_trials.find(kPersistentStringSeparator, next_item);
+  // Must allow empty client_id, so we don't check for id_end == 0.
+  if (id_end == parent_trials.npos)
+    return false;
+  global_->client_id_ = std::string(parent_trials, 0, id_end);
+  next_item = id_end + 1;
+
   while (next_item < parent_trials.length()) {
     size_t name_end = parent_trials.find(kPersistentStringSeparator, next_item);
     if (name_end == parent_trials.npos || next_item == name_end)
       return false;
     size_t group_name_end = parent_trials.find(kPersistentStringSeparator,
                                                name_end + 1);
     if (group_name_end == parent_trials.npos || name_end + 1 == group_name_end)
       return false;
     std::string name(parent_trials, next_item, name_end - next_item);
     std::string group_name(parent_trials, name_end + 1,
@@ skipping 59 matching lines @@
 }
 
 // static
 size_t FieldTrialList::GetFieldTrialCount() {
   if (!global_)
     return 0;
   AutoLock auto_lock(global_->lock_);
   return global_->registered_.size();
 }
 
+// static
+bool FieldTrialList::IsOneTimeRandomizationEnabled() {
+  DCHECK(global_);
+  if (!global_)
+    return false;
+
+  return !global_->client_id_.empty();
+}
+
+// static
+const std::string& FieldTrialList::client_id() {
+  DCHECK(global_);
+  if (!global_)
+    return EmptyString();
+
+  return global_->client_id_;
+}
+
 FieldTrial* FieldTrialList::PreLockedFind(const std::string& name) {
   RegistrationList::iterator it = registered_.find(name);
   if (registered_.end() == it)
     return NULL;
   return it->second;
 }
 
 }  // namespace base