跳到主要内容
版本:2.X(推荐)

轨迹追踪插件

Nacos从2.2.0版本开始,可通过SPI机制注入轨迹追踪实现插件,在插件中订阅并处理追踪事件,并按照您期望的方式进行处理(如打日志,写入存储等)。本文档详细介绍一个轨迹追踪插件如何实现以及如何使其生效。

注意: 目前轨迹追踪插件处于Beta测试阶段,其API及接口方法定义可能会在后续版本升级而有较大修改,请注意您的插件适用版本。

Nacos 的轨迹追踪不同于一般意义的链路追踪, 主要目的是追踪和记录一些Nacos的相关操作,如服务注册、注销、推送、状态变更等,并非追踪微服务间的相互访问链路,如需要监控追踪服务间的相互访问,请使用对应的链路追踪项目。

轨迹追踪插件中的概念

追踪事件 TraceEvent

Nacos 在关键操作的链路中进行了埋点,定义了一系列的追踪事件TraceEvent, 将多个针对相同资源(如服务,配置等)的追踪事件串起来之后,便得到了该资源的轨迹。

在追踪事件TraceEvent中,会包含如下内容:

字段名描述
type事件的类型,由具体事件定义
eventTime事件发生的时间
namespaceId事件对应资源的命名空间ID
group事件对应资源的分组名
name事件对应资源的资源名,如服务名或配置的dataId

目前Nacos中已经定义的子追踪事件类型有:

事件名描述详情
RegisterInstanceTraceEvent服务实例注册事件,主要发生于注册服务提供者时事件详情
DeregisterInstanceTraceEvent服务实例注销事件,主要发生于注销服务提供者时事件详情
RegisterServiceTraceEvent服务注册事件,不同于服务实例注册事件,主要发生于创建空服务时事件详情
DeregisterServiceTraceEvent服务注销事件,不同于服务实例注销事件,主要发生于删除空服务时事件详情
SubscribeServiceTraceEvent服务订阅事件,主要发生于订阅服务时事件详情
UnsubscribeServiceTraceEvent取消服务订阅事件,主要发生于取消订阅服务时事件详情
PushServiceTraceEvent服务推送事件,主要发生于发生服务推送时事件详情
HealthStateChangeTraceEvent服务实例健康状态变更事件,主要发生于实例因心跳/健康检查而导致实例健康状态变化时事件详情

插件开发

开发Nacos服务端轨迹追踪插件,首先需要依赖轨迹追踪插件的相关API

        <dependency>
<groupId>com.alibaba.nacos</groupId>
<artifactId>nacos-trace-plugin</artifactId>
<version>${project.version}</version>
</dependency>

${project.version} 为您开发插件所对应的Nacos版本

随后实现com.alibaba.nacos.plugin.trace.spi.NacosTraceSubscriber接口, 并将您的实现添加到SPI的services当中。

接口中需要实现的方法如下:

方法名入参内容返回内容描述
getNamevoidString插件的名称,当名字相同时,后加载的插件会覆盖先加载的插件。
subscribeTypesvoidList<Class<? extends TraceEvent>>该插件期望订阅的事件类型,返回空列表是不订阅。
onEventTraceEventvoid处理事件的具体逻辑,输入的具体事件类型由subscribeTypes接口定义
executorvoidExecutor当返回不为null时,将使用该Executor进行onEvent调用,否则将使用事件分发线程进行调用

注意: 建议插件实现时使用独立Executor,如插件实现中有存在阻塞的IO操作,当存在IO异常时将阻塞其他事件的onEvent调用,导致积压问题。

nacos-group/nacos-plugin中,有一个demo的轨迹追踪插件实现,该demo插件订阅了注册及注销实例的事件,并打印到日志中。

轨迹追踪插件的降级

由于轨迹追踪插件增强监控类别的插件,不会对Nacos的数据造成影响,因此当轨迹追踪插件出现问题时,因尽量不影响Nacos主要链路。

因此建议插件实现时使用独立Executor,如插件实现中有存在阻塞的IO操作,当存在IO异常时将阻塞其他事件的onEvent调用,导致积压问题。

如果不幸发生积压,轨迹追踪插件的事件队列达到上限时,会自动丢弃后来的事件,以保证系统整体稳定性。

发生丢弃时能从nacos.log中看到Trace Event Publish failed, event : {}, publish queue size : {}字样。

附录:子追踪事件详情

服务实例注册事件 RegisterInstanceTraceEvent

2.2.0版本开始支持。

type: REGISTER_INSTANCE_TRACE_EVENT

额外内容:

字段名描述
clientIp注册服务实例请求的来源IP,可能为null
rpc来源是否为gRPC,true时为gRPC注册,false时为HTTP注册
instanceIp所注册实例的地址IP/HOST
instancePort所注册实例的端口PORT

服务实例注销事件 DeregisterInstanceTraceEvent

2.2.0版本开始支持。

type: DEREGISTER_INSTANCE_TRACE_EVENT

额外内容:

字段名描述
clientIp注销服务实例请求的来源IP,可能为null
reason注销服务实例的原因,详情见服务实例注销原因
rpc来源是否为gRPC,true时为gRPC注册,false时为HTTP注册
instanceIp所注销实例的地址IP/HOST
instancePort所注销实例的端口PORT

服务实例注销原因 DeregisterInstanceReason

原因描述
REQUEST注销来自于客户端请求,即由用户发起的注销
NATIVE_DISCONNECTED注销来自于客户端链接断开
SYNCED_DISCONNECTED注销来自于客户端链接断开,但该客户端链接是与集群其他的节点,断开后同步到本节点的
HEARTBEAT_EXPIRE注销来自于客户端心跳请求超时,适用于1.X版本的客户端

服务注册事件 RegisterServiceTraceEvent

2.2.0版本开始支持。

type: REGISTER_SERVICE_TRACE_EVENT

额外内容:无

服务注销事件 DeregisterServiceTraceEvent

2.2.0版本开始支持。

type: DEREGISTER_SERVICE_TRACE_EVENT

额外内容:无

服务订阅事件 SubscribeServiceTraceEvent

2.2.0版本开始支持。

type: SUBSCRIBE_SERVICE_TRACE_EVENT

额外内容:

字段名描述
clientIp订阅者IP

取消服务订阅事件 UnsubscribeServiceTraceEvent

2.2.0版本开始支持。

type: UNSUBSCRIBE_SERVICE_TRACE_EVENT

额外内容:

字段名描述
clientIp订阅者IP

服务推送事件 PushServiceTraceEvent

2.2.0版本开始支持。

type: PUSH_SERVICE_TRACE_EVENT

额外内容:

字段名描述
clientIp订阅者IP
instanceSize本次推送的提供者数量
pushCostTimeForAll本次推送总耗时,定义为开始发起推送到推送结束时的耗时,包含了在聚合队列中的等待时间以及执行推送的时间
pushCostTimeForNetWork本次推送的网络耗时,定义为执行推送到推送结束的耗时,仅包含了网络耗时
serviceLevelAgreementTime本次推送的实际生效耗时,定义为服务变更到推送结束时的耗时,粗略值

服务实例健康状态变更事件 HealthStateChangeTraceEvent

2.2.0版本开始支持。

type: HEALTH_STATE_CHANGE_TRACE_EVENT

额外内容:

字段名描述
instanceIp实例的地址IP/HOST
instancePort实例的端口PORT
isHealthy变更结果是否为健康
healthCheckType健康检查的类型
healthStateChangeReason健康状态发生的原因