> ## Documentation Index
> Fetch the complete documentation index at: https://acp-docs.cxykevin.top/llms.txt
> Use this file to discover all available pages before exploring further.

# 代理遥测导出

* 作者：[@codefromthecrypt](https://github.com/codefromthecrypt)
* 支持者：[@benbrandt](https://github.com/benbrandt)

## 电梯演讲

> 您提议进行什么更改？

定义代理如何将遥测（日志、指标、追踪）导出到客户端，而无需通过 ACP 传输隧道传输。客户端运行本地遥测接收器，并在启动代理时传递标准的 OpenTelemetry 环境变量。这使遥测保持在 ACP 传输之外，并使编辑器能够显示代理活动、调试问题以及与可观测性后端集成。

## 现状

> 今天的事情是如何运作的，这导致了什么问题？我们为什么要改变？

ACP 定义了客户端如何将代理作为子进程启动并通过 stdio 进行通信。[meta-propagation RFD](./meta-propagation) 通过 `params._meta` 解决了追踪上下文传播问题，实现了追踪关联。但是，对于代理应该如何导出实际的遥测数据（跨度、指标、日志），没有约定。

没有标准方法：

1. **无法了解代理行为** - 编辑器无法显示代理正在做什么（令牌使用、工具调用、计时）
2. **调试困难** - 当代理失败时，没有结构化的方法来捕获诊断信息
3. **解决方案碎片化** - 每个代理/客户端对发明自己的遥测机制
4. **凭证暴露风险** - 如果代理需要直接将遥测发送到后端，它们需要凭证

通过 ACP stdio 传输隧道传输遥测是有问题的：

* **队头阻塞** - 遥测流量可能会延迟代理消息
* **实现负担** - ACP 需要定义遥测消息格式
* **耦合** - 代理需要 ACP 特定的遥测代码而不是标准 SDK

## 我们提议对此做什么

> 您提议如何改善情况？

想要接收代理遥测的客户端运行本地 OTLP（OpenTelemetry Protocol）接收器，并在启动代理子进程时注入环境变量：

```
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_SERVICE_NAME=agent-name
```

使用 OpenTelemetry SDK 的代理会自动从这些变量配置。客户端的接收器可以：

* 在编辑器 UI 中显示遥测（例如，令牌计数、计时、错误）
* 将遥测转发到客户端配置的可观测性后端
* 在转发之前添加客户端上下文

这遵循 [OpenTelemetry 收集器部署模式](https://opentelemetry.io/docs/collector/deployment/agent/)，本地接收器将遥测代理到后端。

### 架构

```
┌────────────────────────────────────────────────────────────┐
│ 客户端/编辑器                                              │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐  │
│  │ ACP 处理器   │    │OTLP 接收器   │───▶│   导出器     │  │
│  └──────────────┘    └──────────────┘    └──────────────┘  │
└────────┬─────────────────────▲──────────────────┬──────────┘
         │ stdio               │ HTTP             │
         ▼                     │                  ▼
┌─────────────────────┐        │         ┌───────────────────┐
│ 代理进程            │        │         │ 可观测性          │
│  ┌──────────────┐   │        │         │ 后端              │
│  │ ACP 代理     │   │        │         └───────────────────┘
│  ├──────────────┤   │        │
│  │ OTEL SDK     │────────────┘
│  └──────────────┘   │
└─────────────────────┘
```

### 发现

环境变量必须在启动子进程之前设置，但 ACP 能力交换发生在连接之后。发现的选项：

1. **乐观注入** - 客户端无条件注入 OTEL 环境变量。不支持 OpenTelemetry 的代理只需忽略它们。这是务实的，因为环境变量成本很低，OTEL SDK 可以优雅地处理配置错误。

2. **注册表元数据** - 代理注册表（如 PR #289 中提议的）可以在代理清单中包含遥测支持，让客户端提前知道。

3. **手动配置** - 用户配置他们的客户端以对特定代理启用遥测收集。

## 美好的未来

> 一旦这个功能存在，事情将如何发展？

1. **编辑器集成** - 编辑器可以显示代理活动：令牌使用、工具调用计时、模型切换、错误
2. **统一调试** - 当代理失败时，结构化遥测可用于诊断
3. **端到端追踪** - 结合 `params._meta` 追踪传播，追踪从客户端流经代理到任何下游服务
4. **无需凭证共享** - 代理永远看不到后端凭证；客户端处理身份验证
5. **标准 SDK** - 代理作者使用在任何上下文中都能正常工作的普通 OpenTelemetry SDK，而不是 ACP 特定的代码

## 实施细节

> 告诉我更多关于您的实施。您的详细实施计划是什么？

### 1. 创建 `docs/protocol/observability.mdx`

添加新的协议文档页面，涵盖 ACP 的可观测性实践。此页面将描述：

**对于客户端/编辑器：**

* 运行 OTLP 接收器以收集代理遥测
* 在启动代理子进程时注入 `OTEL_EXPORTER_*` 环境变量
* 尊重用户配置的 `OTEL_*` 变量（如果已设置，不要覆盖）
* 使用客户端凭证将遥测转发到配置的后端

**对于代理作者：**

* 使用具有标准自动配置的 OpenTelemetry SDK
* 代理操作的推荐跨度、指标和日志模式
* 当 `OTEL_*` 变量存在与不存在时，遥测如何流动

### 2. 更新 `docs/protocol/extensibility.mdx`

添加一个指向新可观测性文档的部分，类似于可扩展性概念与其他协议功能的关系方式。简要提及遥测实践（遥测导出）在单独的文档中记录。

### 3. 更新 `docs/docs.json`

将 `protocol/observability` 添加到协议导航组。

## 常见问题

> 在编写本文档的过程中或随后的讨论中出现了哪些问题？

### 这与 `params._meta` 中的追踪传播有什么关系？

它们是互补的：

* **追踪传播**（`params._meta` 包含 `traceparent` 等）传递追踪上下文，以便跨度可以关联
* **遥测导出**（此 RFD）定义代理发送实际跨度/指标/日志数据的位置

两者都需要用于端到端可观测性。

### 如果代理不使用 OpenTelemetry 怎么办？

没有 OTEL SDK 的代理只需忽略环境变量。不会造成伤害。随着越来越多的代理采用 OpenTelemetry，生态系统会受益。

### 如果用户已经配置了 `OTEL_*` 环境变量怎么办？

如果环境中已经设置了 `OTEL_*` 变量，客户端不应覆盖它们。用户配置的遥测设置优先，允许用户在他们希望时将代理遥测导向自己的后端。

### 为什么不定义 ACP 特定的遥测消息？

这会重复 OTLP 功能，增加 ACP 的实现负担，并强制代理作者使用非标准 API。使用 OTLP 意味着代理可以使用标准工具和文档。

### 对于不是作为子进程启动的代理怎么办？

此 RFD 侧重于客户端启动代理的 stdio 传输。对于其他传输（HTTP 等），代理需要替代的配置机制，这可以在未来的 RFD 中解决。

### 您考虑了哪些替代方法，为什么选择这一个？

1. **通过 ACP 隧道传输遥测** - 由于队头阻塞问题和实现复杂性被拒绝
2. **代理直接导出到后端** - 因为需要与代理共享凭证被拒绝
3. **基于文件的遥测** - 因为不支持实时显示并增加复杂性被拒绝

环境变量方法：

* 使用现有标准（OTLP、OpenTelemetry SDK 约定）
* 将遥测保持在 ACP 消息之外
* 让客户端控制遥测的去向，而不暴露凭证
* 无需更改 ACP 消息格式

## 修订历史

* 2025-12-04：初始草稿