wehub-resource-sync
121 lines
5.9 KiB
Markdown
121 lines
5.9 KiB
Markdown
<!--
|
|
Copyright 1999-2026 Alibaba Group Holding Ltd.
|
|
|
|
Licensed under the Apache License, Version 2.0 (the "License");
|
|
you may not use this file except in compliance with the License.
|
|
You may obtain a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
-->
|
|
|
|
# Trace 插件规范
|
|
|
|
## 范围
|
|
|
|
Trace 插件用于将 Nacos 领域操作事件发布给订阅者。它面向 Nacos 操作追踪、审计和诊断，不是
|
|
应用服务之间的分布式链路追踪。
|
|
|
|
这是订阅或广播插件。多个订阅者可以观察同一个事件。Trace 插件不得拥有主业务决策权。
|
|
通用插件生命周期和状态规则由 [Nacos 插件化规范](plugin-spec.md) 定义。
|
|
Trace 事件分发运行在 Nacos 本地事件基础设施之上，并必须遵循
|
|
[事件分发与 NotifyCenter 规范](../design/foundation-event-dispatch-spec.md)。
|
|
共享 trace、审计、指标和诊断边界由
|
|
[可观测钩子规范](../design/foundation-observability-hooks-spec.md)定义。
|
|
|
|
与通用分布式链路追踪不同，Nacos Trace 事件描述的是 Nacos 资源操作，例如实例注册、
|
|
服务删除、服务推送和健康状态变化。它不是应用服务之间调用链的 span。
|
|
|
|
## 概念
|
|
|
|
| 概念 | 含义 |
|
|
|------|------|
|
|
| `TraceEvent` | 基础不可变事件，包含 type、event time、namespace、group 和 name。 |
|
|
| 领域 Trace 事件 | 增加领域专有字段的子类。 |
|
|
| Combined subscriber | 核心桥接器，将领域事件分发给感兴趣的插件订阅者。 |
|
|
| Subscriber executor | 可选 executor，用于隔离插件 IO 或慢回调。 |
|
|
|
|
## SPI
|
|
|
|
插件实现 `NacosTraceSubscriber`。
|
|
|
|
| 方法 | 要求 |
|
|
|------|------|
|
|
| `getName()` | 稳定订阅者名称，重复名称后加载者会替换先加载者。 |
|
|
| `subscribeTypes()` | 该订阅者希望接收的 Trace 事件类。 |
|
|
| `onEvent(event)` | 订阅者回调。 |
|
|
| `executor()` | 可选的异步回调执行器。 |
|
|
|
|
该插件以 `trace` 类型暴露给核心插件管理器。
|
|
|
|
## 事件规则
|
|
|
|
Trace 事件携带事件类型、事件时间、命名空间、分组和资源名等
|
|
[Nacos 资源信息](../design/resource-model-spec.md)。领域事件可以增加额外字段。
|
|
通用字段名、脱敏规则和 metric label 边界由
|
|
[可观测钩子规范](../design/foundation-observability-hooks-spec.md)定义。本文档不要求每个领域
|
|
发出完全相同的业务字段。
|
|
|
|
订阅者必须把事件视为不可变事实。除非所属领域明确记录该副作用，否则订阅者不得在 Trace
|
|
回调中修改 Nacos 资源。
|
|
|
|
当前 Naming Trace 事件类型包括：
|
|
|
|
| 事件类 | Event type | 含义 |
|
|
|--------|------------|------|
|
|
| `RegisterInstanceTraceEvent` | `REGISTER_INSTANCE_TRACE_EVENT` | 实例注册。 |
|
|
| `BatchRegisterInstanceTraceEvent` | `BATCH_REGISTER_INSTANCE_TRACE_EVENT` | 批量实例注册。 |
|
|
| `DeregisterInstanceTraceEvent` | `DEREGISTER_INSTANCE_TRACE_EVENT` | 实例注销。 |
|
|
| `RegisterServiceTraceEvent` | `REGISTER_SERVICE_TRACE_EVENT` | 空服务创建。 |
|
|
| `DeregisterServiceTraceEvent` | `DEREGISTER_SERVICE_TRACE_EVENT` | 空服务删除。 |
|
|
| `UpdateInstanceTraceEvent` | `UPDATE_INSTANCE_TRACE_EVENT` | 实例元数据或状态更新。 |
|
|
| `UpdateServiceTraceEvent` | `UPDATE_SERVICE_TRACE_EVENT` | 服务元数据更新。 |
|
|
| `SubscribeServiceTraceEvent` | `SUBSCRIBE_SERVICE_TRACE_EVENT` | 服务订阅。 |
|
|
| `UnsubscribeServiceTraceEvent` | `UNSUBSCRIBE_SERVICE_TRACE_EVENT` | 服务取消订阅。 |
|
|
| `PushServiceTraceEvent` | `PUSH_SERVICE_TRACE_EVENT` | 向订阅者推送服务。 |
|
|
| `HealthStateChangeTraceEvent` | `HEALTH_STATE_CHANGE_TRACE_EVENT` | 实例健康状态变化。 |
|
|
|
|
`DeregisterInstanceTraceEvent` 携带注销原因。当前原因包括 `REQUEST`、
|
|
`NATIVE_DISCONNECTED`、`SYNCED_DISCONNECTED` 和 `HEARTBEAT_EXPIRE`。
|
|
|
|
当前 AI 资源 Trace 事件类型包括：
|
|
|
|
| 事件类 | Event type | 含义 |
|
|
|--------|------------|------|
|
|
| `AiResourceTraceEvent` | `AI_RESOURCE_TRACE_EVENT` | AI 资源生命周期操作，例如创建草稿、评审、发布、上线/下线、删除、标签更新、scope 更新，或兼容审计日志的默认文件输出。 |
|
|
|
|
`AiResourceTraceEvent` 携带操作者、资源类型、资源标识、可选版本、操作、状态、
|
|
客户端 IP 和可选扩展文本。
|
|
|
|
## 执行
|
|
|
|
`NacosCombinedTraceSubscriber` 注册领域事件 publisher，并只把匹配的事件类分发给插件
|
|
订阅者。如果 `executor()` 返回 `null`，回调会在事件分发路径中执行。写远端系统、文件、
|
|
数据库或其他慢 sink 的插件应返回专用 executor。
|
|
|
|
Trace publisher 允许在队列压力下丢弃 trace event 进行降级，具体边界遵循本地事件降级规则。
|
|
|
|
Trace 订阅者通过 SPI 加载。同一类型内重复名称不适合生产稳定使用，插件包应使用唯一名称。
|
|
|
|
## 降级
|
|
|
|
Trace 插件属于观测扩展。插件失败不得破坏 Nacos 核心数据变更或请求处理。执行阻塞 IO 的
|
|
插件应返回专用 executor。当 Trace 队列过载时，可以丢弃事件以保护服务端稳定性。
|
|
|
|
当前核心桥接器会捕获订阅者回调异常。插件实现仍必须记录足够信息，帮助运维人员诊断自己的
|
|
sink 故障。
|
|
|
|
## 实现说明
|
|
|
|
Nacos 服务端仓库定义 Trace SPI 和事件模型。参考订阅者实现可以位于外部插件仓库，并应遵守
|
|
本文档。
|
|
|
|
为了兼容已有 AI 资源审计日志，Nacos 在 `plugin-default-impl` 中提供默认的
|
|
`AiResourceTraceEvent` 文件日志订阅者，并随默认插件包发布。它是标准 Trace 订阅者，
|
|
并将既有 JSON 行格式写入 `ai-resource-trace.log`。
|