nemo-relay-plugin-observability

配置可观测性插件

先使用内置的 Observability 插件管理一个导出器。这是可复用进程配置的默认选择，也是大多数用户最适合先使用的插件，因为它能让 Relay 捕获的活动变得可见。 在添加更多遥测目标之前，先选择一种验证输出。

只有在测试、脚本或应用需要直接控制注册名称、采集窗口或刷新时机时，才使用手动订阅器或导出器 API。这两种方式使用相同的规范事件流。

选择 Relay 版本

在提供配置或绑定 API 之前，先确定应用使用的是 NeMo Relay 0.6 还是 0.7。优先查看已安装的软件包版本、锁文件或清单。如果无法确定版本，请询问用户；不要在同一个示例中混用两种 API。

• 0.6 使用可观测性配置版本 2。OpenTelemetry 和 OpenInference 是独立的导出器，分别使用 OpenTelemetryConfig / OpenTelemetrySubscriber 和 OpenInferenceConfig / OpenInferenceSubscriber。
• 0.7 使用可观测性配置版本 3。一个类型化的 OpenTelemetry 导出器提供 full、gen_ai 和 openinference 投影。

选择输出

选择最符合用户当前检查目标的输出：

• 控制台或自定义事件处理 使用手动订阅器进行短期进程内检查。
• 原始规范生命周期事件 使用 ATOF JSONL；阅读 references/atof.md。
• 可移植的执行轨迹 使用 ATIF；阅读 references/atif.md。
• OTLP 跟踪 对于 0.6，选择独立的 OpenTelemetry 或 OpenInference 导出器。对于 0.7，选择类型化的 OpenTelemetry 端点（full、gen_ai 或 openinference）。阅读 references/opentelemetry.md；如果后端支持 OpenInference，还需阅读 references/openinference.md。

先选择一种输出并验证，然后再添加其他输出。ATOF 是本地验证的默认选择，因为它以最少的转换保留原始事件流。首次验证请使用合成的非敏感载荷。在导出器接收生产载荷之前，先添加并验证脱敏处理；验证导出器时，切勿显示完整事件记录。

嵌入式事件与订阅者模型

解释采集与导出之间的关系时，请使用此模型：

• NeMo Relay 从作用域、标记、托管工具调用、托管 LLM 调用、中间件和手动生命周期 API 发出一个规范事件流。
• 订阅者消费事件，但不定义事件模型。多个订阅者可以观察同一事件流，用于日志记录、导出、分析或诊断。
• 全局订阅者会在整个进程中持续活跃，直到被移除。
• 作用域本地订阅者由一个活跃作用域持有，并会在该作用域关闭时消失。
• 通过插件安装的订阅者是可复用、由配置驱动的运行时组件。
• 面向导出的订阅者会保留原始 ATOF，或将事件流转换为 ATIF 或适用于相应版本的 OpenTelemetry/OpenInference 格式。
• 如果调用使用托管辅助方法，或手动生命周期参数提供了这些字段，事件负载会反映经过护栏处理的输入和输出。
• LLM 注解遵循以下时效规则：
  • 每个所属 Agent 作用域都会从全新状态开始，而 compaction 标记会刷新注解。
  • 后续的第一个 LLM 启动会保留完整注解历史。之后的启动会保留系统指令、最新的用户消息，以及其后所有助手或工具消息。
  • 如果请求编解码器提供了注解，Relay 会对符合提供方格式的事件输入应用相同的仅限事件投影，而不改变提供方的执行过程。
• 事件字段包括通过 ATOF data 字段提供的语义输入/输出、类型化配置文件数据（例如 model_name 和 tool_call_id），以及编解码器提供的 LLM 请求/响应注解数据，供进程内订阅者和导出器使用。
• 一流技能工具以及读取完整 SKILL.md 的请求会在工具 span 下自动发出 skill.load 标记。负载仅包含 skill_name；元数据会记录加载来源和工具名称。不完整读取不计入其中，而含义不明确的斜杠命令展开会使用单独的 skill.load.inferred 名称。如果工具执行随后失败，提前发出的标记仍会保留。

共享生命周期

1. 创建导出器或订阅者。
2. 在相关作用域工作开始前，使用唯一名称注册它。
3. 在作用域内运行经过 NeMo Relay 插桩的工作。
4. 按导出器专属参考文档规定的顺序刷新并注销。
5. 在进程或子系统完成工作后将其关闭。

绑定名称

请使用所选语言绑定和 Relay 版本导出的名称：

• Python 0.6：nemo_relay.subscribers.register(...)、AtofExporter、 AtifExporter、OpenTelemetrySubscriber 和 OpenInferenceSubscriber
• Python 0.7：使用相同的注册方法和文件导出器，另有支持全部三种类型化投影的 OpenTelemetrySubscriber
• Node.js 通过根导出项遵循相同的 0.6/0.7 区分
• Rust：nemo_relay::api::subscriber 和 nemo_relay::observability::*
• Go：以源码为先的封装会提供等效的注册、导出器和订阅者生命周期方法

何时加载参考文档

仅加载所选输出所需的参考文档：

• 对于用于本地调试或离线检查的原始 JSONL 事件，请加载 references/atof.md。
• 对于 ATIF 轨迹，请加载 references/atif.md。
• 对于 OTLP/OpenTelemetry 轨迹，请加载 references/opentelemetry.md。
• 对于独立的 0.6 OpenInference 导出器或 0.7 openinference OpenTelemetry 投影，请加载 references/openinference.md。

何时使用其他技能

如果任务属于相邻工作流，请选择其他技能：

• 使用 nemo-relay-plugin-build，将基于订阅者的导出行为打包为可复用插件。
• 如果尚未对作用域、工具调用或 LLM 调用进行插桩，请使用 nemo-relay-get-started 或 nemo-relay-instrument-calls。
• 使用 nemo-relay-debug-runtime-integration 诊断缺失的遥测数据。

相关技能

在相邻工作流中使用以下技能：

• 使用 nemo-relay-instrument-calls 为应用调用添加检测。
• 使用 nemo-relay-instrument-typed-wrappers 添加类型化封装。
• 使用 nemo-relay-plugin-build 打包可复用行为。
• 使用 nemo-relay-debug-runtime-integration 诊断缺失事件。