diff --git a/zh-cn/application-dev/reference/apis/Readme-CN.md b/zh-cn/application-dev/reference/apis/Readme-CN.md index 8b2cdb6da5264f713f1fa693cc22e12caf47e867..16286defa11112818f3dac92860a7e2004849493 100644 --- a/zh-cn/application-dev/reference/apis/Readme-CN.md +++ b/zh-cn/application-dev/reference/apis/Readme-CN.md @@ -69,8 +69,9 @@ - [设置系统时间](js-apis-system-time.md) - [动画](js-apis-basic-features-animator.md) - [应用打点](js-apis-hiappevent.md) - - [性能打点](js-apis-bytrace.md) + - [性能打点](js-apis-hitracemeter.md) - [故障日志获取](js-apis-faultLogger.md) + - [分布式跟踪](js-apis-hitracechain.md) - [日志打印](js-apis-hilog.md) - 语言基础类库 - [获取进程相关的信息](js-apis-process.md) diff --git a/zh-cn/application-dev/reference/apis/js-apis-bytrace.md b/zh-cn/application-dev/reference/apis/js-apis-bytrace.md index 0e8a5058d6676b86af07a94468772622750e6ae6..029e6952cb144295dd103bfc1ca51ad23bbd49af 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-bytrace.md +++ b/zh-cn/application-dev/reference/apis/js-apis-bytrace.md @@ -1,7 +1,8 @@ # 性能打点 > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明:** -> 本模块首批接口从API version 7开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。 +> - 从API Version 8开始,该接口不再维护,推荐使用新接口[hiTraceMeter](js-apis-hitracemeter.md)。具体新接口在接口描述中说明。 +> - 本模块首批接口从API version 7开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。 ## 导入模块 diff --git a/zh-cn/application-dev/reference/apis/js-apis-hitracechain.md b/zh-cn/application-dev/reference/apis/js-apis-hitracechain.md new file mode 100644 index 0000000000000000000000000000000000000000..a499e0b10a226435783a4a9533a737597609cb5f --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-hitracechain.md @@ -0,0 +1,253 @@ +# 分布式跟踪 + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明:** +> 本模块首批接口从API version 8开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。 + +## 导入模块 + +``` +import hiTraceChain from '@ohos.hiTraceChain'; +``` + +## 系统能力 + +SystemCapability.HiviewDFX.HiTrace + +## HiTraceFlag + +跟踪标志组合类型枚举。 + +| 名称 | 默认值 | 说明 | +| -------- | -------- | -------- | +| DEFAULT | 0 | 缺省标志 | +| INCLUDE_ASYNC | 1 | 异步调用标志 | +| DONOT_CREATE_SPAN | 1 << 1 | 无分支标志 | +| TP_INFO | 1 << 2 | 埋点标志 | +| NO_BE_INFO | 1 << 3 | 无起始结束标志 | +| DISABLE_LOG | 1 << 4 | 日志关联标志 | +| FAILURE_TRIGGER | 1 << 5 | 故障触发标志 | +| D2D_TP_INFO | 1 << 6 | 设备间埋点标志 | + +## HiTraceTracepointType + +跟踪埋点类型枚举。 + +| 名称 | 默认值 | 说明 | +| -------- | -------- | -------- | +| CS | 0 | 客户端发送类型 | +| CR | 1 | 客户端接收类型 | +| SS | 2 | 服务端发送类型 | +| SR | 3 | 服务端接收类型 | +| GENERAL | 4 | 常规类型 | + +## HiTraceCommunicationMode + +跟踪通信类型枚举。 + +| 名称 | 默认值 | 说明 | +| -------- | -------- | -------- | +| DEFAULT | 0 | 缺省方式 | +| THREAD | 1 | 线程间通信类型 | +| PROCESS | 2 | 进程间通信类型 | +| DEVICE | 3 | 设备间通信类型 | + +## HiTraceId + +此接口为HiTraceId对象接口。 + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| chainId | bigint | 是 | 跟踪链标识。 | +| spandId | number | 否 | 分支标识。 | +| parentSpanId | number | 否 | 父分支标识。 | +| flags | number | 否 | 跟踪标志组合。 | + +## hiTraceChain.begin + +begin(name: string, flags: number = HiTraceFlag.DEFAULT): HiTraceId + +开始跟踪,同步接口。 + +- 参数: + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | name | string | 是 | 跟踪业务名。 | + | flags | number | 是 | [跟踪标志组合](#hitraceflag)。 | +- 返回值: + | 类型 | 说明 | + | -------- | -------- | + | [HiTraceId](#hitraceid) | HiTraceId实例。 | + +- 示例: + ``` + let asyncTraceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.INCLUDE_ASYNC | hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN); + ``` + +## hiTraceChain.end + +end(id: HiTraceId): void + +结束跟踪,同步接口。 + +- 参数: + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | id | [HiTraceId](#hitraceid) | 是 | HiTraceId实例。 | + +- 示例: + ``` + let asyncTraceId = hiTraceChain.begin("business"); + // 若干业务逻辑完成后,结束跟踪。 + hiTraceChain.end(asyncTraceId); + ``` + +## hiTraceChain.getId + +getId(): HiTraceId + +获取跟踪标识,同步接口。 + +- 返回值: + | 类型 | 说明 | + | -------- | -------- | + | [HiTraceId](#hitraceid) | HiTraceId实例。 | + +- 示例: + ``` + let traceId = hiTraceChain.begin("business"); + // 若干业务逻辑完成后,获取当前HiTraceId。 + let curTraceId = hiTraceChain.getId(); + ``` + +## hiTraceChain.setId + +setId(id: HiTraceId): void + +设置跟踪标识,同步接口。 + +- 参数: + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | id | [HiTraceId](#hitraceid) | 是 | HiTraceId实例。 | + +- 示例: + ``` + let traceId = hiTraceChain.begin("business"); + // 若干业务逻辑完成后,设置当前HiTraceId。 + hiTraceChain.setId(asyncTraceId); + ``` + +## hiTraceChain.clearId + +clearId(): void + +清除跟踪标识,同步接口。 + +- 示例: + ``` + let traceId = hiTraceChain.begin("business"); + // 若干业务逻辑完成后,清除当前HiTraceId。 + hiTraceChain.clearId(); + ``` + +## hiTraceChain.createSpan + +createSpan(): HiTraceId + +创建跟踪分支,同步接口。 + +- 返回值: + | 类型 | 说明 | + | -------- | -------- | + | [HiTraceId](#hitraceid) | HiTraceId实例。 | + +- 示例: + ``` + let traceId = hiTraceChain.begin("business"); + // 若干业务逻辑完成后,创建跟踪分支。 + let spanTraceId = hiTraceChain.createSpan(); + ``` + +## hiTraceChain.tracepoint + +tracepoint(mode: HiTraceCommunicationMode, type: HiTraceTracepointType, id: HiTraceId, msg?: string): void + +信息埋点,同步接口。 + +- 参数: + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | mode | [HiTraceCommunicationMode](#hitracecommunicationmode) | 是 | 信息埋点需要指定的跟踪通信模式。 | + | type | [HiTraceTracepointType](#hitracetracepointtype)| 是 | 信息埋点需要指定的跟踪埋点类型。 | + | id | [HiTraceId](#hitraceid) | 是 | 实施信息埋点操作的HiTraceId实例。 | + | msg | string | 否 | 信息埋点操作传入的trace说明信息。 | + +- 示例: + ``` + let asyncTraceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.INCLUDE_ASYNC | hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN); + // 若干业务逻辑完成后,触发信息埋点操作。 + hiTraceChain.tracepoint(hiTraceChain.HiTraceCommunicationMode.THREAD, hiTraceChain.HiTraceTracepointType.SS, asyncTraceId, "Just a example"); + ``` + +## hiTraceChain.isValid + +isValid(id: HiTraceId): boolean + +判断HiTraceId对象是否有效,同步接口。 + +- 参数: + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | id | [HiTraceId](#hitraceid) | 是 | 需要判断是否有效的HiTraceId实例。 | +- 返回值: + | 类型 | 说明 | + | -------- | -------- | + | boolean | 返回true表示HiTraceId有效,否则无效。 | + +- 示例: + ``` + let traceId = hiTraceChain.begin("business"); + let traceIdIsvalid = hiTraceChain.isValid(traceId); + ``` + +## hiTraceChain.isFlagEnabled + +isFlagEnabled(id: HiTraceId, flag: HiTraceFlag): boolean + +判断HiTraceId对象中指定的跟踪标志是否已置位,同步接口。 + +- 参数: + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | id | [HiTraceId](#hitraceid) | 是 | 需要判断指定跟踪标志是否置位的HiTraceId实例。 | + | flag | [HiTraceFlag](#hitraceflag) | 是 | 指定的跟踪标志。 | +- 返回值: + | 类型 | 说明 | + | -------- | -------- | + | boolean | 返回true标识HiTraceId已置位指定的flag,否则没有置位。 | +- 示例: + ``` + let asyncTraceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.INCLUDE_ASYNC); + // enabledDoNotCreateSpanFlag为true + let enabledDoNotCreateSpanFlag = hiTraceChain.isFlagEnabled(asyncTraceId, hiTraceChain.HiTraceFlag.INCLUDE_ASYNC); + ``` + +## hiTraceChain.enableFlag + +enableFlag(id: HiTraceId, flag: HiTraceFlag): void + +置位HiTraceId对象中指定的跟踪标志,同步接口。 + +- 参数: + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | id | [HiTraceId](#hitraceid) | 是 | 需要置位指定跟踪标志的HiTraceId实例。 | + | flag | [HiTraceFlag](#hitraceflag) | 是 | 指定的跟踪标志。 | + +- 示例: + ``` + let asyncTraceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.INCLUDE_ASYNC); + hiTraceChain.enable(asyncTraceId, hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN); + // enabledDoNotCreateSpanFlag为true + let enabledDoNotCreateSpanFlag = hiTraceChain.isFlagEnabled(asyncTraceId, hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN); + ``` diff --git a/zh-cn/application-dev/reference/apis/js-apis-hitracemeter.md b/zh-cn/application-dev/reference/apis/js-apis-hitracemeter.md new file mode 100644 index 0000000000000000000000000000000000000000..712409d46d32e3e337b8abad427ead91aa4e2db4 --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-hitracemeter.md @@ -0,0 +1,107 @@ +# 性能打点 + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明:** +> 本模块首批接口从API version 8开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。 + + +## 导入模块 + +``` +import hiTraceMeter from '@ohos.hiTraceMeter'; +``` + + +## 系统能力 + +SystemCapability.HiviewDFX.HiTrace + + +## hiTraceMeter.startTrace + +startTrace(name: string, taskId: number, expectedTime?: number): void + +标记一个预追踪耗时任务的开始,expectedTime是可选参数,标识该任务的期望耗时。 + + +- 参数: + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | name | string | 是 | 要追踪的任务名称 | + | taskId | number | 是 | 任务id | + | expectedTime | number | 否 | 期望的耗时时间,单位:ms | + + > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明:** + > 如果有多个相同name的任务需要追踪或者对同一个任务要追踪多次,并且这些会同时被执行,则每次调用startTrace的taskId必须不一致。如果具有相同name的任务是串行执行的,则taskId可以相同。在下面hiTraceMeter.finishTrace的示例中会举例说明。 + +- 示例: + ``` + hiTraceMeter.startTrace("myTestFunc", 1); + hiTraceMeter.startTrace("myTestFunc", 1, 5); //从startTrace到finishTrace流程的耗时期望为5ms + ``` + + +## hiTraceMeter.finishTrace + +finishTrace(name: string, taskId: number): void + +标记一个预追踪耗时任务的结束。 + + +- 参数: + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | name | string | 是 | 要追踪的任务名称 | + | taskId | number | 是 | 任务id | + + > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明:** + > finishTrace的name和taskId必须与流程开始的startTrace对应参数值一致。 + +- 示例: + ``` + hiTraceMeter.finishTrace("myTestFunc", 1); + ``` + + ``` + //追踪并行执行的同名任务 + hiTraceMeter.startTrace("myTestFunc", 1); + //业务流程...... + hiTraceMeter.startTrace("myTestFunc", 2); //第二个追踪的任务开始,同时第一个追踪的同名任务还没结束,出现了并行执行,对应接口的taskId需要不同。 + //业务流程...... + hiTraceMeter.finishTrace("myTestFunc", 1); + //业务流程...... + hiTraceMeter.finishTrace("myTestFunc", 2); + ``` + + ``` + //追踪串行执行的同名任务 + hiTraceMeter.startTrace("myTestFunc", 1); + //业务流程...... + hiTraceMeter.finishTrace("myTestFunc", 1); //第一个追踪的任务结束 + //业务流程...... + hiTraceMeter.startTrace("myTestFunc", 1); //第二个追踪的同名任务开始,同名的待追踪任务串行执行。 + //业务流程...... + hiTraceMeter.finishTrace("myTestFunc", 1); + ``` + + +## hiTraceMeter.traceByValue + +traceByValue(name: string, value: number): void + +用来标记一个预追踪的数值变量,该变量的数值会不断变化。 + + +- 参数: + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | name | string | 是 | 要追踪的数值变量名称 | + | value | number | 是 | 变量的值 | + +- 示例: + ``` + let traceCount = 3; + hiTraceMeter.traceByValue("myTestCount", traceCount); + traceCount = 4; + hiTraceMeter.traceByValue("myTestCount", traceCount); + //业务流程...... + ```