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