AgoraIO-Extensions / AgoraIO-Extensions/agent-infra

feat(platform): expose operational traces logs and metrics

Abierto
#441 3 comentarios 0 reacciones 0 asignados Ver en GitHub
needs-triage
Lenguaje dominante
TypeScript
Estrellas
0
Forks
0
Merge medio
8 h 51 min
PR fusionados (30 d)
99

Descripción

> 本票继续由 [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) 评审;实施前回读合入后的权威版本并复核差额,历史基础引用不能覆盖新增结论。

Guía de contribución

No hay ninguna guía de contribución indexada para este repositorio

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.