AgentOps 计算字段迁移指南从 v2 Meters 到基于 ClickHouse OpenTelemetry 数据的 v4 指标体系【免费下载链接】agentopsPython SDK for AI agent monitoring, LLM cost tracking, benchmarking, and more. Integrates with most LLMs and agent frameworks including CrewAI, Agno, OpenAI Agents SDK, Langchain, Autogen, AG2, and CamelAI项目地址: https://gitcode.com/GitHub_Trending/ag/agentops在 AgentOps 后端v2 API 的会话统计LLM 调用次数、Token 用量、成本、成功率等是由 meters 在 Supabase 侧预计算并写入stats表的而 v4 API 的数据底座已经切换为 ClickHouse 中的 OpenTelemetry 数据。本篇围绕仓库中 迁移任务说明 展开完整介绍如何把 v2 的全部计算字段迁移到 v4哪些字段需要迁移、每个字段如何映射到 OTel 概念、如何用物化视图与 UDF 预聚合、如何缓存与保证向后兼容以及测试策略。读完后你可以独立评估或实施该迁移并理解当前仓库中 ClickHouse 迁移脚本与 v4 metrics 视图已经落地的部分。一、迁移背景与总体策略v2 时代SDK 上报事件后由服务端 meters 逻辑逐条累加把cost、Token 数等写进 Supabase 的stats表——例如 v2 的 update_session 接口 在更新会话后就是从stats表读出cost字段作为token_cost返回给调用方。这意味着统计口径强依赖事件到达即计算的时序模型。v4 则把原始遥测数据spans、events、resource attributes完整落入 ClickHouse统计字段需要在查询侧从 OpenTelemetry 数据现场计算。迁移任务文档 给出的五项要求是识别 v2 端点中的全部计算字段设计从 OpenTelemetry 数据计算这些字段的策略实现计算逻辑保证与现有客户端的向后兼容优化查询性能。文档同时建议在agentops/api/utils/computed_fields.py中集中放置各字段的计算函数统一使用 span attributes 与 span events 提取数据。该路径是任务规划中的实现位置阅读时可将其视为计算逻辑单一入口的设计意图。二、需要迁移的计算字段清单迁移文档列出了六类必须覆盖的计算字段这也是向后兼容性的验收基线计算字段v2 语义v4 计算目标LLM 调用count、tokens、cost从 LLM 类型 span 聚合工具调用count、types从工具类型 span 聚合会话时长由会话起止时间戳得出由 trace 内 span 时间戳得出会话成本stats.costmeters 累加LLM span 成本求和会话统计成功率、错误率由 span 状态码与属性推导Agent 性能指标各 agent 维度聚合从 span 维度推导任何 v4 端点在返回这些字段时数值口径都应能与 v2 时代客户端SDK 回传展示、dashboard 面板对齐这是任务文档确保向后兼容一条的实质含义。三、v2 字段到 OpenTelemetry 概念的映射文档给出的映射规则是整套计算逻辑的核心逐条对应到 OTel 数据模型LLM 调用span.kindclient且带有ai.model.name属性的 span。即 LLM 请求在 OTel 语义中是一个客户端调用模型名作为 span 属性落库工具调用span.kindclient且带有特定工具类属性的 span。工具调用与 LLM 调用同为客户端 span靠属性区分会话时长同一 trace 内第一个 span 与最后一个 span 的时间戳之差。v4 中一个会话/运行对应一条 trace时长不再是显式上报的字段而是从 span 时间范围推导会话成本对所有 LLM 调用 span 的成本求和。单项成本由 token 用量乘以模型单价得出见下一节的 UDF 实现会话统计成功率/错误率由 span 的状态码Status与相关属性推导即错误 span 数 / 总 span 数一类的比值。这条映射表的工程价值在于它把业务统计概念锚定到了 OTel 的span kind attributes status三要素上后续所有 SQL 与 Python 计算逻辑都有统一的取数口径。SDK 侧的属性命名常量可以结合 semconv 定义 与 span kind 定义 核对保证上报侧与查询侧属性名一致。四、成本计算的落地ClickHouse 字典 UDF会话成本 LLM span 成本之和依赖单项成本计算而单项成本 prompt tokens 单价 completion tokens 单价。当前仓库在 UDF 与定价迁移脚本 中已实现这一层模型价格表otel_2.model_costs_source表存放model、prompt_cost_per_1k、completion_cost_per_1k三列并由 完整价格种子脚本 灌数字典加速基于该表创建model_costs_dict字典COMPLEX_KEY_HASHED布局使每行成本计算走 O(1) 字典查找而非关联表模型名归一化normalize_model_name函数处理裸模型名如sonar-pro归一为perplexity/sonar-pro避免上报侧命名不一致导致查价落空成本 UDFcalculate_prompt_cost / calculate_completion_cost 在 SQL 内完成tokens / 1000 * 单价并保留 7 位小数未命中模型时dictGetOrDefault回退为 0。对迁移的直接意义是计算 LLM 调用的 cost 字段时无需在 Python 层维护价格表ClickHouse 查询内即可展开求和Python 侧的computed_fields逻辑保持薄只做字段组装。五、查询优化物化视图、缓存与高效查询模式任务文档的Query Optimization一节给出三条策略仓库中均有对应证据5.1 物化视图预聚合mv_trace_span_counts 是已落地的示例物化视图otel_2.mv_trace_span_counts从otel_2.otel_traces按(project_id, TraceId)分组用countState()把 span 数写入AggregatingMergeTree目标表otel_2.trace_span_counts。查询时用countMerge()类终态函数即可得到每条 trace 的 span 数这一高频聚合而无需每次全表扫描。这一模式可以直接套用到迁移文档要求的其他预聚合上——例如按 trace 预聚合 prompt/completion tokens、按 trace 预聚合成本借助第五节的 UDF把 v2 meters 增量累加的效果转化为 v4 物化视图增量预聚合这正是文档所说在 ClickHouse 中创建物化视图预计算常见聚合的具体形态。5.2 API 层缓存v4 的 ProjectMetricsView 内置了MetricsCache缓存键为project_id | start_time | end_time的 MD5 摘要key 构造逻辑时间参数先归一化再入键避免等价参数产生不同键默认 TTL 300 秒5 分钟过期即删容量保护超过 1000 个条目时淘汰最老的 100 条防止无界增长。计算字段接口复用这种项目 时间窗口的键控缓存即可满足文档对高频访问数据实现缓存的要求且与 v4 metrics 端点的现有缓存语义一致。5.3 最小化数据传输的查询模式文档要求使用高效查询模式最小化数据传输。结合仓库现状可以归纳为先在 ClickHouse 内完成过滤与聚合ResourceAttributes[agentops.project.id]作为项目隔离条件、按 trace 聚合后只返回每 trace 一行把明细留在库内API 层只接收聚合结果。v4 metrics 视图 中按项目 时间范围取数并组装SpanCount、TotalTokens、AverageTokens、DurationMetrics等响应模型的做法就是这种库内聚合、窄结果集返回模式的现行实现。六、向后兼容策略任务文档把确保与现有客户端的向后兼容列为独立要求。从仓库结构看兼容主要体现在两个层面字段口径兼容v2 客户端从/v2/update_session等端点拿到的token_cost、会话统计字段在 v4 等价端点上必须以相同语义美元成本、成功率/错误率返回而不是换名换型。v2 路由文件 routes/v2.py 保留了完整的旧接口行为可作为字段对照基准路由级兼容v4 内部已存在双路由先例——/metrics 与 /meterics 双端点 测试验证两条路径返回相同响应该测试因上游 issue 820 被标记 skip但其断言了两路径状态码一致、响应体一致这一兼容性验收标准。迁移新端点时可沿用同样的新旧路径并存 一致性测试手法。此外v4 路由包 中responses.py响应模型与views.py处理逻辑分离的结构使新增计算字段时只扩展响应模型与视图不破坏既有端点签名。七、测试策略文档给出的测试要求及仓库中可对应的落点计算逻辑单元测试对各字段函数用构造的 span 数据断言输出。参考 v4 测试 的写法——直接构造带gen_ai.usage.prompt_tokens、gen_ai.usage.completion_tokens、gen_ai.request.model、agentops.project.id等属性的 span 字典来模拟 ClickHouse 返回行无需真实数据库即可单测聚合逻辑ClickHouse 真实数据测试端到端验证物化视图与 UDF 联调后的成本、span 计数正确性大数据量性能测试验证物化视图预聚合后查询在大量 trace 下的耗时与内存占用向后兼容测试对比同一数据集下 v2 口径字段与 v4 计算结果的数值一致性并对双路由端点做响应相等断言。八、小结迁移的三层落地结构综合任务文档与仓库现状这次迁移在实现上收敛为三层存储层ClickHouse以 otel_traces 表 为数据源价格字典 成本 UDF 解决单价计算物化视图 解决高频预聚合API 层v4 路由按 迁移文档 规划把字段计算集中到computed_fields模块v4 metrics 视图 的键控 TTL 缓存与窄结果集查询模式直接复用兼容与测试层以 v2 路由为字段口径基准以 v4 测试目录 为单测与双路由一致性测试的落点覆盖真实数据、大数据量与兼容回归三类场景。按文档估算完整实施约需 12–16 小时工作量依赖项是 ClickHouse 客户端实现与 trace/logs/metrics 端点的先行落地。对阅读者而言最关键的判断标准始终是第三节那张映射表只要 v4 的每个字段都能回答它由哪一类 span 的哪个属性聚合而来迁移就处于可控状态。【免费下载链接】agentopsPython SDK for AI agent monitoring, LLM cost tracking, benchmarking, and more. Integrates with most LLMs and agent frameworks including CrewAI, Agno, OpenAI Agents SDK, Langchain, Autogen, AG2, and CamelAI项目地址: https://gitcode.com/GitHub_Trending/ag/agentops创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考