开源鸿蒙 HiTrace开发指导
HiTrace开发指导
概述
HiTrace主要是对于跨设备/跨进程/跨线程的业务流程,通过相同的traceid在整个业务流程中传递,将流程处理过程中的调用关系、各种输出信息关联和展现出来,帮助使用者分析、定位问题和系统调优。
应用场景
HiTrace在产品中应用场景如下,包括:
端侧业务流程信息(日志、事件等)关联、上报
云侧对上报信息的关联展示和分析,辅助问题定位
IDE对业务流程详细信息、耗时分布进行调试,辅助系统调优
图1 HiTrace应用场景
业务使用示例
图2 业务调用流程图(跨设备、跨进程同步调用)
调试时展示业务流程中的调用关系,进行关键路径分析、功能依赖分析,确定各调用点耗时、调用频率,提前发现性能瓶颈点。
图3 业务调用流程序列图
图4 业务调用流程性能耗时分布
在日志和事件等信息中自动附加traceid信息,便于开发人员综合分析和快速实现问题定界定位。
接口说明
HiTrace提供C++、C接口。上层业务主要使用HiTrace跟踪启动、结束接口。
HiTrace实现在C层,主要原理是在一次业务调用流程中,利用通信传递traceid,在业务处理前将traceid设置到当前线程的TLS(Thread Local Storage)中,业务处理结束清除当前线程的TLS;这样的话,在业务处理中可以从当前线程的上下文TLS取到traceid,自动附加到日志、事件信息中。
接口形式对比
表1 C++、C的函数接口
| | C++ | C | | ——– | ——– | ——– | | 类 | 函数 | 函数 | | HiTrace | HiTraceId Begin(const std::string& name, int flags) | HiTraceIdStruct HiTraceBegin(const char* name, int flags) | | | void End(const HiTraceId& id) | void HiTraceEnd(const HiTraceIdStruct* pId) | | | HiTraceId GetId(); | HiTraceIdStruct HiTraceGetId() | | | void SetId(const HiTraceId& id) | void HiTraceSetId(const HiTraceIdStruct* pId) | | | void ClearId() | void HiTraceClearId() | | | HiTraceId CreateSpan() | HiTraceIdStruct HiTraceCreateSpan() | | | void Tracepoint(HiTraceTracepointType type, const HiTraceId& id, const char* fmt, …) | void HiTraceTracepoint(HiTraceTracepointType type, const HiTraceIdStruct pId, const char fmt, …) | | | void Tracepoint(HiTraceCommunicationMode mode, HiTraceTracepointType type, const HiTraceId& id, const char* fmt, …) | void HiTraceTracepointEx(HiTraceCommunicationMode mode, HiTraceTracepointType type, const HiTraceIdStruct pId, const char fmt, …) | | HiTraceId | HiTraceId(); | void HiTraceInitId(HiTraceIdStruct* pId) | | | HiTraceId(const uint8_t* pIdArray, int len) | HiTraceIdStruct HiTraceBytesToId(const uint8_t* pIdArray, int len) | | | bool IsValid() | int HiTraceIsValid(const HiTraceIdStruct* pId) | | | bool IsFlagEnabled(HiTraceFlag flag) | int HiTraceIsFlagEnabled(const HiTraceIdStruct* pId, HiTraceFlag flag) | | | void EnableFlag(HiTraceFlag flag) | void HiTraceEnableFlag(HiTraceIdStruct* pId, HiTraceFlag flag) | | | int GetFlags() | int HiTraceGetFlags(const HiTraceIdStruct* pId) | | | void SetFlags(int flags) | void HiTraceSetFlags(HiTraceIdStruct* pId, int flags) | | | uint64_t GetChainId() | uint64_t HiTraceGetChainId(const HiTraceIdStruct* pId) | | | void SetChainId(uint64_t chainId) | void HiTraceSetChainId(HiTraceIdStruct* pId, uint64_t chainId) | | | uint64_t GetSpanId() | uint64_t HiTraceGetSpanId(const HiTraceIdStruct* pId) | | | void SetSpanId(uint64_t spanId) | void HiTraceSetSpanId(HiTraceIdStruct* pId, uint64_t spanId) | | | uint64_t GetParentSpanId() | uint64_t HiTraceGetParentSpanId(const HiTraceIdStruct* pId) | | | void SetParentSpanId(uint64_t parentSpanId) | void HiTraceSetParentSpanId(HiTraceIdStruct* pId, uint64_t parentSpanId) | | | int ToBytes(uint8t* pIdArray, int len) | int HiTraceIdToBytes(const HiTraceIdStruct pId, uint8t pIdArray, int len) |
接口功能参数
表2 C++接口说明函数参数和功能
| 类 | 方法 | 描述 |
| ——– | ——– | ——– |
| HiTrace | HiTraceId Begin(const std::string& name, int flags) | 功能:启动HiTrace跟踪、生成HiTraceId对象并设置到当前线程TLS中。
输入参数:
- name:业务流程名称。
- flags:跟踪指示位,可以组合使用,具体含义为:
- HITRACE_FLAG_INCLUDE_ASYNC:同时跟踪同步调用和异步调用,缺省只跟踪同步调用。
- HITRACE_FLAG_DONOT_CREATE_SPAN:不创建子分支,缺省创建子分支。
- HITRACE_FLAG_TP_INFO:输出tracepoint信息,缺省不输出。
- HITRACE_FLAG_NO_BE_INFO:不输出起始、结束信息,缺省输出。
- HITRACE_FLAG_DONOT_ENABLE_LOG:不与日志关联输出,缺省关联。
- HITRACE_FLAG_FAULT_TRIGGER:故障触发的跟踪,缺省为正常启动的。
- HITRACE_FLAG_D2D_TP_INFO:输出设备间tracepoint信息,缺省不输出。
- HITRACE_FLAG_DEFAULT: 缺省标志。
- 输出参数:无
- 返回值:启动跟踪超过返回有效HiTraceId对象,否则返回无效对象。
注意:嵌套启动跟踪时,内层启动调用返回无效对象。 |
| | void End(const HiTraceId& id) | 功能:根据Begin返回的HiTraceId停止HiTrace跟踪;清除当前线程TLS中HiTraceId内容。
输入参数:
- id:HiTraceId对象。
输出参数:无。
返回值:无。 |
| | HiTraceId GetId(); | 功能:从当前线程TLS中获取HiTraceId对象。
输入参数:无。
输出参数:无。
返回值:当前线程上下文的HiTraceId对象。 |
| | void SetId(const HiTraceId& id) | 功能:设置HiTraceId对象内容到当前线程TLS中。
输入参数:
- id:HiTraceId对象。
输出参数:无。
返回值:无。 |
| | void ClearId() | 功能:清除当前线程TLS中的HiTraceId对象。
输入参数:无。
输出参数:无。
返回值:无。 |
| | HiTraceId CreateSpan() | 接口功能:获取当前HiTraceId对象中的分支ID。
输入参数:无。
输出参数:无。
返回值:当前分支ID。 |
| | void Tracepoint(HiTraceTracepointType type, const HiTraceId& id, const char* fmt, …) | 功能:根据埋点信息类型输出HiTrace埋点信息,包括时间戳、子分支HiTraceId对象信息。
输入参数:
- type:埋点信息类型,具体为
- HITRACE_TP_CS:Client Send,同步/异步通信客户端发送信息。
- HITRACE_TP_SR:Server Receive, 同步/异步通信服务端接收信息。
- HITRACE_TP_SS:Server Send,同步通信服务端发送响应信息。
- HITRACE_TP_CR:Client Receive,同步通信客户端接收响应信息。
- HITRACE_TP_GENERAL:普通输出信息。
- id:当前子分支id。
- fmt:格式化变参描述字符串。
- args:变参。
输出参数:无。
返回值:无。 |
| | void Tracepoint(HiTraceCommunicationMode mode, HiTraceTracepointType type, const HiTraceId& id, const char* fmt, …) | 功能:根据通信模式、埋点信息类型输出HiTrace埋点信息,包括时间戳、子分支HiTraceId对象信息。
输入参数:
- mode:通信模式,具体为
- HITRACE_CM_DEFAULT:未指定通信模式。
- HITRACE_CM_THREAD:线程间通信。
- HITRACE_CM_PROCESS:进程间通信。
- HITRACE_CM_DEVICE:设备间通信。
- type:埋点信息类型,具体为
- HITRACE_TP_CS:Client Send,同步/异步通信客户端发送信息。
- HITRACE_TP_SR:Server Receive, 同步/异步通信服务端接收信息。
- HITRACE_TP_SS:Server Send,同步通信服务端发送响应信息。
- HITRACE_TP_CR:Client Receive,同步通信客户端接收响应信息。
- HITRACE_TP_GENERAL:普通输出信息。
- id:当前子分支id。
- fmt:格式化变参描述字符串。
- args:变参。
输出参数:无。
返回值:无。 |
| HiTraceId | HiTraceId(); | 功能:缺省构造函数,生成无效HiTraceId对象。
输入参数:无。
输出参数:无。
返回值:无。 |
| | HiTraceId(const uint8_t* pIdArray, int len) | 功能:构造函数,根据字节数组创建跟踪HiTraceId对象。
输入参数:
- pIdArray:字节数组指针。
- len:字节数组长度。
输出参数:无。
返回值:无。 |
| | bool IsValid() | 功能:HiTraceId对象是否有效。
输入参数:无。
输出参数:无。
返回值:true 有效;false 无效。 |
| | bool IsFlagEnabled(HiTraceFlag flag) | 功能:HiTraceId对象的某标志是否置位。
输入参数:
- flag:跟踪指示位,具体含义见Begin函数中的定义。
输出参数:无。
返回值:true 该标志置位;false 该标志未置位。 |
| | void EnableFlag(HiTraceFlag flag) | 功能:设置某跟踪标志位到HiTraceId对象中。
输入参数:
- flag:跟踪指示位,具体含义见Begin函数中的定义。
输出参数:无。
返回值:无。 |
| | int GetFlags() | 功能:获取HiTraceId对象中设置的标志位。
输入参数:无。
输出参数:无。
返回值:跟踪指示位组合,具体含义见Begin函数中的定义。 |
| | void SetFlags(int flags) | 功能:设置跟踪标志位到HiTraceId对象中。
输入参数:
- flags:跟踪指示位组合,具体含义见Begin函数中的定义。
输出参数:无。
返回值:无。 |
| | uint64_t GetChainId() | 功能:获取跟踪链ID。
输入参数:无。
输出参数:无。
返回值:跟踪链ID。 |
| | void SetChainId(uint64_t chainId) | 功能:设置跟踪链ID到HiTraceId对象中。
输入参数:
- chainId:跟踪链ID。
输出参数:无。
返回值:无。 |
| | uint64_t GetSpanId() | 接口功能:获取当前HiTraceId对象中的分支ID。
输入参数:无。
输出参数:无。
返回值:当前分支ID。 |
| | void SetSpanId(uint64_t spanId) | 功能:设置分支ID到HiTraceId对象中。
输入参数:
- spanId:分支ID。
输出参数:无。
返回值:无。 |
| | uint64_t GetParentSpanId() | 功能:获取当前HiTraceId对象中的父分支ID。
输入参数:无。
输出参数:无。
返回值:父分支ID。 |
| | void SetParentSpanId(uint64_t parentSpanId) | 功能:设置父分支ID到HiTraceId对象中。
输入参数:
- parentSpanId:父分支ID。
输出参数:无。
返回值:无。 |
| | int ToBytes(uint8_t* pIdArray, int len) | 功能:将HiTraceId对象转换为字节数组,便于缓存或者通信传递。
输入参数:
- pIdArray:字节数组指针,数组长度至少为HITRACE_ID_LEN。
- len: 字节数组长度
输出参数:
- pIdArray:字节数组指针,对象有效时存储转换后的对象数据。
返回值:0 转换失败; >0 有效对象转换数组长度。 |
通信调用处理
业务使用时跨设备/跨进程/跨线程的调用是通过通信机制实现的,HiTrace需要通信机制传递traceid。
OpenHarmony系统内置部分通信机制(如ZIDL)已经支持传递traceid。
下面描述了同步通信调用传递traceid的处理过程,异步通信调用处理类似。
对于不支持的扩展通信机制可以参照该方式实现。 图5 同步通信处理
处理流程:
client侧业务模块调用begin()接口启动调用链跟踪。
client侧业务模块发起同步调用transact,到client侧通信组件。
client侧通信组件:
- 从当前线程TLS中获取traceid。
- 生成子调用分支(child traceid)。
- 将child traceid写入同步调用通信数据(transaction data)中。
- 进行CS埋点(Client Send)。
- 将通信数据发送到server侧通信组件。
server侧通信组件收到通信数据:
- 从数据消息包中取出traceid。
- 将traceid设置到当前线程TLS中。
- 进行SR埋点(Server Receive)。
- 然后进行同步调用回调(onTransact)到server侧业务模块。
server侧业务模块进行服务处理,处理完毕发送处理结果(transact reply)到通信组件。
server侧通信组件:
- 进行SS埋点(Server Send)。
- 将响应数据发送到client侧通信组件。
- 清除当前线程TLS中的traceid信息。
client侧通信组件收到响应数据:
- 进行CR埋点(Client Receive)。
- 发送同步调用响应(transact reply)到client侧业务模块。
client侧业务模块进行同步调用响应处理。
client侧业务模块在流程结束时调用end()接口停止调用链跟踪。
开发实例
C++接口实例
- 源代码开发 在类定义头文件或者类实现源文件中,包含hitrace头文件:
#include "hitrace/trace.h"
在业务类实现源文件中使用(启动/结束跟踪):
using namespace OHOS::HiviewDFX;
HiTraceId traceId = HiTrace::Begin("MyServiceFlow", HITRACE_FLAG_DEFAULT);
......
HiTrace::End(traceId);
- 编译设置,在BUILD.gn里增加子系统SDK依赖:
external_deps = [ "hiviewdfx:libhitrace" ]
C接口实例
- 源代码开发 在源文件中,包含hitrace头文件:
#include "hitrace/trace.h"
在业务类实现源文件中使用(启动/结束跟踪):
HiTraceIdStruct traceId = HiTraceBegin("MyServiceFlow", HITRACE_FLAG_DEFAULT);
......
HiTraceEnd(traceId);
- 编译设置,在BUILD.gn里增加子系统SDK依赖:
external_deps = [ "hiviewdfx:libhitrace" ]
你可能感兴趣的文章
热门推荐
-
2、 - 优质文章
-
3、 gate.io
-
8、 golang
-
9、 openharmony
-
10、 Vue中input框自动聚焦