172062f5744557e270a38192554c3126ea5f97434Tim Northover# Copyright 2014 The Chromium Authors. All rights reserved.
272062f5744557e270a38192554c3126ea5f97434Tim Northover# Use of this source code is governed by a BSD-style license that can be
372062f5744557e270a38192554c3126ea5f97434Tim Northover# found in the LICENSE file.
472062f5744557e270a38192554c3126ea5f97434Tim Northover
572062f5744557e270a38192554c3126ea5f97434Tim Northoverclass TracingController(object):
672062f5744557e270a38192554c3126ea5f97434Tim Northover  def __init__(self, tracing_controller_backend):
772062f5744557e270a38192554c3126ea5f97434Tim Northover    """Provides control of the tracing systems supported by telemetry."""
872062f5744557e270a38192554c3126ea5f97434Tim Northover    self._tracing_controller_backend = tracing_controller_backend
972062f5744557e270a38192554c3126ea5f97434Tim Northover
1072062f5744557e270a38192554c3126ea5f97434Tim Northover  def Start(self, trace_options, category_filter, timeout=10):
1172062f5744557e270a38192554c3126ea5f97434Tim Northover    """Starts tracing.
12dce4a407a24b04eebc6a376f8e62b41aaa7b071fStephen Hines
1372062f5744557e270a38192554c3126ea5f97434Tim Northover    trace_options specifies which tracing systems to activate. Category filter
1472062f5744557e270a38192554c3126ea5f97434Tim Northover    allows fine-tuning of the data that are collected by the selected tracing
1572062f5744557e270a38192554c3126ea5f97434Tim Northover    systems.
16
17    Some tracers are process-specific, e.g. chrome tracing, but are not
18    guaranteed to be supported. In order to support tracing of these kinds of
19    tracers, Start will succeed *always*, even if the tracing systems you have
20    requested are not supported.
21
22    If you absolutely require a particular tracer to exist, then check
23    for its support after you have started the process in question. Or, have
24    your code fail gracefully when the data you require is not present in the
25    resulting trace.
26    """
27    self._tracing_controller_backend.Start(
28        trace_options, category_filter, timeout)
29
30  def Stop(self):
31    """Stops tracing and returns a TraceValue."""
32    return self._tracing_controller_backend.Stop()
33
34  @property
35  def is_tracing_running(self):
36    return self._tracing_controller_backend.is_tracing_running
37
38  def IsChromeTracingSupported(self, browser):
39    """Returns whether chrome tracing is supported on the given browser."""
40    return self._tracing_controller_backend.IsChromeTracingSupported(browser)
41