1 /* 2 * Copyright (C) 2018 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef INCLUDE_PERFETTO_TRACE_PROCESSOR_TRACE_PROCESSOR_H_ 18 #define INCLUDE_PERFETTO_TRACE_PROCESSOR_TRACE_PROCESSOR_H_ 19 20 #include <memory> 21 #include <vector> 22 23 #include "perfetto/base/build_config.h" 24 #include "perfetto/base/export.h" 25 #include "perfetto/trace_processor/basic_types.h" 26 #include "perfetto/trace_processor/iterator.h" 27 #include "perfetto/trace_processor/metatrace_config.h" 28 #include "perfetto/trace_processor/status.h" 29 #include "perfetto/trace_processor/trace_processor_storage.h" 30 31 namespace perfetto { 32 namespace trace_processor { 33 34 // Extends TraceProcessorStorage to support execution of SQL queries on loaded 35 // traces. See TraceProcessorStorage for parsing of trace files. 36 class PERFETTO_EXPORT_COMPONENT TraceProcessor : public TraceProcessorStorage { 37 public: 38 // For legacy API clients. Iterator used to be a nested class here. Many API 39 // clients depends on it at this point. 40 using Iterator = ::perfetto::trace_processor::Iterator; 41 42 // Creates a new instance of TraceProcessor. 43 static std::unique_ptr<TraceProcessor> CreateInstance(const Config&); 44 45 ~TraceProcessor() override; 46 47 // Executes the SQL on the loaded portion of the trace. 48 // 49 // More than one SQL statement can be passed to this function; all but the 50 // last will be fully executed by this function before retuning. The last 51 // statement will be executed and will yield rows as the caller calls Next() 52 // over the returned Iterator. 53 // 54 // See documentation of the Iterator class for an example on how to use 55 // the returned iterator. 56 virtual Iterator ExecuteQuery(const std::string& sql) = 0; 57 58 // Registers SQL files with the associated path under the module named 59 // |sql_module.name|. These modules can be run by using the |IMPORT| SQL 60 // function. 61 // 62 // For example, if you registered a module called "camera" with a file path 63 // "camera/cpu/metrics.sql" you can import it (run the file) using "SELECT 64 // IMPORT('camera.cpu.metrics');". The first word of the string has to be a 65 // module name and there can be only one module registered with a given name. 66 virtual base::Status RegisterSqlModule(SqlModule sql_module) = 0; 67 68 // Registers a metric at the given path which will run the specified SQL. 69 virtual base::Status RegisterMetric(const std::string& path, 70 const std::string& sql) = 0; 71 72 // Reads the FileDescriptorSet proto message given by |data| and |size| and 73 // adds any extensions to the metrics proto to allow them to be available as 74 // proto builder functions when computing metrics. 75 virtual base::Status ExtendMetricsProto(const uint8_t* data, size_t size) = 0; 76 77 // Behaves exactly as ExtendMetricsProto, except any FileDescriptor with 78 // filename matching a prefix in |skip_prefixes| is skipped. 79 virtual base::Status ExtendMetricsProto( 80 const uint8_t* data, 81 size_t size, 82 const std::vector<std::string>& skip_prefixes) = 0; 83 84 // Computes the given metrics on the loded portion of the trace. If 85 // successful, the output argument |metrics_proto| will be filled with the 86 // proto-encoded bytes for the message TraceMetrics in 87 // perfetto/metrics/metrics.proto. 88 virtual base::Status ComputeMetric( 89 const std::vector<std::string>& metric_names, 90 std::vector<uint8_t>* metrics_proto) = 0; 91 92 enum MetricResultFormat { 93 kProtoText = 0, 94 kJson = 1, 95 }; 96 97 // Computes metrics as the ComputeMetric function above, but instead of 98 // producing proto encoded bytes, the output argument |metrics_string| is 99 // filled with the metric formatted in the requested |format|. 100 virtual base::Status ComputeMetricText( 101 const std::vector<std::string>& metric_names, 102 MetricResultFormat format, 103 std::string* metrics_string) = 0; 104 105 // Interrupts the current query. Typically used by Ctrl-C handler. 106 virtual void InterruptQuery() = 0; 107 108 // Deletes all tables and views that have been created (by the UI or user) 109 // after the trace was loaded. It preserves the built-in tables/view created 110 // by the ingestion process. Returns the number of table/views deleted. 111 virtual size_t RestoreInitialTables() = 0; 112 113 // Sets/returns the name of the currently loaded trace or an empty string if 114 // no trace is fully loaded yet. This has no effect on the Trace Processor 115 // functionality and is used for UI purposes only. 116 // The returned name is NOT a path and will contain extra text w.r.t. the 117 // argument originally passed to SetCurrentTraceName(), e.g., "file (42 MB)". 118 virtual std::string GetCurrentTraceName() = 0; 119 virtual void SetCurrentTraceName(const std::string&) = 0; 120 121 // Enables "meta-tracing" of trace processor. 122 // Metatracing involves tracing trace processor itself to root-cause 123 // performace issues in trace processor. See |DisableAndReadMetatrace| for 124 // more information on the format of the metatrace. 125 using MetatraceConfig = metatrace::MetatraceConfig; 126 using MetatraceCategories = metatrace::MetatraceCategories; 127 virtual void EnableMetatrace(MetatraceConfig config = {}) = 0; 128 129 // Disables "meta-tracing" of trace processor and writes the trace as a 130 // sequence of |TracePackets| into |trace_proto| returning the status of this 131 // read. 132 virtual base::Status DisableAndReadMetatrace( 133 std::vector<uint8_t>* trace_proto) = 0; 134 135 // Gets all the currently loaded proto descriptors used in metric computation. 136 // This includes all compiled-in binary descriptors, and all proto descriptors 137 // loaded by trace processor shell at runtime. The message is encoded as 138 // DescriptorSet, defined in perfetto/trace_processor/trace_processor.proto. 139 virtual std::vector<uint8_t> GetMetricDescriptors() = 0; 140 }; 141 142 // When set, logs SQLite actions on the console. 143 void PERFETTO_EXPORT_COMPONENT EnableSQLiteVtableDebugging(); 144 145 } // namespace trace_processor 146 } // namespace perfetto 147 148 #endif // INCLUDE_PERFETTO_TRACE_PROCESSOR_TRACE_PROCESSOR_H_ 149