content/public/browser/background_tracing_manager.h

   1 // Copyright 2015 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_BACKGROUND_TRACING_MANAGER_H_
   6 #define CONTENT_PUBLIC_BROWSER_BACKGROUND_TRACING_MANAGER_H_
   7
   8 #include "base/trace_event/trace_event_impl.h"
   9 #include "base/values.h"
  10 #include "content/common/content_export.h"
  11
  12 namespace content {
  13 struct BackgroundTracingConfig;
  14 struct BackgroundTracingUploadConfig;
  15
  16 // BackgroundTracingManager is used on the browser process to trigger the
  17 // collection of trace data and upload the results. Only the browser UI thread
  18 // is allowed to interact with the BackgroundTracingManager. All callbacks are
  19 // called on the UI thread.
  20 class BackgroundTracingManager {
  21  public:
  22   CONTENT_EXPORT static BackgroundTracingManager* GetInstance();
  23
  24   // ReceiveCallback will will be called on the UI thread every time the
  25   // BackgroundTracingManager finalizes a trace. The first parameter of
  26   // this callback is the trace data. The second is metadata that was
  27   // generated and embedded into the trace. The third is a callback to
  28   // notify the BackgroundTracingManager that you've finished processing
  29   // the trace data.
  30   //
  31   // Example:
  32   //
  33   // void Upload(const scoped_refptr<base::RefCountedString>& data,
  34   //             scoped_ptr<base::DictionaryValue>,
  35   //             base::Closure done_callback) {
  36   //   BrowserThread::PostTaskAndReply(
  37   //       BrowserThread::FILE,
  38   //       FROM_HERE,
  39   //       base::Bind(&DoUploadOnFileThread, data),
  40   //       done_callback
  41   //     );
  42   // }
  43   //
  44   typedef base::Callback<void(const scoped_refptr<base::RefCountedString>&,
  45                               scoped_ptr<base::DictionaryValue>,
  46                               base::Closure)> ReceiveCallback;
  47
  48   // Set the triggering rules for when to start recording.
  49   //
  50   // In preemptive mode, recording begins immediately and any calls to
  51   // TriggerNamedEvent() will potentially trigger the trace to finalize and get
  52   // uploaded to the specified upload_sink. Once the trace has been uploaded,
  53   // tracing will be enabled again.
  54   //
  55   // In reactive mode, recording begins when TriggerNamedEvent() is called, and
  56   // continues until either the next call to TriggerNamedEvent, or a timeout
  57   // occurs. Tracing will not be re-enabled after the trace is finalized and
  58   // uploaded to the upload_sink.
  59   //
  60   // Calls to SetActiveScenario() with a config will fail if tracing is
  61   // currently on. Use WhenIdle to register a callback to get notified when
  62   // the manager is idle and a config can be set again.
  63   enum DataFiltering {
  64     NO_DATA_FILTERING,
  65     ANONYMIZE_DATA,
  66   };
  67   virtual bool SetActiveScenario(scoped_ptr<BackgroundTracingConfig> config,
  68                                  const ReceiveCallback& receive_callback,
  69                                  DataFiltering data_filtering) = 0;
  70
  71   // Notifies the caller when the manager is idle (not recording or uploading),
  72   // so that a call to SetActiveScenario() is likely to succeed.
  73   typedef base::Callback<void()> IdleCallback;
  74   virtual void WhenIdle(IdleCallback idle_callback) = 0;
  75
  76   typedef base::Callback<void(bool)> StartedFinalizingCallback;
  77   typedef int TriggerHandle;
  78
  79   // Notifies that a manual trigger event has occurred, and we may need to
  80   // either begin recording or finalize the trace, depending on the config.
  81   // If the trigger specified isn't active in the config, this will do nothing.
  82   virtual void TriggerNamedEvent(
  83       TriggerHandle trigger_handle,
  84       StartedFinalizingCallback started_callback) = 0;
  85
  86   // Registers a manual trigger handle, and returns a TriggerHandle which can
  87   // be passed to DidTriggerHappen().
  88   virtual TriggerHandle RegisterTriggerType(const char* trigger_name) = 0;
  89
  90   // Returns a list of all registered triggers.
  91   virtual void GetTriggerNameList(std::vector<std::string>* trigger_names) = 0;
  92
  93   virtual void InvalidateTriggerHandlesForTesting() = 0;
  94   virtual void SetTracingEnabledCallbackForTesting(
  95       const base::Closure& callback) = 0;
  96   virtual void FireTimerForTesting() = 0;
  97   virtual bool HasActiveScenarioForTesting() = 0;
  98
  99  protected:
 100   virtual ~BackgroundTracingManager() {}
 101 };
 102
 103 }  // namespace content
 104
 105 #endif  // CONTENT_PUBLIC_BROWSER_BACKGROUND_TRACING_MANAGER_H_