base/metrics/field_trial.cc

   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 #include "base/metrics/field_trial.h"
   6
   7 #include "base/build_time.h"
   8 #include "base/logging.h"
   9 #include "base/metrics/histogram.h"
  10 #include "base/rand_util.h"
  11 #include "base/sha1.h"
  12 #include "base/stringprintf.h"
  13 #include "base/string_util.h"
  14 #include "base/sys_byteorder.h"
  15 #include "base/utf_string_conversions.h"
  16
  17 namespace base {
  18
  19 namespace {
  20
  21 // Created a time value based on |year|, |month| and |day_of_month| parameters.
  22 Time CreateTimeFromParams(int year, int month, int day_of_month) {
  23   DCHECK_GT(year, 1970);
  24   DCHECK_GT(month, 0);
  25   DCHECK_LT(month, 13);
  26   DCHECK_GT(day_of_month, 0);
  27   DCHECK_LT(day_of_month, 32);
  28
  29   Time::Exploded exploded;
  30   exploded.year = year;
  31   exploded.month = month;
  32   exploded.day_of_week = 0;  // Should be unused.
  33   exploded.day_of_month = day_of_month;
  34   exploded.hour = 0;
  35   exploded.minute = 0;
  36   exploded.second = 0;
  37   exploded.millisecond = 0;
  38
  39   return Time::FromLocalExploded(exploded);
  40 }
  41
  42 }  // namespace
  43
  44 static const char kHistogramFieldTrialSeparator('_');
  45
  46 // statics
  47 const int FieldTrial::kNotFinalized = -1;
  48 const int FieldTrial::kDefaultGroupNumber = 0;
  49 bool FieldTrial::enable_benchmarking_ = false;
  50
  51 const char FieldTrialList::kPersistentStringSeparator('/');
  52 int FieldTrialList::kExpirationYearInFuture = 0;
  53
  54 //------------------------------------------------------------------------------
  55 // FieldTrial methods and members.
  56
  57 FieldTrial::FieldTrial(const std::string& trial_name,
  58                        const Probability total_probability,
  59                        const std::string& default_group_name)
  60     : trial_name_(trial_name),
  61       divisor_(total_probability),
  62       default_group_name_(default_group_name),
  63       random_(static_cast<Probability>(divisor_ * RandDouble())),
  64       accumulated_group_probability_(0),
  65       next_group_number_(kDefaultGroupNumber + 1),
  66       group_(kNotFinalized),
  67       enable_field_trial_(true),
  68       forced_(false),
  69       group_reported_(false) {
  70   DCHECK_GT(total_probability, 0);
  71   DCHECK(!trial_name_.empty());
  72   DCHECK(!default_group_name_.empty());
  73 }
  74
  75 FieldTrial::EntropyProvider::~EntropyProvider() {
  76 }
  77
  78 void FieldTrial::UseOneTimeRandomization() {
  79   // No need to specify randomization when the group choice was forced.
  80   if (forced_)
  81     return;
  82   DCHECK_EQ(group_, kNotFinalized);
  83   DCHECK_EQ(kDefaultGroupNumber + 1, next_group_number_);
  84   const EntropyProvider* entropy_provider =
  85       FieldTrialList::GetEntropyProviderForOneTimeRandomization();
  86   if (!entropy_provider) {
  87     NOTREACHED();
  88     // TODO(stevet): Remove this temporary histogram when logging
  89     // investigations are complete.
  90     UMA_HISTOGRAM_BOOLEAN("Variations.DisabledNoEntropyProvider", true);
  91     Disable();
  92     return;
  93   }
  94
  95   random_ = static_cast<Probability>(
  96       divisor_ * entropy_provider->GetEntropyForTrial(trial_name_));
  97 }
  98
  99 void FieldTrial::Disable() {
 100   DCHECK(!group_reported_);
 101   enable_field_trial_ = false;
 102
 103   // In case we are disabled after initialization, we need to switch
 104   // the trial to the default group.
 105   if (group_ != kNotFinalized) {
 106     // Only reset when not already the default group, because in case we were
 107     // forced to the default group, the group number may not be
 108     // kDefaultGroupNumber, so we should keep it as is.
 109     if (group_name_ != default_group_name_)
 110       SetGroupChoice(default_group_name_, kDefaultGroupNumber);
 111   }
 112 }
 113
 114 int FieldTrial::AppendGroup(const std::string& name,
 115                             Probability group_probability) {
 116   // When the group choice was previously forced, we only need to return the
 117   // the id of the chosen group, and anything can be returned for the others.
 118   if (forced_) {
 119     DCHECK(!group_name_.empty());
 120     if (name == group_name_) {
 121       return group_;
 122     }
 123     DCHECK_NE(next_group_number_, group_);
 124     // We still return different numbers each time, in case some caller need
 125     // them to be different.
 126     return next_group_number_++;
 127   }
 128
 129   DCHECK_LE(group_probability, divisor_);
 130   DCHECK_GE(group_probability, 0);
 131
 132   if (enable_benchmarking_ || !enable_field_trial_)
 133     group_probability = 0;
 134
 135   accumulated_group_probability_ += group_probability;
 136
 137   DCHECK_LE(accumulated_group_probability_, divisor_);
 138   if (group_ == kNotFinalized && accumulated_group_probability_ > random_) {
 139     // This is the group that crossed the random line, so we do the assignment.
 140     SetGroupChoice(name, next_group_number_);
 141   }
 142   return next_group_number_++;
 143 }
 144
 145 int FieldTrial::group() {
 146   FinalizeGroupChoice();
 147   FieldTrialList::NotifyFieldTrialGroupSelection(this);
 148   return group_;
 149 }
 150
 151 const std::string& FieldTrial::group_name() {
 152   // Call |group()| to ensure group gets assigned and observers are notified.
 153   group();
 154   DCHECK(!group_name_.empty());
 155   return group_name_;
 156 }
 157
 158 // static
 159 std::string FieldTrial::MakeName(const std::string& name_prefix,
 160                                  const std::string& trial_name) {
 161   std::string big_string(name_prefix);
 162   big_string.append(1, kHistogramFieldTrialSeparator);
 163   return big_string.append(FieldTrialList::FindFullName(trial_name));
 164 }
 165
 166 // static
 167 void FieldTrial::EnableBenchmarking() {
 168   DCHECK_EQ(0u, FieldTrialList::GetFieldTrialCount());
 169   enable_benchmarking_ = true;
 170 }
 171
 172 void FieldTrial::SetForced() {
 173   // We might have been forced before (e.g., by CreateFieldTrial) and it's
 174   // first come first served, e.g., command line switch has precedence.
 175   if (forced_)
 176     return;
 177
 178   // And we must finalize the group choice before we mark ourselves as forced.
 179   FinalizeGroupChoice();
 180   forced_ = true;
 181 }
 182
 183 FieldTrial::~FieldTrial() {}
 184
 185 void FieldTrial::SetGroupChoice(const std::string& group_name, int number) {
 186   group_ = number;
 187   if (group_name.empty())
 188     StringAppendF(&group_name_, "%d", group_);
 189   else
 190     group_name_ = group_name;
 191   DVLOG(1) << "Field trial: " << trial_name_ << " Group choice:" << group_name_;
 192 }
 193
 194 void FieldTrial::FinalizeGroupChoice() {
 195   if (group_ != kNotFinalized)
 196     return;
 197   accumulated_group_probability_ = divisor_;
 198   // Here it's OK to use |kDefaultGroupNumber| since we can't be forced and not
 199   // finalized.
 200   DCHECK(!forced_);
 201   SetGroupChoice(default_group_name_, kDefaultGroupNumber);
 202 }
 203
 204 bool FieldTrial::GetActiveGroup(ActiveGroup* active_group) const {
 205   if (!group_reported_ || !enable_field_trial_) {
 206     // TODO(asvitkine): Temporary histogram. Remove this once it is not needed.
 207     if (trial_name_ == "UMA-Uniformity-Trial-1-Percent") {
 208       const int kGroupNotReported = 1;
 209       const int kTrialDisabled = 2;
 210       int value = 0;
 211       if (!group_reported_)
 212         value |= kGroupNotReported;
 213       if (!enable_field_trial_)
 214         value |= kTrialDisabled;
 215       UMA_HISTOGRAM_ENUMERATION("Variations.UniformityTrialGroupNotActive",
 216                                 value, 4);
 217     }
 218     return false;
 219   }
 220   DCHECK_NE(group_, kNotFinalized);
 221   active_group->trial_name = trial_name_;
 222   active_group->group_name = group_name_;
 223   return true;
 224 }
 225
 226 //------------------------------------------------------------------------------
 227 // FieldTrialList methods and members.
 228
 229 // static
 230 FieldTrialList* FieldTrialList::global_ = NULL;
 231
 232 // static
 233 bool FieldTrialList::used_without_global_ = false;
 234
 235 FieldTrialList::Observer::~Observer() {
 236 }
 237
 238 FieldTrialList::FieldTrialList(
 239     const FieldTrial::EntropyProvider* entropy_provider)
 240     : entropy_provider_(entropy_provider),
 241       observer_list_(new ObserverListThreadSafe<FieldTrialList::Observer>(
 242           ObserverListBase<FieldTrialList::Observer>::NOTIFY_EXISTING_ONLY)) {
 243   DCHECK(!global_);
 244   DCHECK(!used_without_global_);
 245   global_ = this;
 246
 247   Time::Exploded exploded;
 248   Time two_years_from_now =
 249       Time::NowFromSystemTime() + TimeDelta::FromDays(730);
 250   two_years_from_now.LocalExplode(&exploded);
 251   kExpirationYearInFuture = exploded.year;
 252 }
 253
 254 FieldTrialList::~FieldTrialList() {
 255   AutoLock auto_lock(lock_);
 256   while (!registered_.empty()) {
 257     RegistrationList::iterator it = registered_.begin();
 258     it->second->Release();
 259     registered_.erase(it->first);
 260   }
 261   DCHECK_EQ(this, global_);
 262   global_ = NULL;
 263 }
 264
 265 // static
 266 FieldTrial* FieldTrialList::FactoryGetFieldTrial(
 267     const std::string& name,
 268     FieldTrial::Probability total_probability,
 269     const std::string& default_group_name,
 270     const int year,
 271     const int month,
 272     const int day_of_month,
 273     int* default_group_number) {
 274   if (default_group_number)
 275     *default_group_number = FieldTrial::kDefaultGroupNumber;
 276   // Check if the field trial has already been created in some other way.
 277   FieldTrial* existing_trial = Find(name);
 278   if (existing_trial) {
 279     CHECK(existing_trial->forced_);
 280     // If the field trial has already been forced, check whether it was forced
 281     // to the default group. Return the chosen group number, in that case..
 282     if (default_group_number &&
 283         default_group_name == existing_trial->default_group_name()) {
 284       *default_group_number = existing_trial->group();
 285     }
 286     return existing_trial;
 287   }
 288
 289   FieldTrial* field_trial =
 290       new FieldTrial(name, total_probability, default_group_name);
 291   if (GetBuildTime() > CreateTimeFromParams(year, month, day_of_month)) {
 292     // TODO(asvitkine): Temporary histogram. Remove this once it is not needed.
 293     if (name == "UMA-Uniformity-Trial-1-Percent")
 294       UMA_HISTOGRAM_BOOLEAN("Variations.UniformityTrialExpired", true);
 295     field_trial->Disable();
 296   }
 297   FieldTrialList::Register(field_trial);
 298   return field_trial;
 299 }
 300
 301 // static
 302 FieldTrial* FieldTrialList::Find(const std::string& name) {
 303   if (!global_)
 304     return NULL;
 305   AutoLock auto_lock(global_->lock_);
 306   return global_->PreLockedFind(name);
 307 }
 308
 309 // static
 310 int FieldTrialList::FindValue(const std::string& name) {
 311   FieldTrial* field_trial = Find(name);
 312   if (field_trial)
 313     return field_trial->group();
 314   return FieldTrial::kNotFinalized;
 315 }
 316
 317 // static
 318 std::string FieldTrialList::FindFullName(const std::string& name) {
 319   FieldTrial* field_trial = Find(name);
 320   if (field_trial)
 321     return field_trial->group_name();
 322   return "";
 323 }
 324
 325 // static
 326 bool FieldTrialList::TrialExists(const std::string& name) {
 327   return Find(name) != NULL;
 328 }
 329
 330 // static
 331 void FieldTrialList::StatesToString(std::string* output) {
 332   FieldTrial::ActiveGroups active_groups;
 333   GetActiveFieldTrialGroups(&active_groups);
 334   for (FieldTrial::ActiveGroups::const_iterator it = active_groups.begin();
 335        it != active_groups.end(); ++it) {
 336     DCHECK_EQ(std::string::npos,
 337               it->trial_name.find(kPersistentStringSeparator));
 338     DCHECK_EQ(std::string::npos,
 339               it->group_name.find(kPersistentStringSeparator));
 340     output->append(it->trial_name);
 341     output->append(1, kPersistentStringSeparator);
 342     output->append(it->group_name);
 343     output->append(1, kPersistentStringSeparator);
 344   }
 345 }
 346
 347 // static
 348 void FieldTrialList::GetActiveFieldTrialGroups(
 349     FieldTrial::ActiveGroups* active_groups) {
 350   DCHECK(active_groups->empty());
 351   if (!global_)
 352     return;
 353   AutoLock auto_lock(global_->lock_);
 354
 355   for (RegistrationList::iterator it = global_->registered_.begin();
 356        it != global_->registered_.end(); ++it) {
 357     FieldTrial::ActiveGroup active_group;
 358     if (it->second->GetActiveGroup(&active_group))
 359       active_groups->push_back(active_group);
 360   }
 361 }
 362
 363 // static
 364 bool FieldTrialList::CreateTrialsFromString(const std::string& trials_string) {
 365   DCHECK(global_);
 366   if (trials_string.empty() || !global_)
 367     return true;
 368
 369   size_t next_item = 0;
 370   while (next_item < trials_string.length()) {
 371     size_t name_end = trials_string.find(kPersistentStringSeparator, next_item);
 372     if (name_end == trials_string.npos || next_item == name_end)
 373       return false;
 374     size_t group_name_end = trials_string.find(kPersistentStringSeparator,
 375                                                name_end + 1);
 376     if (group_name_end == trials_string.npos || name_end + 1 == group_name_end)
 377       return false;
 378     std::string name(trials_string, next_item, name_end - next_item);
 379     std::string group_name(trials_string, name_end + 1,
 380                            group_name_end - name_end - 1);
 381     next_item = group_name_end + 1;
 382
 383     FieldTrial* trial = CreateFieldTrial(name, group_name);
 384     if (!trial)
 385       return false;
 386     // Call |group()| to mark the trial as "used" and notify observers, if any.
 387     // This is needed to ensure the trial is properly reported in child process
 388     // crash reports.
 389     trial->group();
 390   }
 391   return true;
 392 }
 393
 394 // static
 395 FieldTrial* FieldTrialList::CreateFieldTrial(
 396     const std::string& name,
 397     const std::string& group_name) {
 398   DCHECK(global_);
 399   DCHECK_GE(name.size(), 0u);
 400   DCHECK_GE(group_name.size(), 0u);
 401   if (name.empty() || group_name.empty() || !global_)
 402     return NULL;
 403
 404   FieldTrial* field_trial = FieldTrialList::Find(name);
 405   if (field_trial) {
 406     // In single process mode, or when we force them from the command line,
 407     // we may have already created the field trial.
 408     if (field_trial->group_name_internal() != group_name)
 409       return NULL;
 410     return field_trial;
 411   }
 412   const int kTotalProbability = 100;
 413   field_trial = new FieldTrial(name, kTotalProbability, group_name);
 414   // This is where we may assign a group number different from
 415   // kDefaultGroupNumber to the default group.
 416   field_trial->AppendGroup(group_name, kTotalProbability);
 417   field_trial->forced_ = true;
 418   FieldTrialList::Register(field_trial);
 419   return field_trial;
 420 }
 421
 422 // static
 423 void FieldTrialList::AddObserver(Observer* observer) {
 424   if (!global_)
 425     return;
 426   global_->observer_list_->AddObserver(observer);
 427 }
 428
 429 // static
 430 void FieldTrialList::RemoveObserver(Observer* observer) {
 431   if (!global_)
 432     return;
 433   global_->observer_list_->RemoveObserver(observer);
 434 }
 435
 436 // static
 437 void FieldTrialList::NotifyFieldTrialGroupSelection(FieldTrial* field_trial) {
 438   if (!global_)
 439     return;
 440
 441   {
 442     AutoLock auto_lock(global_->lock_);
 443     if (field_trial->group_reported_)
 444       return;
 445     field_trial->group_reported_ = true;
 446   }
 447
 448   if (!field_trial->enable_field_trial_)
 449     return;
 450
 451   global_->observer_list_->Notify(
 452       &FieldTrialList::Observer::OnFieldTrialGroupFinalized,
 453       field_trial->trial_name(),
 454       field_trial->group_name_internal());
 455 }
 456
 457 // static
 458 size_t FieldTrialList::GetFieldTrialCount() {
 459   if (!global_)
 460     return 0;
 461   AutoLock auto_lock(global_->lock_);
 462   return global_->registered_.size();
 463 }
 464
 465 // static
 466 const FieldTrial::EntropyProvider*
 467     FieldTrialList::GetEntropyProviderForOneTimeRandomization() {
 468   if (!global_) {
 469     used_without_global_ = true;
 470     return NULL;
 471   }
 472
 473   return global_->entropy_provider_.get();
 474 }
 475
 476 FieldTrial* FieldTrialList::PreLockedFind(const std::string& name) {
 477   RegistrationList::iterator it = registered_.find(name);
 478   if (registered_.end() == it)
 479     return NULL;
 480   return it->second;
 481 }
 482
 483 // static
 484 void FieldTrialList::Register(FieldTrial* trial) {
 485   if (!global_) {
 486     used_without_global_ = true;
 487     return;
 488   }
 489   AutoLock auto_lock(global_->lock_);
 490   DCHECK(!global_->PreLockedFind(trial->trial_name()));
 491   trial->AddRef();
 492   global_->registered_[trial->trial_name()] = trial;
 493 }
 494
 495 }  // namespace base