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