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 <cstddef> 21 #include <cstdint> 22 #include <memory> 23 #include <string> 24 #include <vector> 25 26 #include "perfetto/base/export.h" 27 #include "perfetto/base/status.h" 28 #include "perfetto/trace_processor/basic_types.h" 29 #include "perfetto/trace_processor/iterator.h" 30 #include "perfetto/trace_processor/metatrace_config.h" 31 #include "perfetto/trace_processor/trace_blob_view.h" 32 #include "perfetto/trace_processor/trace_processor_storage.h" 33 34 namespace perfetto::trace_processor { 35 36 // Extends TraceProcessorStorage to support execution of SQL queries on loaded 37 // traces. See TraceProcessorStorage for parsing of trace files. 38 class PERFETTO_EXPORT_COMPONENT TraceProcessor : public TraceProcessorStorage { 39 public: 40 // For legacy API clients. Iterator used to be a nested class here. Many API 41 // clients depends on it at this point. 42 using Iterator = ::perfetto::trace_processor::Iterator; 43 44 // Creates a new instance of TraceProcessor. 45 static std::unique_ptr<TraceProcessor> CreateInstance(const Config&); 46 47 ~TraceProcessor() override; 48 49 // ================================================================= 50 // | PerfettoSQL related functionality starts here | 51 // ================================================================= 52 53 // Executes the SQL on the loaded portion of the trace. 54 // 55 // More than one SQL statement can be passed to this function; all but the 56 // last will be fully executed by this function before retuning. The last 57 // statement will be executed and will yield rows as the caller calls Next() 58 // over the returned Iterator. 59 // 60 // See documentation of the Iterator class for an example on how to use 61 // the returned iterator. 62 virtual Iterator ExecuteQuery(const std::string& sql) = 0; 63 64 // Registers SQL files with the associated path under the package named 65 // |sql_package.name|. 66 // 67 // For example, if you registered a package called "camera" with a file path 68 // "camera/cpu/metrics.sql" you can include it (run the file) using "INCLUDE 69 // PERFETTO MODULE camera.cpu.metrics". The first word of the string has to be 70 // a package name and there can be only one package registered with a given 71 // name. 72 virtual base::Status RegisterSqlPackage(SqlPackage) = 0; 73 74 // ================================================================= 75 // | Trace summary related functionality starts here | 76 // ================================================================= 77 78 // Creates a summary of the trace as defined by the `computation` and `specs` 79 // parameters. 80 // 81 // `computation` is a `TraceSummaryComputationSpec` struct which decides how 82 // the trace should be summarized. It does not contain any business logic 83 // itself, instead just referencing the contents of `specs`. 84 // 85 // Each entry in `specs` should point to an instance of the `TraceSummarySpec` 86 // proto with `spec_format` defining the file format of each specs. This 87 // function accepts a vector to make it easy to compute metrics in the common 88 // case of having many different `TraceSummarySpec` files, each with a subset 89 // of the summary to be computed (e.g. metrics shareded across multiple 90 // files). 91 // 92 // The result of computing the summary will be returned in `output` (with a 93 // schema specified by the `TraceSummary` proto) with `output_spec` defining 94 // the format that the data should be returned in. 95 // 96 // Conceptual note: this function is designed with a split in `computation` 97 // vs `specs` is to allow for `specs` to be stored as self-contained set of 98 // protos on the filesystem or in a git repo which are then referenced by the 99 // embedder of trace processor to actually decide which parts of the spec 100 // matter for a particular trace. This allows decoupling what should be 101 // computed from how that computation should happen. 102 // 103 // Implementation note: after this function returns, any or all of the 104 // referenced PerfettoSQL modules in any computed metrics will remain 105 // included. This behaviour is *not* considered part of the API and should not 106 // be relied on. It is likely this will change in the future. 107 virtual base::Status Summarize( 108 const TraceSummaryComputationSpec& computation, 109 const std::vector<TraceSummarySpecBytes>& specs, 110 std::vector<uint8_t>* output, 111 const TraceSummaryOutputSpec& output_spec) = 0; 112 113 // ================================================================= 114 // | Metatracing related functionality starts here | 115 // ================================================================= 116 117 // Enables "meta-tracing" of trace processor. 118 // Metatracing involves tracing trace processor itself to root-cause 119 // performace issues in trace processor. See |DisableAndReadMetatrace| for 120 // more information on the format of the metatrace. 121 using MetatraceConfig = metatrace::MetatraceConfig; 122 using MetatraceCategories = metatrace::MetatraceCategories; 123 virtual void EnableMetatrace(MetatraceConfig config = {}) = 0; 124 125 // Disables "meta-tracing" of trace processor and writes the trace as a 126 // sequence of |TracePackets| into |trace_proto| returning the status of this 127 // read. 128 virtual base::Status DisableAndReadMetatrace( 129 std::vector<uint8_t>* trace_proto) = 0; 130 131 // ================================================================= 132 // | Advanced functionality starts here | 133 // ================================================================= 134 135 // Sets/returns the name of the currently loaded trace or an empty string if 136 // no trace is fully loaded yet. This has no effect on the Trace Processor 137 // functionality and is used for UI purposes only. 138 // The returned name is NOT a path and will contain extra text w.r.t. the 139 // argument originally passed to SetCurrentTraceName(), e.g., "file (42 MB)". 140 virtual std::string GetCurrentTraceName() = 0; 141 virtual void SetCurrentTraceName(const std::string&) = 0; 142 143 // Registers the contents of a file. 144 // This method can be used to pass out of band data to the trace processor 145 // which can be used by importers to do some advanced processing. For example 146 // if you pass binaries these are used to decode ETM traces. 147 // Registering the same file twice will return an error. 148 virtual base::Status RegisterFileContent(const std::string& path, 149 TraceBlobView content) = 0; 150 151 // Interrupts the current query. Typically used by Ctrl-C handler. 152 virtual void InterruptQuery() = 0; 153 154 // Restores Trace Processor to its pristine state. It preserves the built-in 155 // tables/views/functions created by the ingestion process. Returns the number 156 // of objects created in runtime that has been deleted. 157 // NOTE: No Iterators can active when called. 158 virtual size_t RestoreInitialTables() = 0; 159 160 // Deprecated. Use |RegisterSqlPackage()| instead, which is identical in 161 // functionality to |RegisterSqlModule()| and the only difference is in 162 // the argument, which is directly translatable to |SqlPackage|. 163 virtual base::Status RegisterSqlModule(SqlModule) = 0; 164 165 // ================================================================= 166 // | Trace-based metrics (v1) related functionality starts here | 167 // ================================================================= 168 // 169 // WARNING: The metrics v1 system is "soft" deprecated: no new metrics are 170 // allowed but we still fully support any existing metrics written using this 171 // system. 172 // 173 // If possible, prefer using the metrics v2 methods above for any new 174 // usecases. 175 176 // Registers a metric at the given path which will run the specified SQL. 177 virtual base::Status RegisterMetric(const std::string& path, 178 const std::string& sql) = 0; 179 180 // Reads the FileDescriptorSet proto message given by |data| and |size| and 181 // adds any extensions to the metrics proto to allow them to be available as 182 // proto builder functions when computing metrics. 183 virtual base::Status ExtendMetricsProto(const uint8_t* data, size_t size) = 0; 184 185 // Behaves exactly as ExtendMetricsProto, except any FileDescriptor with 186 // filename matching a prefix in |skip_prefixes| is skipped. 187 virtual base::Status ExtendMetricsProto( 188 const uint8_t* data, 189 size_t size, 190 const std::vector<std::string>& skip_prefixes) = 0; 191 192 // Computes the given metrics on the loded portion of the trace. If 193 // successful, the output argument |metrics_proto| will be filled with the 194 // proto-encoded bytes for the message TraceMetrics in 195 // perfetto/metrics/metrics.proto. 196 virtual base::Status ComputeMetric( 197 const std::vector<std::string>& metric_names, 198 std::vector<uint8_t>* metrics_proto) = 0; 199 200 enum MetricResultFormat { 201 kProtoText = 0, 202 kJson = 1, 203 }; 204 205 // Computes metrics as the ComputeMetric function above, but instead of 206 // producing proto encoded bytes, the output argument |metrics_string| is 207 // filled with the metric formatted in the requested |format|. 208 virtual base::Status ComputeMetricText( 209 const std::vector<std::string>& metric_names, 210 MetricResultFormat format, 211 std::string* metrics_string) = 0; 212 213 // Gets all the currently loaded proto descriptors used in metric computation. 214 // This includes all compiled-in binary descriptors, and all proto descriptors 215 // loaded by trace processor shell at runtime. The message is encoded as 216 // DescriptorSet, defined in perfetto/trace_processor/trace_processor.proto. 217 virtual std::vector<uint8_t> GetMetricDescriptors() = 0; 218 219 // ================================================================= 220 // | Experimental | 221 // ================================================================= 222 223 virtual base::Status AnalyzeStructuredQueries( 224 const std::vector<StructuredQueryBytes>& queries, 225 std::vector<AnalyzedStructuredQuery>* output) = 0; 226 }; 227 228 } // namespace perfetto::trace_processor 229 230 #endif // INCLUDE_PERFETTO_TRACE_PROCESSOR_TRACE_PROCESSOR_H_ 231