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 <memory>
9 #include <string>
10 
11 #include "base/strings/string_piece.h"
12 #include "base/trace_event/trace_event_impl.h"
13 #include "base/values.h"
14 #include "content/common/content_export.h"
15 
16 namespace content {
17 class BackgroundTracingConfig;
18 
19 // BackgroundTracingManager is used on the browser process to trigger the
20 // collection of trace data and upload the results. Only the browser UI thread
21 // is allowed to interact with the BackgroundTracingManager. All callbacks are
22 // called on the UI thread.
23 class BackgroundTracingManager {
24  public:
25   CONTENT_EXPORT static BackgroundTracingManager* GetInstance();
26 
27   // ReceiveCallback will be called on the UI thread every time the
28   // BackgroundTracingManager finalizes a trace. The first parameter of this
29   // callback is the trace data. The second is metadata that was generated and
30   // embedded into the trace. The third is a callback to notify the
31   // BackgroundTracingManager that you've finished processing the trace data
32   // and whether we were successful or not.
33   //
34   // Example:
35   //
36   // void Upload(const scoped_refptr<base::RefCountedString>& data,
37   //             FinishedProcessingCallback done_callback) {
38   //   base::PostTaskAndReply(
39   //       FROM_HERE, {base::MayBlock(), base::TaskPriority::BEST_EFFORT},
40   //       base::BindOnce(&DoUploadInBackground, data),
41   //       std::move(done_callback));
42   // }
43   //
44   using FinishedProcessingCallback = base::OnceCallback<void(bool success)>;
45   using ReceiveCallback =
46       base::RepeatingCallback<void(std::unique_ptr<std::string>,
47                                    FinishedProcessingCallback)>;
48 
49   // Set the triggering rules for when to start recording.
50   //
51   // In preemptive mode, recording begins immediately and any calls to
52   // TriggerNamedEvent() will potentially trigger the trace to finalize and get
53   // uploaded to the specified upload_sink. Once the trace has been uploaded,
54   // tracing will be enabled again.
55   //
56   // In reactive mode, recording begins when TriggerNamedEvent() is called, and
57   // continues until either the next call to TriggerNamedEvent, or a timeout
58   // occurs. Tracing will not be re-enabled after the trace is finalized and
59   // uploaded to the upload_sink.
60   //
61   // Calls to SetActiveScenario() with a config will fail if tracing is
62   // currently on. Use WhenIdle to register a callback to get notified when
63   // the manager is idle and a config can be set again.
64   enum DataFiltering {
65     NO_DATA_FILTERING,
66     ANONYMIZE_DATA,
67   };
68   virtual bool SetActiveScenario(
69       std::unique_ptr<BackgroundTracingConfig> config,
70       ReceiveCallback receive_callback,
71       DataFiltering data_filtering) = 0;
72 
73   // Notifies the caller when the manager is idle (not recording or uploading),
74   // so that a call to SetActiveScenario() is likely to succeed.
75   using IdleCallback = base::RepeatingCallback<void()>;
76   virtual void WhenIdle(IdleCallback idle_callback) = 0;
77 
78   using StartedFinalizingCallback = base::OnceCallback<void(bool)>;
79   using TriggerHandle = int;
80 
81   // Notifies that a manual trigger event has occurred, and we may need to
82   // either begin recording or finalize the trace, depending on the config.
83   // If the trigger specified isn't active in the config, this will do nothing.
84   virtual void TriggerNamedEvent(
85       TriggerHandle trigger_handle,
86       StartedFinalizingCallback started_callback) = 0;
87 
88   // Registers a manual trigger handle, and returns a TriggerHandle which can
89   // be passed to DidTriggerHappen().
90   virtual TriggerHandle RegisterTriggerType(const char* trigger_name) = 0;
91 
92   virtual bool HasActiveScenario() = 0;
93 
94   // Returns true whether a trace is ready to be uploaded.
95   virtual bool HasTraceToUpload() = 0;
96 
97   // Returns the latest trace created for uploading in a serialized proto of
98   // message type perfetto::Trace.
99   // TODO(ssid): This should also return the trigger for the trace along with
100   // the serialized trace proto.
101   virtual std::string GetLatestTraceToUpload() = 0;
102 
103   // For tests
104   virtual void AbortScenarioForTesting() = 0;
105   virtual void SetTraceToUploadForTesting(
106       std::unique_ptr<std::string> trace_data) = 0;
107 
108  protected:
~BackgroundTracingManager()109   virtual ~BackgroundTracingManager() {}
110 };
111 
112 }  // namespace content
113 
114 #endif  // CONTENT_PUBLIC_BROWSER_BACKGROUND_TRACING_MANAGER_H_
115