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