HiTrace开发指导

About 26 min

HiTrace开发指导

概述

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

应用场景

HiTrace在产品中应用场景如下,包括:

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

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

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

    图 1 HiTrace应用场景

业务使用示例

图 2 业务调用流程图(跨设备、跨进程同步调用)

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

    图 3 业务调用流程序列图

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

  2. 在日志和事件等信息中自动附加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(uint8_t* pIdArray, int len)

int HiTraceIdToBytes(const HiTraceIdStruct* pId, uint8_t* 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信息,缺省不输出。
    • HITRCE_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 同步通信处理

处理流程:

  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. 源代码开发

    在类定义头文件或者类实现源文件中,包含hitrace头文件:

    #include "hitrace/trace.h"
    
    1

    在业务类实现源文件中使用(启动/结束跟踪):

    using namespace OHOS::HiviewDFX;
    HiTraceId traceId = HiTrace::Begin("MyServiceFlow", HITRACE_FLAG_DEFAULT);
    ......
    HiTrace::End(traceId);
    
    1
    2
    3
    4
  2. 编译设置,在BUILD.gn里增加子系统SDK依赖:

    external_deps = [ "hiviewdfx:libhitrace" ]
    
    1

C接口实例

  1. 源代码开发

    在源文件中,包含hitrace头文件:

    #include "hitrace/trace.h"
    
    1

    在业务类实现源文件中使用(启动/结束跟踪):

    HiTraceIdStruct traceId = HiTraceBegin("MyServiceFlow", HITRACE_FLAG_DEFAULT);
    ......
    HiTraceEnd(traceId);
    
    1
    2
    3
  2. 编译设置,在BUILD.gn里增加子系统SDK依赖:

    external_deps = [ "hiviewdfx:libhitrace" ]
    
    1