!1437 SR000GIILK:【资料】hitrace部件的js api需求

Merge pull request !1437 from honghecun/master

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)

zh-cn/application-dev/reference/apis/js-apis-bytrace.md

 # 性能打点
 
 > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**
-> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
+> - 从API Version 8开始，该接口不再维护，推荐使用新接口[hiTraceMeter](js-apis-hitracemeter.md)。具体新接口在接口描述中说明。
+> - 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
 
 
 ## 导入模块

zh-cn/application-dev/reference/apis/js-apis-hitracechain.md

+# 分布式跟踪
+
+> ![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);
+  ```

zh-cn/application-dev/reference/apis/js-apis-hitracemeter.md

+# 性能打点
+
+> ![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);
+  //业务流程......
+  ```