diff --git a/zh-cn/application-dev/reference/apis/js-apis-hiperf.md b/zh-cn/application-dev/reference/apis/js-apis-hiperf.md new file mode 100644 index 0000000000000000000000000000000000000000..7a6577e7d2a7dbd3c18109eb86817644594d92a0 --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-hiperf.md @@ -0,0 +1,507 @@ +# hiperf js api 说明 +提供控制hiperf采样的功能。用于集成到js应用。 + +# 导入模块 +``` +import hiperf from '@ohos.hiperf' +``` + +# 系统能力 + +SystemCapability.Developtools.Hiperf + +# 方法 + +## startWithOption +``` +startWithOption(): boolean +``` +使用设置的参数启动采样 +### 返回值 +| 类型 | 说明 | +| ---------------------- | ---------------------------- | +| boolean | 是否启动成功 | + +## resetOption +``` +resetOption(): boolean +``` +复位采样参数 +### 返回值 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 是否复位成功 | + +## start +``` +start(): boolean +``` +使用默认采样参数启动采样 +### 返回值 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 是否启动成功 | + +## pause +``` +pause(): boolean +``` +暂停采样 +### 返回值 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 是否暂停成功 | + +## resume +``` +resume(): boolean +``` +恢复采样 +### 返回值 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 是否恢复成功 | + +## stop +``` +stop(): boolean +``` +停止采样 +### 返回值 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 是否停止成功 | + +## isReady +``` +isReady(): boolean +``` +是否可以开始采样 +### 返回值 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 是否可以开始采样 | + +## setup +``` +setup(outputDir: string): boolean +``` +设置输出采样数据的路径 +### 参数 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| string | 输出采样数据的路径 | +### 返回值 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 是否设置成功 | + +## getOutputDir +``` +getOutputDir(): string +``` +获取当前设置的采样数据输出路径 +### 返回值 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| string | 当前设置的采样数据输出路径 | + +## getCommandPath +``` +getCommandPath(): string +``` +获取当前的hiperf工具路径 +### 返回值 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| string | 当前的hiperf工具路径 | + +## getOutputPerfDataPath +``` +getOutputPerfDataPath(): string +``` +获取当前的采样数据的完整路径 +### 返回值 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| string | 当前的采样数据的完整路径 | + +## setDebugMode +``` +setDebugMode(): boolean +``` +设置调试模式 +### 返回值 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 设置是否成功 | + +## setOutputFilename +``` +setOutputFilename(outputFilename: string): boolean +``` +设置输出的采样数据文件名称 +### 参数 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| string | 输出的采样数据文件名称 | +### 返回值 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 设置是否成功 | + +## getOutputFileName +``` +getOutputFileName(): string +``` +获取输出的采样数据文件名 +### 返回值 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| string | 输出的采样数据文件名 | + +## setTargetSystemWide +``` +setTargetSystemWide(enble: boolean): boolean +``` +设置全局采样参数 +### 参数 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 是否全局采样，默认为否 | +### 返回值 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 设置是否成功 | + +## setCompressData +``` +setCompressData(enble: boolean): boolean +``` +设置启用采样压缩功能 +### 参数 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 是否压缩，默认为否 | +### 返回值 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 设置是否成功 | + +## setSelectCpus +``` +setSelectCpus(cpus: number[]): boolean +``` +设置采样的目标CPU ID +### 参数 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| number[] | 目标CPU ID | +### 返回值 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 设置是否成功 | + +## setTimeStopSec +``` +setTimeStopSec(timeStopSec: number): boolean +``` +设置采样持续的秒数 +### 参数 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| number | 持续的秒数 | +### 返回值 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 设置是否成功 | + +## setFrequency +``` +setFrequency(frequency: number): boolean +``` +设置采样频率 +### 参数 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| number | 采样频率 | +### 返回值 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 设置是否成功 | + +## setPeriod +``` +setPeriod(period: number): boolean +``` +设置采样周期 +### 参数 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| number | 采样周期 | +### 返回值 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 设置是否成功 | + +## setSelectEvents +``` +setSelectEvents(selectEvents: string[]): boolean +``` +设置采样的事件 +### 参数 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| string[] | 采样的事件 | +### 返回值 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 设置是否成功 | + +## setSelectGroups +``` +setSelectGroups(selectGroups: string[]): boolean +``` +设置采样的事件组 +### 参数 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| string[] | 采样的事件组 | +### 返回值 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 设置是否成功 | + +## setNoInherit +``` +setNoInherit(enable: boolean): boolean +``` +设置是否要追踪子线程/子进程 +### 参数 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 是否要追踪子线程/子进程，默认为否 | +### 返回值 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 设置是否成功 | + +## setSelectPids +``` +setSelectPids(selectPids: number[]): boolean +``` +设置需要采样的目标PID +### 参数 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| number[] | 目标PID | +### 返回值 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 设置是否成功 | + +## setSelectTids +``` +setSelectTids(selectPids: number[]): boolean +``` +设置需要采样的目标TID +### 参数 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| number[] | 目标TID | +### 返回值 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 设置是否成功 | + +## setExcludePerf +``` +setExcludePerf(excludePerf: boolean): boolean +``` +设置是否排除hiperf自己的采样数据，需与setTargetSystemWide配合使用 +### 参数 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 是否排除hiperf自己 | +### 返回值 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 设置是否成功 | + +## setCpuPercent +``` +setCpuPercent(cpuPercent: number): boolean +``` +设置采样时CPU的最大占用比（内核） +### 参数 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| number | CPU最大占用比 | +### 返回值 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 设置是否成功 | + +## setOffCPU +``` +setOffCPU(offCPU: boolean): boolean +``` +设置是否追踪CPU调离事件 +### 参数 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 是否追踪，默认为否 | +### 返回值 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 设置是否成功 | + +## setCallGraph +``` +setCallGraph(sampleTypes: string): boolean +``` +设置采样的回栈方式，可以选择fp或者dwarf +### 参数 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| string | 回栈方式，默认不回栈 | +### 返回值 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 设置是否成功 | + +## setDelayUnwind +``` +setDelayUnwind(delayUnwind: boolean): boolean +``` +设置是否延迟回栈，dwarf下有效，会降低采样的CPU占有率，但是会增加需要的文件空间大小 +### 参数 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 是否延迟回栈，默认为否 | +### 返回值 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 设置是否成功 | + +## setDisableUnwind +``` +setDisableUnwind(disableUnwind: boolean): boolean +``` +设置是否关闭回栈，dwarf下有效，主要用于离线回栈，会占用大量的磁盘空间 +### 参数 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 是否关闭回栈，默认为否 | +### 返回值 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 设置是否成功 | + +## setDisableCallstackMerge +``` +setDisableCallstackMerge(disableCallstackMerge: boolean): boolean +``` +设置是否禁止堆栈扩展，在用户栈数量不足的情况下可能会降低栈的深度 +### 参数 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 是否禁止堆栈扩展，默认为否 | +### 返回值 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 设置是否成功 | + +## setSymbolDir +``` +setSymbolDir(symbolDir_: string): boolean +``` +设置回栈用的符号表路径 +### 参数 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| string | 符号表路径 | +### 返回值 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 设置是否成功 | + +## setDataLimit +``` +setDataLimit(limit: string): boolean +``` +设置采样数据的最大大小，用KMG为单位，例如： 100M +### 参数 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| string | 采样数据的最大大小 | +### 返回值 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 设置是否成功 | + +## setAppPackage +``` +setAppPackage(appPackage: string): boolean +``` +设置采样的目标app名称，如果app未启动，会等待app启动，等待超时为10秒 +### 参数 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| string | 目标app名称 | +### 返回值 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 设置是否成功 | + +## setClockId +``` +setClockId(clockId: string): boolean +``` +设置采样时钟ID，用于采样记录里的时间戳。时钟ID包括：monotonic、monotonic_raw、boottime、realtime、clock_tai +### 参数 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| string | 采样时钟ID | +### 返回值 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 设置是否成功 | + +## setVecBranchSampleTypes +``` +setVecBranchSampleTypes(vecBranchSampleTypes: string[]): boolean +``` +设置分支预测的采样。分支类型包括：any、any_call、any_ret、ind_call、call、u、k，其中u表示用户层，k表示内核层。例如：any_call,any_ret,u +### 参数 +| 类型 | 说明 | +| --------------------- | ---------------------------- |u +| string[] | 分支类型 | +### 返回值 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 设置是否成功 | + +## setMmapPages +``` +setMmapPages(mmapPages: number): boolean +``` +设置内核采样的缓冲区mmap页数 +### 参数 +| 类型 | 说明 | +| --------------------- | ---------------------------- |u +| number | 缓冲区mmap页数 | +### 返回值 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| boolean | 设置是否成功 | + +## getOptionVecString +``` +getOptionVecString(): string[] +``` +获取设置的采样参数 +### 返回值 +| 类型 | 说明 | +| --------------------- | ---------------------------- | +| string | 采样参数列表 |