Profile-Guided Optimization (PGO)

Generating PGO Profiles via Bots

See go/chrome-pgo-internal (Googlers only).

Generating PGO Profiles Manually

Normally devs don't need to worry about this and can use the default profile for official builds. The default profile can be fetched by adding "checkout_pgo_profiles": True to custom_vars in the gclient config and running gclient runhooks.

To produce an executable built with a custom PGO profile:

• Produce the instrumented executable using the following gn args:

  chrome_pgo_phase = 1
  enable_resource_allowlist_generation = false
  is_official_build = true
  symbol_level = 0
  use_remoteexec = true
  

  For android you need these in addition:

  target_os = "android"
  target_cpu = "arm64"
  

• Run representative benchmarks to produce profiles

  python3 tools/pgo/generate_profile.py -C out/builddir

  If collecting profiles on an android device, add a browser name like one of these:

  python3 tools/pgo/generate_profile.py -C out/builddir \
      --android-browser android-trichrome-chrome-google-bundle
  

  You can find available browsers using:

  tools/perf/run_benchmark run --browser=list
  

  By default, some benchmark replay archives require special access permissions. For more details and to request access, please refer to Telemetry documentation. You can also choose to run generate_profile.py without these benchmarks, using the --run-public-benchmarks-only flag. However, note that doing so may produce a profile that isn't fully representative.

  python3 tools/pgo/generate_profile.py -C out/builddir \
     --android-browser android-trichrome-chrome-google-bundle \
     --run-public-benchmarks-only
  

  If generate_profile.py fails with ServiceException: 401 Anonymous caller does not have storage.objects.get access to the Google Cloud Storage object., then run download_from_google_storage --config (with your @google address; enter 0 as project-id).

  This will produce out/builddir/profile.profdata

• Produce the final PGO'd executable with the following gn args (and additional android args, if any):

  enable_resource_allowlist_generation = false
  is_official_build = true
  symbol_level = 0
  use_remoteexec = true
  pgo_data_path = "//out/builddir/profile.profdata"
  

How It Works

chrome_pgo_phase is defined in build/config/compiler/pgo/pgo.gni. This GN variable can be one of 0, 1, or 2, meaning “don't use profile”, “generating profile”, and “use profile” respectively. See pgo.gni for details on platform-specific GN variables that determine which phase is used in each build.

Which file under //chrome/build/pgo_profiles/ gets used? It depends on both the platform and _pgo_target. For example, for 64-bit android, the file //chrome/build/android-arm64.pgo.txt contains the name of the *.profdata file that is used as the PGO profile by default if no other profile is specified via the GN arg pgo_data_path.

Background Reading

https://clang.llvm.org/docs/UsersManual.html#profile-guided-optimization

https://source.android.com/docs/core/perf/pgo