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/status.h"
28 #include "perfetto/trace_processor/trace_processor_storage.h"
29 
30 namespace perfetto {
31 namespace trace_processor {
32 
33 // Extends TraceProcessorStorage to support execution of SQL queries on loaded
34 // traces. See TraceProcessorStorage for parsing of trace files.
35 class PERFETTO_EXPORT TraceProcessor : public TraceProcessorStorage {
36  public:
37   // For legacy API clients. Iterator used to be a nested class here. Many API
38   // clients depends on it at this point.
39   using Iterator = ::perfetto::trace_processor::Iterator;
40 
41   // Creates a new instance of TraceProcessor.
42   static std::unique_ptr<TraceProcessor> CreateInstance(const Config&);
43 
44   ~TraceProcessor() override;
45 
46   // Executes a SQLite query on the loaded portion of the trace. The returned
47   // iterator can be used to load rows from the result.
48   virtual Iterator ExecuteQuery(const std::string& sql,
49                                 int64_t time_queued = 0) = 0;
50 
51   // Registers a metric at the given path which will run the specified SQL.
52   virtual util::Status RegisterMetric(const std::string& path,
53                                       const std::string& sql) = 0;
54 
55   // Reads the FileDescriptorSet proto message given by |data| and |size| and
56   // adds any extensions to the metrics proto to allow them to be available as
57   // proto builder functions when computing metrics.
58   virtual util::Status ExtendMetricsProto(const uint8_t* data, size_t size) = 0;
59 
60   // Computes the given metrics on the loded portion of the trace. If
61   // successful, the output argument |metrics_proto| will be filled with the
62   // proto-encoded bytes for the message TraceMetrics in
63   // perfetto/metrics/metrics.proto.
64   virtual util::Status ComputeMetric(
65       const std::vector<std::string>& metric_names,
66       std::vector<uint8_t>* metrics_proto) = 0;
67 
68   enum MetricResultFormat {
69     kProtoText = 0,
70     kJson = 1,
71   };
72 
73   // Computes metrics as the ComputeMetric function above, but instead of
74   // producing proto encoded bytes, the output argument |metrics_string| is
75   // filled with the metric formatted in the requested |format|.
76   virtual util::Status ComputeMetricText(
77       const std::vector<std::string>& metric_names,
78       MetricResultFormat format,
79       std::string* metrics_string) = 0;
80 
81   // Interrupts the current query. Typically used by Ctrl-C handler.
82   virtual void InterruptQuery() = 0;
83 
84   // Deletes all tables and views that have been created (by the UI or user)
85   // after the trace was loaded. It preserves the built-in tables/view created
86   // by the ingestion process. Returns the number of table/views deleted.
87   virtual size_t RestoreInitialTables() = 0;
88 
89   // Sets/returns the name of the currently loaded trace or an empty string if
90   // no trace is fully loaded yet. This has no effect on the Trace Processor
91   // functionality and is used for UI purposes only.
92   // The returned name is NOT a path and will contain extra text w.r.t. the
93   // argument originally passed to SetCurrentTraceName(), e.g., "file (42 MB)".
94   virtual std::string GetCurrentTraceName() = 0;
95   virtual void SetCurrentTraceName(const std::string&) = 0;
96 
97   // Enables "meta-tracing" of trace processor.
98   // Metatracing involves tracing trace processor itself to root-cause
99   // performace issues in trace processor. See |DisableAndReadMetatrace| for
100   // more information on the format of the metatrace.
101   virtual void EnableMetatrace() = 0;
102 
103   // Disables "meta-tracing" of trace processor and writes the trace as a
104   // sequence of |TracePackets| into |trace_proto| returning the status of this
105   // read.
106   virtual util::Status DisableAndReadMetatrace(
107       std::vector<uint8_t>* trace_proto) = 0;
108 
109   // Gets all the currently loaded proto descriptors used in metric computation.
110   // This includes all compiled-in binary descriptors, and all proto descriptors
111   // loaded by trace processor shell at runtime. The message is encoded as
112   // DescriptorSet, defined in perfetto/trace_processor/trace_processor.proto.
113   virtual std::vector<uint8_t> GetMetricDescriptors() = 0;
114 };
115 
116 // When set, logs SQLite actions on the console.
117 void PERFETTO_EXPORT EnableSQLiteVtableDebugging();
118 
119 }  // namespace trace_processor
120 }  // namespace perfetto
121 
122 #endif  // INCLUDE_PERFETTO_TRACE_PROCESSOR_TRACE_PROCESSOR_H_
123