TimelineBasedMeasurement(object) instead of TimelineBasedMeasurement(page_test.PageTest)

tools/telemetry/telemetry/web_perf/timeline_based_measurement.py

 # Copyright 2014 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.
 
 from collections import defaultdict
 
 from telemetry.core.platform import tracing_category_filter
 from telemetry.core.platform import tracing_options
 from telemetry.page import page_test
 from telemetry.timeline import model as model_module
@@ skipping 93 matching lines @@
       if not interactions_with_metric:
         continue
       if len(interactions_with_metric) != len(interactions):
         raise InvalidInteractions('Interaction records with the same logical '
                                   'name must have the same flags.')
       metric = self._get_metric_from_metric_type_callback(metric_type)
       metric.AddResults(self._model, self._renderer_thread,
                         interactions, wrapped_results)
 
 
-class TimelineBasedMeasurement(page_test.PageTest):
-  """Collects multiple metrics pages based on their interaction records.
+class Options(object):
+  """A class to be used to configure TimelineBasedMeasurement.
 
-  A timeline measurement shifts the burden of what metrics to collect onto the
-  page under test, or the pageset running that page. Instead of the measurement
-  having a fixed set of values it collects about the page, the page being tested
+  This is created and returned by
+  Benchmark.CreateTimelineBasedMeasurementOptions.
+  """
+
+  def __init__(self, overhead_level=NO_OVERHEAD_LEVEL):
+    """Save the overhead level.
+
+    As the amount of instrumentation increases, so does the overhead.
+    The user of the measurement chooses the overhead level that is appropriate,
+    and the tracing is filtered accordingly.
+
+    overhead_level: one of NO_OVERHEAD_LEVEL, V8_OVERHEAD_LEVEL,
+        MINIMAL_OVERHEAD_LEVEL, or DEBUG_OVERHEAD_LEVEL.
+        The v8 overhead level is a temporary solution that may be removed.
+    """
+    self._overhead_level = overhead_level
+
+
+class TimelineBasedMeasurement(object):
+  """Collects multiple metrics based on their interaction records.
+
+  A timeline based measurement shifts the burden of what metrics to collect onto
+  the user story under test. Instead of the measurement
+  having a fixed set of values it collects, the user story being tested
   issues (via javascript) an Interaction record into the user timing API that
-  describing what the page is doing at that time, as well as a standardized set
+  describing what is happening at that time, as well as a standardized set
   of flags describing the semantics of the work being done. The
   TimelineBasedMeasurement object collects a trace that includes both these
-  interaction recorsd, and a user-chosen amount of performance data using
+  interaction records, and a user-chosen amount of performance data using
   Telemetry's various timeline-producing APIs, tracing especially.
 
   It then passes the recorded timeline to different TimelineBasedMetrics based
-  on those flags. This allows a single run through a page to produce load timing
-  data, smoothness data, critical jank information and overall cpu usage
-  information.
+  on those flags. As an example, this allows a single user story run to produce
+  load timing data, smoothness data, critical jank information and overall cpu
+  usage information.
 
   For information on how to mark up a page to work with
   TimelineBasedMeasurement, refer to the
   perf.metrics.timeline_interaction_record module.
+  """
+  def __init__(self, options):
+    self._overhead_level = options._overhead_level
 
-  """
-  def __init__(self, overhead_level=NO_OVERHEAD_LEVEL):
-    super(TimelineBasedMeasurement, self).__init__('RunPageInteractions')
-    self._overhead_level = overhead_level
+  def StartTracing(self, app, synthetic_delay_categories=None):

[nednguyen, 2014/12/19 01:16:21]

s/StartTracing/WillRunTest
also
s/StopTracing/DidRunTest

[slamm, 2015/01/02 23:47:20]

Done.

+    """Configure and start tracing.
 
-  def WillNavigateToPage(self, page, tab):
-    if not tab.browser.platform.tracing_controller.IsChromeTracingSupported(
-        tab.browser):
+    Args:
+      app: an app.App subclass instance.
+      synthetic_delay_categories: iterable of delays. For example:
+          ['DELAY(cc.BeginMainFrame;0.014;alternating)']
+          where 'cc.BeginMainFrame' is a timeline event, 0.014 is the delay,
+          and 'alternating' is the mode.
+    """
+    if not app.platform.tracing_controller.IsChromeTracingSupported(app):
       raise Exception('Not supported')
 
     assert self._overhead_level in ALL_OVERHEAD_LEVELS
     if self._overhead_level == NO_OVERHEAD_LEVEL:
       category_filter = tracing_category_filter.CreateNoOverheadFilter()
     # TODO(ernstm): Remove this overhead level when benchmark relevant v8 events
     # become available in the 'benchmark' category.
     elif self._overhead_level == V8_OVERHEAD_LEVEL:
       category_filter = tracing_category_filter.CreateNoOverheadFilter()
       category_filter.AddIncludedCategory('v8')
     elif self._overhead_level == MINIMAL_OVERHEAD_LEVEL:
       category_filter = tracing_category_filter.CreateMinimalOverheadFilter()
     else:
       category_filter = tracing_category_filter.CreateDebugOverheadFilter()
 
-    for delay in page.GetSyntheticDelayCategories():
+    # TODO(slamm): Move synthetic_delay_categories to the TBM options.
+    for delay in synthetic_delay_categories or []:
       category_filter.AddSyntheticDelay(delay)
     options = tracing_options.TracingOptions()
     options.enable_chrome_trace = True
-    tab.browser.platform.tracing_controller.Start(options, category_filter)
+    app.platform.tracing_controller.Start(options, category_filter)
 
-  def ValidateAndMeasurePage(self, page, tab, results):
-    """ Collect all possible metrics and added them to results. """
-    trace_result = tab.browser.platform.tracing_controller.Stop()
+  def Measure(self, app, renderer_thread_tab_id, results):
+    """Collect all possible metrics and added them to results."""
+    trace_result = app.platform.tracing_controller.Stop()
     results.AddValue(trace.TraceValue(results.current_page, trace_result))
     model = model_module.TimelineModel(trace_result)
-    renderer_thread = model.GetRendererThreadFromTabId(tab.id)
+    renderer_thread = model.GetRendererThreadFromTabId(renderer_thread_tab_id)
     meta_metrics = _TimelineBasedMetrics(
         model, renderer_thread, _GetMetricFromMetricType)
     meta_metrics.AddResults(results)
 
+  def StopTracing(self, app):
+    if app.platform.tracing_controller.is_tracing_running:
+      app.platform.tracing_controller.Stop()
+
+
+class TimelineBasedPageTest(page_test.PageTest):
+  """Page test that collects metrics with TimelineBasedMeasurement."""
+  def __init__(self, tbm):
+    super(TimelineBasedPageTest, self).__init__('RunPageInteractions')
+    self._measurement = tbm
+
+  @property
+  def measurement(self):
+    return self._measurement
+
+  def WillNavigateToPage(self, page, tab):
+    self._measurement.StartTracing(
+        tab.browser, page.GetSyntheticDelayCategories())
+
+  def ValidateAndMeasurePage(self, page, tab, results):
+    """Collect all possible metrics and added them to results."""
+    self._measurement.Measure(tab.browser, tab.id, results)
 
   def CleanUpAfterPage(self, page, tab):
-    if tab.browser.platform.tracing_controller.is_tracing_running:
-      tab.browser.platform.tracing_controller.Stop()
+    self._measurement.StopTracing(tab.browser)