Tab Search: Add benchmark documentation

Bug: 1099917
Change-Id: I1eaf5e9c70961d98cf0fe2fbc11d3455b5e892bb
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/2558912
Commit-Queue: Yuheng Huang <yuhengh@chromium.org>
Reviewed-by: John Chen <johnchen@chromium.org>
Cr-Commit-Position: refs/heads/master@{#830790}

docs/speed/benchmark/harnesses/tab_search.md

+# Tab Search Benchmark
+
+## Overview
+
+Tab Search Benchmark is used to measure and monitor Tab Search Web UI performance.
+It captures important metrics such as
+
+* Initial load time
+* Subsequent load time
+* Fetch data time
+* Search user input time
+* Frame time when scrolling
+
+in different stories representing different scenarios
+* tab_search:top10:2020 - Test CUJs with 10 open tabs, after all tabs are loaded
+* tab_search:top50:2020 - Test CUJs with 50 open tabs, after all tabs are loaded
+* tab_search:top100:2020 - Test CUJs with 100 open tabs, after all tabs are loaded
+* tab_search:top10:loading:2020 - Test CUJs with 10 open tabs, before all tabs are loaded
+* tab_search:top50:loading:2020 - Test CUJs with 50 open tabs, before all tabs are loaded
+* tab_search:top100:loading:2020 - Test CUJs with 100 open tabs, before all tabs are loaded
+* tab_search:close_and_open:2020 - Test open, close and reopen Tab Search UI
+
+
+For more information please see this [doc](https://docs.google.com/document/d/1-1ijT7wt05hlBZmSKjX_DaTCzVqpxbfTM1y-j7kYHlc).
+
+## Run the benchmark on pinpoint
+
+In most cases, you only need to run the benchmark on [pinpoint](https://pinpoint-dot-chromeperf.appspot.com/) before/after a CL that may have performance impact. If you don't have platform requirement linux-perf is recommended since they are the most stable trybots for this benchmark.
+
+
+## Run the benchmark locally
+
+In some cases, if trybots cannot meet your requirement or you need to debug on your own machine, use the following command to run the benchmark locally. You need an @google account to be able to do that.
+
+```
+tools/perf/run_benchmark run tab_search --browser-executable=out/Default/chrome --story-filter=tab_search:top10:2020 --pageset-repeat=3
+```
+
+
+## Add new metrics
+
+There are 3 ways to add metrics to the benchmarking code
+
+1. Add UMA metrics to your code and include them in the [benchmark definition](../../../../tools/perf/benchmark/tab_search.py). The listed UMA metrics will show up on the result page automatically.
+2. Add C++ trace with name starts with "webui_metric:". Make sure your trace has category "browser" or add other categories that you use to the benchmark definition. For example:
+   ```c++
+   void Foo::DoWork() {
+     TRACE_EVENT0("browser", "webui_metric:Foo:DoWork");
+     ...
+   }
+   ```
+3. Add Javascript performance.mark() with names end with ":benchmark_begin" and ":benchmark_end". Time between performance.mark('YOUR_METRIC_NAME:benchmark_begin') and performance.mark('YOUR_METRIC_NAME:benchmark') will show up as YOUR_METRIC_NAME on the result page. For example:
+   ```javascript
+   function calc() {
+     performance.mark('calc_time:benchmark_begin');
+     ...
+     performance.mark('calc_time:benchmark_end');
+   }
+   ```
+
+## Record new stories
+
+Add new stories to [here](../../../../tools/perf/page_sets/tab_search/tab_search_stories.py).
+Generally we want to put most of the user journeys in the main story so we only need to run 1 story to verify a CL in most cases. However, if the user journey may affect metrics of other user journeys (e.g. close and reopen Tab Search UI), you should make it a separate story.
+
+Use the following command to record a story
+```
+tools/perf/record_wpr --browser-executable=out/Default/chrome tab_search --story-filter=<YOUR_STORY_NAME>
+```
+and the following command to upload to the cloud.
+```
+upload_to_google_storage.py --bucket chrome-partner-telemetry tools/perf/page_sets/data/tab_search_desktop_<YOUR_RECORDED_HASH>.wprgo
+```
\ No newline at end of file

tools/perf/benchmark.csv

@@ -60,7 +60,7 @@ system_health.memory_desktop,"pasko@chromium.org, lizeb@chromium.org",,https://b
 system_health.memory_mobile,"pasko@chromium.org, lizeb@chromium.org",,https://bit.ly/system-health-benchmarks,"2016,2018,2019,2020,emerging_market,health_check,images,infinite_scroll,international,javascript_heavy"
 system_health.weblayer_startup,"cduvall@chromium.org, weblayer-team@chromium.org",Internals>WebLayer,https://bit.ly/36XBtpn,2016
 system_health.webview_startup,"oksamyt@chromium.org, torne@chromium.org, changwan@chromium.org",Mobile>WebView>Perf,,2016
-tab_search,"yuhengh@chromium.org, tluk@chromium.org, romanarora@chromium.org",UI>Browser>TabSearch,,
+tab_search,"yuhengh@chromium.org, tluk@chromium.org, romanarora@chromium.org",UI>Browser>TabSearch,https://chromium.googlesource.com/chromium/src/+/master/docs/speed/benchmark/harnesses/tab_search.md,
 tab_switching.typical_25,vovoy@chromium.org,OS>Performance,,"2016,tabs_switching"
 tracing.tracing_with_background_memory_infra,ssid@chromium.org,,,
 tracing_perftests,"eseckler@chromium.org, oysteine@chromium.org",Speed>Tracing,,

tools/perf/benchmarks/tab_search.py

@@ -29,10 +29,14 @@ TAB_SEARCH_BENCHMARK_UMA = [
 ]
 
 
-@benchmark.Info(emails=[
-    'yuhengh@chromium.org', 'tluk@chromium.org', 'romanarora@chromium.org'
-],
-                component='UI>Browser>TabSearch')
+@benchmark.Info(
+    emails=[
+        'yuhengh@chromium.org', 'tluk@chromium.org', 'romanarora@chromium.org'
+    ],
+    component='UI>Browser>TabSearch',
+    documentation_url=
+    'https://chromium.googlesource.com/chromium/src/+/master/docs/speed/benchmark/harnesses/tab_search.md'
+)
 class TabSearch(perf_benchmark.PerfBenchmark):
   """Tab Search Benchmark."""
   PLATFORM = 'desktop'

tools/perf/core/undocumented_benchmarks.py

@@ -24,7 +24,6 @@ UNDOCUMENTED_BENCHMARKS = {
     'speedometer2-future',
     'startup.mobile',
     'system_health.webview_startup',
-    'tab_search',
     'tab_switching.typical_25',
     'tracing.tracing_with_background_memory_infra',
     'tracing_perftests',