src/content/public/browser/trace_controller.h

   1 // Copyright (c) 2012 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 #ifndef CONTENT_PUBLIC_BROWSER_TRACE_CONTROLLER_H_
   6 #define CONTENT_PUBLIC_BROWSER_TRACE_CONTROLLER_H_
   7
   8 #include "base/debug/trace_event.h"
   9 #include "content/common/content_export.h"
  10
  11 namespace content {
  12
  13 class TraceSubscriber;
  14
  15 // Note: TraceController is going to be deprecated and replaced with
  16 // TracingController.
  17 //
  18 // TraceController is used on the browser processes to enable/disable
  19 // trace status and collect trace data. Only the browser UI thread is allowed
  20 // to interact with the TraceController object. All calls on the TraceSubscriber
  21 // happen on the UI thread.
  22 class TraceController {
  23  public:
  24   CONTENT_EXPORT static TraceController* GetInstance();
  25
  26   // Called by browser process to start tracing events on all processes.
  27   //
  28   // Currently only one subscriber is allowed at a time.
  29   // Tracing begins immediately locally, and asynchronously on child processes
  30   // as soon as they receive the BeginTracing request.
  31   //
  32   // If BeginTracing was already called previously,
  33   //   or if an EndTracingAsync is pending,
  34   //   or if another subscriber is tracing,
  35   //   BeginTracing will return false meaning it failed.
  36   //
  37   // |category_patterns| is a comma-delimited list of category wildcards.
  38   // A category pattern can have an optional '-' prefix to exclude category
  39   // groups that contain a matching category.
  40   // All the same rules apply above, so for example, having both included and
  41   // excluded category patterns in the same list would not be supported.
  42   //
  43   // |mode| is the tracing mode being used.
  44   //
  45   // Example: BeginTracing("test_MyTest*");
  46   // Example: BeginTracing("test_MyTest*,test_OtherStuff");
  47   // Example: BeginTracing("-excluded_category1,-excluded_category2");
  48   virtual bool BeginTracing(TraceSubscriber* subscriber,
  49                             const std::string& category_patterns,
  50                             base::debug::TraceLog::Options options) = 0;
  51
  52   // Called by browser process to stop tracing events on all processes.
  53   //
  54   // Child processes typically are caching trace data and only rarely flush
  55   // and send trace data back to the browser process. That is because it may be
  56   // an expensive operation to send the trace data over IPC, and we would like
  57   // to avoid much runtime overhead of tracing. So, to end tracing, we must
  58   // asynchronously ask all child processes to flush any pending trace data.
  59   //
  60   // Once all child processes have acked the EndTracing request,
  61   // TraceSubscriber will be called with OnEndTracingComplete.
  62   //
  63   // If a previous call to EndTracingAsync is already pending,
  64   //   or if another subscriber is tracing,
  65   //   EndTracingAsync will return false meaning it failed.
  66   virtual bool EndTracingAsync(TraceSubscriber* subscriber) = 0;
  67
  68   // Get the maximum across processes of trace buffer percent full state.
  69   // When the TraceBufferPercentFull value is determined,
  70   // subscriber->OnTraceBufferPercentFullReply is called.
  71   // When any child process reaches 100% full, the TraceController will end
  72   // tracing, and call TraceSubscriber::OnEndTracingComplete.
  73   // GetTraceBufferPercentFullAsync fails in the following conditions:
  74   //   trace is ending or disabled;
  75   //   a previous call to GetTraceBufferPercentFullAsync is pending; or
  76   //   the caller is not the current subscriber.
  77   virtual bool GetTraceBufferPercentFullAsync(TraceSubscriber* subscriber) = 0;
  78
  79   // |subscriber->OnEventWatchNotification()| will be called every time the
  80   // given event occurs on any process.
  81   virtual bool SetWatchEvent(TraceSubscriber* subscriber,
  82                              const std::string& category_name,
  83                              const std::string& event_name) = 0;
  84
  85   // Cancel the watch event. If tracing is enabled, this may race with the
  86   // watch event notification firing.
  87   virtual bool CancelWatchEvent(TraceSubscriber* subscriber) = 0;
  88
  89   // Cancel the subscriber so that it will not be called when EndTracingAsync is
  90   // acked by all child processes. This will also call EndTracingAsync
  91   // internally if necessary.
  92   // Safe to call even if caller is not the current subscriber.
  93   virtual void CancelSubscriber(TraceSubscriber* subscriber) = 0;
  94
  95   // Get set of known category groups. This can change as new code paths are
  96   // reached. If true is returned, subscriber->OnKnownCategoriesCollected will
  97   // be called once the categories are retrieved from child processes.
  98   virtual bool GetKnownCategoryGroupsAsync(TraceSubscriber* subscriber) = 0;
  99
 100  protected:
 101   virtual ~TraceController() {}
 102 };
 103
 104 }  // namespace content
 105
 106 #endif  // CONTENT_PUBLIC_BROWSER_TRACE_CONTROLLER_H_
 107