轨迹追踪插件

Nacos Trace 插件用于订阅 Nacos 内部资源操作事件，帮助运维人员做审计、排障和诊断。它记录的是 Nacos 领域事件，例如服务注册、服务推送、实例健康状态变化、AI 资源操作等。

它不是应用服务之间的分布式链路追踪。如果需要观察业务服务之间的调用链，请使用 OpenTelemetry、SkyWalking、Zipkin 等链路追踪体系。

适用场景

• 记录服务注册、注销、订阅、推送等 Naming 事件。
• 记录实例健康状态变化原因，辅助排查实例上下线抖动。
• 将 Nacos 资源操作写入日志、审计系统或观测平台。
• 订阅 AI 资源生命周期事件，保留资源发布、上线、下线、删除等审计记录。

工作模型

Trace 插件实现 NacosTraceSubscriber。Nacos 启动时通过 SPI 加载订阅者，并按订阅者声明的事件类型分发事件。

当前事件类型

Naming 相关事件：

AI 资源相关事件：

DeregisterInstanceTraceEvent 会携带注销原因。常见值包括 REQUEST、NATIVE_DISCONNECTED、SYNCED_DISCONNECTED 和 HEARTBEAT_EXPIRE。

Nacos 默认提供了 AI 资源 Trace 日志订阅者，会将 AiResourceTraceEvent 写入 ai-resource-trace.log，用于兼容 AI 资源审计日志。

启用插件

将插件 JAR 放入 ${nacos.home}/plugins，或加入 Nacos Server 启动 classpath。插件实现需要通过 META-INF/services/com.alibaba.nacos.plugin.trace.spi.NacosTraceSubscriber 声明。

启动后，可在 ${nacos.home}/logs/nacos.log 中查看加载日志：

[TracePluginManager] Load NacosTraceSubscriber(...) name(...) successfully.

Nacos 3.2 起，Trace 插件也会暴露给统一插件管理，插件类型为 trace。如果关闭了某个 Trace 插件，Nacos 不会再向该订阅者分发事件。

开发插件

插件依赖：

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

实现 com.alibaba.nacos.plugin.trace.spi.NacosTraceSubscriber：

最小示例：

public class NamingAuditTraceSubscriber implements NacosTraceSubscriber {

    @Override
    public String getName() {
        return "naming-audit";
    }

    @Override
    public List<Class<? extends TraceEvent>> subscribeTypes() {
        return Collections.singletonList(RegisterInstanceTraceEvent.class);
    }

    @Override
    public void onEvent(TraceEvent event) {
        // Write audit log or send to an observability backend.
    }
}

降级和稳定性

Trace publisher 使用队列分发事件。队列压力过大时，Nacos 可以丢弃新的 Trace 事件以保护服务端稳定性。发生丢弃时，日志中会出现类似信息：

Trace Event Publish failed, event : ..., publish queue size : ...

生产建议：

• 写远端系统、文件、数据库或消息队列时，使用独立 Executor。
• 为外部 sink 设置超时、限流和失败重试策略。
• 不要在 onEvent() 中修改 Nacos 资源。
• 不要把敏感信息写入 Trace 日志。
• 事件丢弃代表观测数据不完整，不代表 Nacos 主流程失败。

排查