1# Copyright 2014 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
6class TracingAgent(object):
7  """A tracing agent provided by the platform.
8
9  A tracing agent can gather data with Start() until Stop().
10  Before constructing an TracingAgent, check whether it's supported on the
11  platform with IsSupported method first.
12
13  NOTE: All subclasses of TracingAgent must not change the constructor's
14  parameters so the agents can be dynamically constructed in
15  tracing_controller_backend.
16
17  """
18
19  def __init__(self, platform_backend):
20    self._platform_backend = platform_backend
21
22  @classmethod
23  def IsSupported(cls, platform_backend):
24    del platform_backend  # unused
25    return False
26
27  def StartAgentTracing(self, config, timeout):
28    """ Override to add tracing agent's custom logic to start tracing.
29
30    Depending on trace_options and category_filter, the tracing agent may choose
31    to start or not start tracing.
32
33    Args:
34      config: tracing_config instance that contains trace_option and
35        category_filter
36        trace_options: an instance of tracing_options.TracingOptions that
37          control which core tracing systems should be enabled.
38        category_filter: an instance of
39          chrome_trace_category_filter.ChromeTraceCategoryFilter
40      timeout: number of seconds that this tracing agent should try to start
41        tracing until time out.
42
43    Returns:
44      True if tracing agent started successfully.
45    """
46    raise NotImplementedError
47
48  def StopAgentTracing(self):
49    """ Override to add tracing agent's custom logic to stop tracing.
50
51    StopAgentTracing() should guarantee tracing is stopped, even if there may
52    be exception.
53    """
54    raise NotImplementedError
55
56  def SupportsFlushingAgentTracing(self):
57    """ Override to indicate support of flushing tracing. """
58    return False
59
60  def FlushAgentTracing(self, config, timeout, trace_data_builder):
61    """ Override to add tracing agent's custom logic to flush tracing. """
62    del config, timeout, trace_data_builder  # unused
63    raise NotImplementedError
64
65  def SupportsExplicitClockSync(self):
66    """ Override to indicate support of explicit clock syncing. """
67    return False
68
69  def RecordClockSyncMarker(self, sync_id,
70                            record_controller_clocksync_marker_callback):
71    """ Override to record clock sync marker.
72
73    Only override if supports explicit clock syncing.
74    Args:
75      sync_id: Unqiue id for sync event.
76      record_controller_clocksync_marker_callback: Function that accepts two
77        arguments: a sync ID and a timestamp taken immediately before the
78        controller requested that the agent write a clock sync marker into its
79        trace. Any tracing agent that implements this method must invoke this
80        callback immediately after receiving confirmation from the agent that
81        the clock sync marker was recorded.
82
83        We use a callback here rather than just calling this function after
84        RecordClockSyncMarker because it's important for clock sync accuracy
85        reasons that the "issued" timestamp and "received confirmation"
86        timestamp be as accurate as possible, and some agents are forced to do
87        additional time-consuming cleanup work in RecordClockSyncMarker after
88        receiving this confirmation.
89    """
90    del sync_id # unused
91    del record_controller_clocksync_marker_callback # unused
92    raise NotImplementedError
93
94  def CollectAgentTraceData(self, trace_data_builder, timeout=None):
95    """ Override to add agent's custom logic to collect tracing data. """
96    del trace_data_builder
97    del timeout
98    raise NotImplementedError
99