Debian Codegraph @

simpleperf/app_api/cpp/simpleperf.h

raw
1 /*
2 * Copyright (C) 2019 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 #pragma once
18 #include <sys/types.h>
19 #include <unistd.h>
20
21 #include <string>
22 #include <vector>
23
24 // A C++ API used to control simpleperf recording.
25 namespace simpleperf {
26
27 /**
28 * RecordOptions sets record options used by ProfileSession. The options are
29 * converted to a string list in toRecordArgs(), which is then passed to
30 * `simpleperf record` cmd. Run `simpleperf record -h` or
31 * `run_simpleperf_on_device.py record -h` for help messages.
32 *
33 * Example:
34 * RecordOptions options;
35 * options.setDuration(3).recordDwarfCallGraph().setOutputFilename("perf.data");
36 * ProfileSession session;
37 * session.startRecording(options);
38 */
39 class RecordOptionsImpl;
40 class RecordOptions {
41 public:
42 RecordOptions();
43 ~RecordOptions();
44 /**
45 * Set output filename. Default is perf-<month>-<day>-<hour>-<minute>-<second>.data.
46 * The file will be generated under simpleperf_data/.
47 */
48 RecordOptions& SetOutputFilename(const std::string& filename);
49
50 /**
51 * Set event to record. Default is cpu-cycles. See `simpleperf list` for all available events.
52 */
53 RecordOptions& SetEvent(const std::string& event);
54
55 /**
56 * Set how many samples to generate each second running. Default is 4000.
57 */
58 RecordOptions& SetSampleFrequency(size_t freq);
59
60 /**
61 * Set record duration. The record stops after `durationInSecond` seconds. By default,
62 * record stops only when stopRecording() is called.
63 */
64 RecordOptions& SetDuration(double duration_in_second);
65
66 /**
67 * Record some threads in the app process. By default, record all threads in the process.
68 */
69 RecordOptions& SetSampleThreads(const std::vector<pid_t>& threads);
70
71 /**
72 * Record dwarf based call graph. It is needed to get Java callstacks.
73 */
74 RecordOptions& RecordDwarfCallGraph();
75
76 /**
77 * Record frame pointer based call graph. It is suitable to get C++ callstacks on 64bit devices.
78 */
79 RecordOptions& RecordFramePointerCallGraph();
80
81 /**
82 * Trace context switch info to show where threads spend time off cpu.
83 */
84 RecordOptions& TraceOffCpu();
85
86 /**
87 * Translate record options into arguments for `simpleperf record` cmd.
88 */
89 std::vector<std::string> ToRecordArgs() const;
90
91 private:
92 RecordOptionsImpl* impl_;
93 };
94
95 /**
96 * ProfileSession uses `simpleperf record` cmd to generate a recording file.
97 * It allows users to start recording with some options, pause/resume recording
98 * to only profile interested code, and stop recording.
99 *
100 * Example:
101 * RecordOptions options;
102 * options.setDwarfCallGraph();
103 * ProfileSession session;
104 * session.StartRecording(options);
105 * sleep(1);
106 * session.PauseRecording();
107 * sleep(1);
108 * session.ResumeRecording();
109 * sleep(1);
110 * session.StopRecording();
111 *
112 * It aborts when error happens. To read error messages of simpleperf record
113 * process, filter logcat with `simpleperf`.
114 */
115 class ProfileSessionImpl;
116 class ProfileSession {
117 public:
118 /**
119 * @param appDataDir the same as android.content.Context.getDataDir().
120 * ProfileSession stores profiling data in appDataDir/simpleperf_data/.
121 */
122 ProfileSession(const std::string& app_data_dir);
123
124 /**
125 * ProfileSession assumes appDataDir as /data/data/app_package_name.
126 */
127 ProfileSession();
128 ~ProfileSession();
129
130 /**
131 * Start recording.
132 * @param options RecordOptions
133 */
134 void StartRecording(const RecordOptions& options);
135
136 /**
137 * Start recording.
138 * @param args arguments for `simpleperf record` cmd.
139 */
140 void StartRecording(const std::vector<std::string>& record_args);
141
142 /**
143 * Pause recording. No samples are generated in paused state.
144 */
145 void PauseRecording();
146
147 /**
148 * Resume a paused session.
149 */
150 void ResumeRecording();
151
152 /**
153 * Stop recording and generate a recording file under appDataDir/simpleperf_data/.
154 */
155 void StopRecording();
156 private:
157 ProfileSessionImpl* impl_;
158 };
159
160 } // namespace simpleperf