1 // Copyright 2018 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 package org.chromium.content_public.browser; 6 7 import android.content.Context; 8 import android.util.Pair; 9 10 import org.chromium.base.Callback; 11 import org.chromium.content.browser.TracingControllerAndroidImpl; 12 13 /** 14 * Controller for Chrome's tracing feature. The embedder may use this class to implement a UI for 15 * recording and sharing Chrome performance traces. 16 */ 17 public interface TracingControllerAndroid { 18 /** 19 * Creates a new TracingControllerAndroid instance. 20 * 21 * @param context the Context in which to create the controller. 22 * @return the controller. 23 */ create(Context context)24 public static TracingControllerAndroid create(Context context) { 25 return new TracingControllerAndroidImpl(context); 26 } 27 28 /** 29 * @return true if a trace is being recorded. 30 */ isTracing()31 boolean isTracing(); 32 33 /** 34 * @return the path of the current output file. Null if isTracing() false. 35 */ getOutputPath()36 String getOutputPath(); 37 38 /** 39 * Start recording a trace to the specified file (if not null) or to a new file in the Downloads 40 * directory. 41 * 42 * Only one TracingControllerAndroid can be running at the same time. If another profiler is 43 * running when this method is called, it will be cancelled. If this profiler is already 44 * running, this method does nothing and returns false. 45 * 46 * @param filename The name of the file to output the profile data to, or null. 47 * @param showToasts Whether or not we want to show toasts during this profiling session. 48 * When we are timing the profile run we might not want to incur extra draw overhead of showing 49 * notifications about the profiling system, or the embedder may want to show such notifications 50 * themselves. 51 * @param categories Which categories to trace. See TracingController::StartTracing() 52 * (in content/public/browser/tracing_controller.h) for the format. 53 * @param traceOptions Which trace options to use. See 54 * TraceOptions::TraceOptions(const std::string& options_string) 55 * (in base/trace_event/trace_event_impl.h) for the format. 56 * @param compressFile Whether the trace file should be compressed (gzip). 57 * @param useProtobuf Whether to generate a binary protobuf trace or use 58 * the legacy JSON format. 59 * @return Whether tracing was started successfully. 60 */ startTracing(String filename, boolean showToasts, String categories, String traceOptions, boolean compressFile, boolean useProtobuf)61 boolean startTracing(String filename, boolean showToasts, String categories, 62 String traceOptions, boolean compressFile, boolean useProtobuf); 63 64 /** 65 * Stop recording and run |callback| when stopped. 66 * 67 * @param callback the Callback executed when tracing has stopped. 68 */ stopTracing(Callback<Void> callback)69 void stopTracing(Callback<Void> callback); 70 71 /** 72 * Get known tracing categories and run |callback| with the set of known categories. 73 * 74 * @param callback the callback that receives the result. 75 * @return whether initiating the request was successful. 76 */ getKnownCategories(Callback<String[]> callback)77 boolean getKnownCategories(Callback<String[]> callback); 78 79 /** 80 * Get the current estimated trace buffer usage and approximate total event count in the buffer. 81 * 82 * @param callback the callback that receives the result as a Pair of (percentage_full, 83 * approximate_event_count). 84 * @return whether initiating the request was successful. 85 */ getTraceBufferUsage(Callback<Pair<Float, Long>> callback)86 boolean getTraceBufferUsage(Callback<Pair<Float, Long>> callback); 87 88 /** 89 * Clean any native dependencies of the controller. After the call, this class instance 90 * shouldn't be used. 91 */ destroy()92 void destroy(); 93 } 94