HiTraceChain开发指导

概述

HiTraceChain主要是对于跨设备/跨进程/跨线程的业务流程，通过相同的traceid在整个业务流程中传递，将流程处理过程中的调用关系、各种输出信息关联和展现出来，帮助使用者分析、定位问题和系统调优。

应用场景

HiTraceChain在产品中应用场景如下，包括：

• 端侧业务流程信息（日志、事件等）关联、上报

• 云侧对上报信息的关联展示和分析，辅助问题定位

• IDE对业务流程详细信息、耗时分布进行调试，辅助系统调优

  图1 HiTraceChain应用场景

业务使用示例

图2 业务调用流程图（跨设备、跨进程同步调用）

1. 调试时展示业务流程中的调用关系，进行关键路径分析、功能依赖分析，确定各调用点耗时、调用频率，提前发现性能瓶颈点。

   图3 业务调用流程序列图

   图4 业务调用流程性能耗时分布

2. 在日志和事件等信息中自动附加traceid信息，便于开发人员综合分析和快速实现问题定界定位。

接口说明

HiTraceChain提供C++、C接口。上层业务主要使用HiTraceChain跟踪启动、结束接口。

HiTraceChain实现在C层，主要原理是在一次业务调用流程中，利用通信传递traceid，在业务处理前将traceid设置到当前线程的TLS(Thread Local Storage)中，业务处理结束清除当前线程的TLS；这样的话，在业务处理中可以从当前线程的上下文TLS取到traceid，自动附加到日志、事件信息中。

接口形式对比

表1 C++、C的函数接口

接口功能参数

表2 跟踪标志组合类型枚举

表3 跟踪埋点类型枚举

表4 跟踪通信类型枚举

表5 C++接口说明函数参数和功能

通信调用处理

业务使用时跨设备/跨进程/跨线程的调用是通过通信机制实现的，HiTraceChain需要通信机制传递traceid。

OpenHarmony系统内置部分通信机制（如ZIDL）已经支持传递traceid。

下面描述了同步通信调用传递traceid的处理过程，异步通信调用处理类似。

对于不支持的扩展通信机制可以参照该方式实现。 图5 同步通信处理

处理流程：

1. client侧业务模块调用begin()接口启动调用链跟踪。

2. client侧业务模块发起同步调用transact，到client侧通信组件。

3. client侧通信组件：

   1. 从当前线程TLS中获取traceid。
   2. 生成子调用分支（child traceid）。
   3. 将child traceid写入同步调用通信数据（transaction data）中。
   4. 进行CS埋点（Client Send）。
   5. 将通信数据发送到server侧通信组件。

4. server侧通信组件收到通信数据：

   1. 从数据消息包中取出traceid。
   2. 将traceid设置到当前线程TLS中。
   3. 进行SR埋点（Server Receive）。
   4. 然后进行同步调用回调（onTransact）到server侧业务模块。

5. server侧业务模块进行服务处理，处理完毕发送处理结果（transact reply）到通信组件。

6. server侧通信组件：

   1. 进行SS埋点（Server Send）。
   2. 将响应数据发送到client侧通信组件。
   3. 清除当前线程TLS中的traceid信息。

7. client侧通信组件收到响应数据：

   1. 进行CR埋点（Client Receive）。
   2. 发送同步调用响应（transact reply）到client侧业务模块。

8. client侧业务模块进行同步调用响应处理。

9. client侧业务模块在流程结束时调用end()接口停止调用链跟踪。

开发实例

C++接口实例

1. 源代码开发 在类定义头文件或者类实现源文件中，包含hitracechain头文件：

   #include "hitrace/tracechain.h"
   

   在业务类实现源文件中使用（启动/结束跟踪）：

   using namespace OHOS::HiviewDFX;
   auto traceId = HiTraceChain::Begin("MyServiceFlow", HITRACE_FLAG_DEFAULT);
   ......
   HiTraceChain::End(traceId);
   

2. 编译设置，在BUILD.gn里增加子系统SDK依赖：

   external_deps = [ "hitrace:libhitracechain" ]
   

C接口实例

1. 源代码开发 在源文件中，包含hitracechain头文件：

   #include "hitrace/tracechain.h"
   

   在业务类实现源文件中使用（启动/结束跟踪）：

   HiTraceIdStruct traceId = HiTraceChainBegin("MyServiceFlow", HITRACE_FLAG_DEFAULT);
   ......
   HiTraceChainEnd(traceId);
   

2. 编译设置，在BUILD.gn里增加子系统SDK依赖：

   external_deps = [ "hitrace:libhitracechain" ]