# HeronSentry (Observability Platform)

## 概述

独立可用的 AI Agent 观测面：追踪、成本、告警与性能分析

HeronSentry 是独立可用的 AI Agent 观测面：通过标准 OTLP 采集 Agent 运行时事件，提供调用链查询、成本聚合、告警与性能导出；不依赖套件其它产品即可单独部署。

## 能做

- 标准 OTLP 协议接收：接收 Traces / Metrics / Logs，三类信号处理深度不同
- 端到端分布式调用链：还原 Agent 思考、工具调用与模型交互拓扑
- 精细化 Token 成本核算：按缓存读写拆分，支持实时成本归因与分析
- 多维度智能告警：错误率、成本突增、积压与异常调用的实时告警
- Agent 专项可靠性指标：首字延迟（TTFT）、截断率、工具拒绝率分析
- 数据分析与审计导出：为 OwlAudit 及管理层提供指标与审计数据支撑

## 不做

- 不作为通用企业海量全文检索日志中心（专注于 Agent 运行时关联的 OTLP 结构化链路与日志）
- 不替代主机与网络级基础设施监控（专注于 Agent 应用层与大模型交互语义层观测）
- 不执行主动任务干预与阻断（仅负责只读观测与告警，拦截动作归 OwlAudit / NodalOS）

## 覆盖的痛点

- Agent 出故障只能看日志，没有调用链
- 成本到月底才知道，超支已成事实
- 看不见某个 Agent 是否健康、是否被滥用

## 能力

- **独立可用**: 零套件依赖，自带采集、PostgreSQL 存储、告警引擎与调试页
- **标准 OTLP 接入**: 接收 OTLP 遥测并内置 Claude Code 等 profile；非 Agent 框架日志不入库，指标不参与告警
- **调用链追踪**: 同一条 OTel Trace 内按父子与 link 还原调用链，并以 Mermaid 呈现
- **成本聚合**: 按缓存读、缓存写拆分计费，并展示推理 Token。推理 Token 消耗实时呈现，不计入额外计费项
- **Agent 可靠性指标**: 流式首字延迟（TTFT）与截断率（输出触达长度上限）；工具拒绝率、对话轮次仅在源端上报对应字段时可用
- **告警**: Agent 运行异常时生成告警，在 AULO 告警页查看；通知发给该 Agent 所在实例或项目的负责人
- **业务域告警**: 可选，默认关闭；开启后可识别进行中任务卡住与连续评审打回；不是任务阻塞链、跨组停滞或预算燃烧告警
- **策略评估可用性告警**: 区分 NodalOS 策略评估器不可达与本地策略回退，与安全拦截不是同一类事件
- **OTLP 接入限流**: OTLP HTTP 与 gRPC 可共用限流桶；默认关闭，原生通道独立计桶
- **拓扑可视化**: 单条调用链以 Mermaid 拓扑呈现
- **性能与成本分析**: 成本可按 Agent / Program 聚合，可靠性指标在 Agent 汇总中提供

## 集成

- NodalOS OTLP 推送（需在 NodalOS 侧开启自身遥测上报）
- AULO 告警页
- PathPilot 成本回写与运行健康（错误率 / P95 / 超时）
- OwlAudit 可拉取 traces / 成本 / 告警导出

## 指标

- OTLP — 开放协议；语义字段按 profile 映射
- 全量 — 默认不采样
- 实时同步入库 — 请求内完成持久化
- 独立 — 零套件依赖即可部署

## 依据 / 参考

- 产品页：/products/heronsentry
