!1623 新增HiTraceMeter和HiTraceChain开发指南

Merge pull request !1623 from honghecun/master

zh-cn/application-dev/dfx/Readme-CN.md

@@ -3,4 +3,10 @@
 - 应用事件打点
   - [应用事件打点概述](hiappevent-overview.md)
   - [应用事件打点开发指导](hiappevent-guidelines.md)
+- 性能打点跟踪
+  - [性能打点跟踪概述](hitracemeter-overview.md)
+  - [性能打点跟踪开发指导](hitracemeter-guidelines.md)
+- 分布式跟踪
+  - [分布式跟踪概述](hitracechain-overview.md)
+  - [分布式跟踪开发指导](hitracechain-guidelines.md)
 

zh-cn/application-dev/dfx/hitracechain-guidelines.md

+# 分布式跟踪开发指导
+
+## 场景介绍
+
+HiTraceChain为开发者提供业务流程调用链跟踪的维测接口，帮助开发者迅速获取指定业务流程调用链的运行日志，定位跨设备/跨进程/跨线程的故障问题。
+
+## 接口说明
+
+分布式跟踪接口由hiTraceChain模块提供，详细API请参考[分布式跟踪API参考](../reference/apis/js-apis-hitracechain.md)。
+
+**分布式跟踪接口功能介绍：**
+
+| 接口名                                                                                                              | 返回值         | 描述         |
+| ------------------------------------------------------------------------------------------------------------------- | -------------- | ------------ |
+| hiTraceChain.begin(name: string, flags: number = HiTraceFlag.DEFAULT)                                               | HiTraceId      | 开始跟踪。   |
+| hiTraceChain.tracepoint(mode: HiTraceCommunicationMode, type: HiTraceTracepointType, id: HiTraceId, msg?: string)   | void           | 信息埋点。   |
+| hiTraceChain.end(id: HiTraceId)                                                                                     | void           | 结束跟踪。   |
+
+## 开发步骤
+
+在应用启动执行页面加载后，开始分布式跟踪，完成业务之后，停止分布式跟踪。
+
+1. 新建一个JS应用工程，在“Project”窗口点击“entry > src > main > js > default > pages > index”，打开工程中的“index.js”文件，在页面执行加载后，在实际业务逻辑中调用hiTraceChain的API，进行分布式跟踪，示例代码如下：
+
+   ```
+   import hiTraceChain from '@ohos.hiTraceChain'
+
+   export default {
+       data: {
+           title: ""
+       },
+       onInit() {
+           this.title = this.$t('strings.world');
+
+           // 1、开启分布式跟踪
+           let asyncTraceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.INCLUDE_ASYNC | hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN);
+           
+           // 2、业务流程开始
+           console.log(`business start`);
+
+           // 3、埋点操作
+           hiTraceChain.tracepoint(hiTraceChain.HiTraceCommunicationMode.THREAD, hiTraceChain.HiTraceTracepointType.SS, asyncTraceId, "Just a example");
+
+           // 4、业务流程执行中
+           console.log(`business running`);
+
+           // 5、业务流程结束
+           console.log(`business end`);
+
+           // 6、停止跟踪
+           hiTraceChain.end(asyncTraceId);
+       }
+   }
+   ```
+
+2. 运行项目，点击应用界面上的运行按钮，即可通过日志信息分析实际业务。
+
+

zh-cn/application-dev/dfx/hitracechain-overview.md

+# 分布式跟踪概述
+
+hiTraceChain是基于云计算分布式跟踪调用链思想，在端侧业务流程（涉及跨线程、跨进程、跨设备）中的一种轻量级实现。
+
+## 基本概念
+
+- **chainId**
+
+  分布式跟踪标识，属于HiTraceId的一部分，用于标识当前跟踪的业务流程。
+
+## 运作机制
+
+hiTraceChain在业务控制面流程中，生成和传递唯一跟踪标识，在业务流程中输出的各类信息中（包括应用事件、系统时间、日志等）记录该跟踪标识。在调试、问题定位过程中，开发者可以通过该唯一跟踪标识将本次业务流程端到端的各类信息快速关联起来。
+
+## 约束与限制
+
+hiTraceChain API提供的相关接口全部为同步接口。
\ No newline at end of file

zh-cn/application-dev/dfx/hitracemeter-guidelines.md

+# 性能打点跟踪开发指导
+
+## 场景介绍
+
+HiTraceMeter为开发者提供系统性能打点接口。开发者通过在自己的业务逻辑中的关键代码位置调用HiTraceMeter接口提供的API接口，能够有效追踪进程轨迹、查看系统性能。
+
+## 接口说明
+ 
+性能打点跟踪接口由hiTraceMeter模块提供，详细API请参考[性能打点跟踪API参考](../reference/apis/js-apis-hitracemeter.md)。
+
+**性能打点跟踪接口功能介绍：**
+
+| 接口名                                                                       | 返回值    | 描述         |
+| ---------------------------------------------------------------------------- | --------- | ------------ |
+| hiTraceMeter.startTrace(name: string, taskId: number, expectedTime?: number) | void      | 标记一个预追踪耗时任务的开始。如果有多个相同name的任务需要追踪或者对同一个任务要追踪多次，并且任务同时被执行，则每次调用startTrace的taskId不相同。如果具有相同name的任务是串行执行的，则taskId可以相同。 |
+| hiTraceMeter.finishTrace(name: string, taskId: number)                       | void      | name和taskId必须与流程开始的hiTraceMeter.startTrace对应参数值保持一致。 |
+| hiTraceMeter.traceByValue(name: string, value: number)                       | void      | 用来标记一个预追踪的数值变量，该变量的数值会不断变化。|
+
+## 开发步骤
+
+在应用启动执行页面加载后，开始分布式跟踪，完成业务之后，停止分布式跟踪。
+
+1. 新建一个JS应用工程，在“Project”窗口点击“entry > src > main > js > default > pages > index”，打开工程中的“index.js”文件，在页面执行加载后，在自己的业务中调用hiTraceMeter的接口，进行性能打点追踪，示例代码如下：
+
+   ```js
+   import hiTraceMeter from '@ohos.hiTraceMeter'
+
+   export default {
+       data: {
+           title: ""
+       },
+       onInit() {
+           this.title = this.$t('strings.world');
+
+           //从startTrace到finishTrace流程的耗时期望为5ms
+           hiTraceMeter.startTrace("business", 1);
+           hiTraceMeter.startTrace("business", 1, 5); 
+           
+           //追踪并行执行的同名任务
+           hiTraceMeter.startTrace("business", 1);
+           //业务流程
+           console.log(`business running`);
+           hiTraceMeter.startTrace("business", 2);  //第二个追踪的任务开始，同时第一个追踪的同名任务还没结束，出现了并行执行，对应接口的taskId需要不同。
+           //业务流程
+           console.log(`business running`);
+           hiTraceMeter.finishTrace("business", 1);
+           //业务流程
+           console.log(`business running`);
+           hiTraceMeter.finishTrace("business", 2);
+
+           //追踪串行执行的同名任务
+           hiTraceMeter.startTrace("business", 1);
+           //业务流程
+           console.log(`business running`);
+           hiTraceMeter.finishTrace("business", 1);  //第一个追踪的任务结束
+           //业务流程
+           console.log(`business running`);
+           hiTraceMeter.startTrace("business", 1);   //第二个追踪的同名任务开始，同名的待追踪任务串行执行。
+           //业务流程
+           console.log(`business running`);
+
+           let traceCount = 3;
+           hiTraceMeter.traceByValue("myTestCount", traceCount);
+           traceCount = 4;
+           hiTraceMeter.traceByValue("myTestCount", traceCount);
+           hiTraceMeter.finishTrace("business", 1);
+       }
+   }
+   ```
+
+2. 运行项目，点击应用界面上的运行按钮，即可通过日志信息分析实际业务。
+
+

zh-cn/application-dev/dfx/hitracemeter-overview.md

+# 性能打点跟踪概述
+
+hiTraceMeter是开发者用于追踪进程轨迹，度量程序执行性能的一种工具，基于内核的ftrace机制，提供给用户态应用代码执行时长度量打点的能力。开发者通过使用hiTraceMeter API在程序中打点，并使用hiTraceMeter提供的命令行工具采集跟踪数据。
+
+## 基本概念
+
+- **hiTraceMeter Tag**
+
+  跟踪数据使用类别分类，称作hiTraceMeter Tag或hiTraceMeter Category，一般每个软件子系统对应一个Tag，该Tag在打点API中以类别TAg参数传入。hiTraceMeter命令行工具采集跟踪数据时，只采集给定的Tag类别选项指定的跟踪数据。
+
+## 运作机制
+
+- 应用程序通过hiTraceMeter函数接口进行打点，hiTraceMeter函数将跟踪数据通过内核sysfs文件接口输出到内核的ftrace数据缓冲区。
+- hiTraceMeter命令行工具读取内核ftrace缓冲区中的跟踪数据，将文本格式的跟踪数据保存到设备侧的文件中。
+
+## 约束与限制
+
+- 由于JS程序的异步IO特性，现在hiTraceMeter只提供了异步接口。
\ No newline at end of file