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 6 class 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
