openllmetry-js

图1：OpenLLMetry 浅色主题 Logo

你正在为公司的大模型应用调试问题。用户反馈说 AI 回答质量下降，但日志里只看到一串 token 数字，看不出模型到底在想什么。这时候，OpenLLMetry-JS 就能派上用场——它把 LLM 调用过程中的每个细节都记录下来，像给 AI 应用装上了一台 X 光机。

背景：LLM 应用急需「可观测性」

随着 GPT-4、Claude、DeepSeek 等大模型在生产环境大规模部署，AI 应用开发者面临一个独特困境：传统 APM 工具（如 Datadog、New Relic）能监控 HTTP 请求和数据库查询，却无法理解 LLM 调用中发生了什么。prompt 传了什么？token 消耗多少？向量检索返回了哪些结果？这些信息对调试 AI 应用至关重要，但传统监控手段完全捕捉不到。

OpenLLMetry-JS 应运而生。它由 Traceloop 公司开发和维护，Y Combinator 孵化支持，基于云原生可观测性标准 OpenTelemetry 构建，核心理念是「不绑架用户生态」——数据可以导出到 Datadog、Honeycomb、Grafana Tempo 等任何兼容 OpenTelemetry Collector 的后端，避免厂商锁定。

更值得注意的是，OpenLLMetry-JS 团队制定的 AI 语义约定（AI Semantic Conventions） 已于 2024 年正式被 OpenTelemetry 官方采纳，成为 LLM 可观测性领域的行业标准。这是开源项目影响行业规范的典型案例。

架构：Monorepo 插件化设计

OpenLLMetry-JS 采用 Monorepo 结构，使用 Nx + Lerna 管理多包项目，主包名为 @traceloop/node-server-sdk，仓库包含 16 个独立包：

这种架构让用户可以按需引入：如果只用 OpenAI，就装 @traceloop/instrumentation-openai；如果需要全链路追踪，直接装 @traceloop/node-server-sdk 一键开启所有支持项。

技术栈方面，核心代码是 TypeScript 编写，Rollup 打包，遵循 OpenTelemetry SDK API 规范，支持 Node.js >= 18。每个 instrumentation 包都是独立的 npm 包，发布到 npm registry，安装即用，无需额外部署服务。

核心功能：从 Prompt 到响应的全链路追踪

使用方式极度简洁，只需两行代码：

import * as traceloop from "@traceloop/node-server-sdk";
traceloop.initialize();

之后所有 LLM 调用会自动生成 trace spans，包含：

• 输入信息：完整的 prompt 内容、模型名称、temperature/top_p 参数
• Token 消耗：输入 token 数、输出 token 数、总 token 数、估算费用
• 向量检索：检索 query、返回的 top-k chunks、相似度分数
• 响应内容：LLM 原始回复、finish reason、响应耗时
• 框架上下文：LangChain 的 chain 名称/LlamaIndex 的 query engine 等元信息

导出的数据格式完全符合 OpenTelemetry 规范，可接入任意兼容后端：

行业意义与局限

OpenLLMetry-JS 代表了 LLM 应用开发工具链的专业化方向。随着 AI 应用复杂度提升，从「能用」到「可控」的转变是必然趋势，可观测性是可控的基础设施之一。

不过，也有一些局限需要注意：

1. 数据隐私风险：所有 trace 数据默认发送到配置的 exporter，企业内部部署场景需确保 exporter 在内网
2. 性能开销：插桩本身会引入少量延迟，高频调用场景需要评估影响
3. 无 Web UI：SDK 不提供界面，需要配合第三方可观测平台使用
4. 覆盖不完整：Weaviate、Milvus 等向量数据库仍在开发中

快速上手

# 安装 SDK
npm install --save @traceloop/node-server-sdk

# 在入口文件顶部引入（任何 LLM 模块之前）
import * as traceloop from "@traceloop/node-server-sdk";
traceloop.initialize();

配置 exporter 时，只需参考官方文档对目标平台的操作指南，通常只需设置 1-2 个环境变量即可。

图2：OpenLLMetry 深色主题 Logo