AgoraIO-Extensions / AgoraIO-Extensions/agent-infra

feat(platform): expose operational traces logs and metrics

Offen
#441 3 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
needs-triage
Vorherrschende Sprache
TypeScript
Sterne
0
Forks
0
Ø Merge
8 Std. 51 Min.
Gemergte PRs (30 T.)
99

Beschreibung

> 本票继续由 [M1 汇合计划](https://github.com/AgoraIO-Extensions/agent-infra/issues/150) 统筹,不进入既有冻结执行 snapshot;主系统总责 LichKing-2234,具体执行者、资源窗口与容量仍待落实,Start/Target 留空。新增契约待评估,Project 保持 Todo;实现前须完成适用文档评审与合入、依赖回读和本票执行准入。

## Problem

工程 Spec §18 要求 Platform 请求、SSE、投递、Workload 和 PostgreSQL/outbox 的工程观测。当前 source 已传递 traceId/requestId 等关联字段,但没有正式 OpenTelemetry/Pino 装配和上述指标出口;既有审计读模型与 #334 发布配置验证不能替代运行观测。本票交付 Platform 工程遥测装配、导出和告警,供容量与故障演练使用;实际模型/工具事实由对应 Runtime 契约唯一生产。

## Scope

- 按既有 OpenTelemetry + Pino 基线,在 Platform API/Worker 的装配和 Adapter 边界接入结构化日志、Trace 与 Metric;领域只输出已有业务结果,不引入 SDK、HTTP/SQL/Kubernetes 类型。
- 沿用 traceId/requestId/agentId/conversationId/executionId 的关联;不创建第二套业务事件权威,不把 Trace 当作持久会话或审计替代。
- 覆盖 HTTP 请求量/错误率/延迟、SSE 在线/重连/积压、消息提交/投递/繁忙/失败/完成、Agent 启动/更新/不可用/调谐失败、PostgreSQL 连接池/慢查询及 outbox 积压。慢查询只输出受控摘要和耗时,不记录参数或原始 SQL 中的用户输入。
- 指标标签保持有界,不以用户、Conversation、executionId 或任意文本作为高基数 label;必要关联 ID 仅进入受控日志/Trace。采样或遥测故障不影响业务事务和授权结果。
- 提供部署中立、可关闭、容量有界的 exporter 配置与本地验证入口;部署产品/地址和凭证不进入源码、普通配置示例或 Issue。不新增独立观测微服务或通用监控平台。
- 复用 #190 的 Workload 状态和既有业务审计;不重写生命周期、投递、恢复或发布机制。后续文件 Adapter 负责通过同一约定补齐对象存储失败指标,不在本票实现对象存储。
- Connection 观测和跨系统 callId 验证由 #432 对齐后的 Connection/联合验收范围承担。本票不实现 Connection、Agent Eval/效果指标或正式值班排班。

- 消费 [持久任务契约](https://github.com/AgoraIO-Extensions/agent-infra/issues/482)、[实际模型/工具事实](https://github.com/AgoraIO-Extensions/agent-infra/issues/483) 和 [审计查询入口](https://github.com/AgoraIO-Extensions/agent-infra/issues/484) 的规范化结果,沿原 request/trace/Execution/操作/尝试串起 API、等待、投递、Worker、Runtime、模型/工具、结果保存与 SSE;持久工作项带关联上下文,异步 Trace 可用 span link,不从日志反解析或重新采集一套调用事实。
- 补充授权拒绝、等待数量/时长、投递/执行/取消/待核实/完成、实际模型/工具耗时与错误、Platform 审计写入/查询及采集/导出故障信号。重复事件去重,合法新尝试独立计数;可得用量按实际事实统计,缺失不作零值,高基数 ID 仍只进入受控日志/Trace。
- 交付服务不可用、持续积压和异常错误的可配置告警规则、查询入口说明与受控告警出口验证;阈值绑定部署容量配置。复用部署选择的后端,不增加观测产品;ObjectStorage 后续生产者继续按既有归属接入同一约定。遥测导出失败独立报告,必要意图/审计故障遵循业务拒绝或待核实语义,不能按尽力而为处理。

## Acceptance criteria

- [ ] **AC-1:** Platform API/Worker 在真实装配中按既有技术栈输出结构化日志、Trace 和工程指标,SDK/vendor 类型不进入 Core 或 wire contract。
- [ ] **AC-2:** HTTP、SSE、消息、Workload、PostgreSQL 和 outbox 指标在对应真实成功、失败、繁忙、重试和积压路径可观测,名称、单位、计数边界与关联方法有文档,不从业务内存计数冒充 durable 结果。
- [ ] **AC-3:** 从请求、durable outbox 到 Worker/RuntimeHost 调用能关联既有稳定 ID;重放不伪造新业务结果,Trace 采样和 exporter 故障不改变事务、幂等或授权语义。
- [ ] **AC-4:** 日志、Trace、指标及 exporter 错误不包含用户消息、附件内容、模型内部思考、Token、Secret、调用证明或可恢复凭证;指标 label 为有界集合。
- [ ] **AC-5:** exporter 不可用、队列满、慢消费者、关闭和进程退出均有有界行为,不阻塞请求或无限积压;部署配置缺失时具有明确可验证的禁用状态。
- [ ] **AC-6:** 本地 collector/受控 sink 和真实 Platform API/Worker 集成验证通过;采集配置、source SHA、镜像和验证命令可回读,不能只凭 mocked SDK 调用或截图证明接入完成。

- [ ] **AC-7:** 真实任务可在采集后端关联 API → 等待/投递 → Worker → Runtime → 模型/工具 → 结果保存/SSE,各阶段耗时与失败原因来自对应事实;四模板实际模型/工具事实可消费,缺失明确标记,重放不重复计数且合法新尝试可区分。
- [ ] **AC-8:** Platform 审计写入/查询、运行依赖和采集/导出故障有可区分信号;服务不可用、持续积压与异常错误能在受控环境实际触发告警并在恢复后收敛,规则/阈值/后端配置及输出证据可回读。
- [ ] **AC-9:** 采样、exporter 关闭/慢消费/故障不改写任务或授权结果,必要审计失败仍按原业务契约处理;实际用户/应用任务的正文、Eval 内容、附件、思考、证明和凭证不进入遥测,伪造关联不能成为身份或权限依据。

## Validation

- 运行格式/脱敏、label 边界、计数定义和关联测试;使用合成敏感哨兵验证日志、Trace、指标及 exporter 失败路径不泄漏。
- 在容器化 PostgreSQL 与正式 API/Worker 装配下触发成功、拒绝、投递、积压、SSE 重连和 Workload 状态,读取实际采集结果;测试只改变本票范围内观测,不重复实现恢复状态机。
- 模拟 exporter 断线、慢消费者和积压,验证超时/缓冲有界、业务结果不变;记录本次镜像、配置、采集证据。
- 执行 `AGENTS.md` 完整仓库验证与 current-head Standards/Spec Review。

- 在实际 API/Store/Worker/RuntimeHost、四模板已交付事实与受控 collector 下执行成功/等待/模型及工具失败、重连重放、取消及 unknown 场景;逐阶段核对持久记录、Trace/指标与实际操作,区分任务、操作、尝试与事件计数。
- 注入 Platform 审计读写、Runtime 依赖、exporter 中断和积压故障,验证独立健康信号、受控告警触发/恢复、业务结果及敏感哨兵;正式运维容量阈值由容量与恢复票结合实际部署测量,不在本票预设生产并发承诺。

## Blocked by

- #190
- #482
- #483
- #484

## Authority

- 工程 Spec §§2.1、6、18、19、22;Agent Platform PRD §13/§14;main `f0e8aa58ca90dec2583459818c1167781979235f`。
- #303 的业务审计、#334 的镜像/发布验证和 #190 的 Workload 状态保持各自唯一归属。本票不把业务关联字段存在视为工程观测已交付。
- 本次新增范围按 [平台 PRD 候选 §§13–16](https://github.com/AgoraIO-Extensions/agent-infra/blob/2eb2762b889a27372c259039d27279cf646c5b1e/docs/prd/PRD-agent-platform-M1.md)、[工程 Spec 候选 §§18–19](https://github.com/AgoraIO-Extensions/agent-infra/blob/7f3b2083d44191ab4b280d7eb8222d7785937b8e/docs/architecture/SPEC-agent-infra-M1-engineering-architecture.md) 和 [Runtime HLD 候选](https://github.com/AgoraIO-Extensions/agent-infra/blob/5da6fff274ffc7a7ee36ae3ebd61d6100ccc9571/docs/architecture/HLD-agent-runtime-M1.md) 评审;实施前回读合入后的权威版本并复核差额,历史基础引用不能覆盖新增结论。

Beitragsleitfaden

Für dieses Repository ist kein Beitragsleitfaden indexiert

Bewertung

Dieses Issue wurde noch nicht bewertet.

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.