# openllmetry-js — OpenTelemetry for LLM Apps

> Add OpenTelemetry traces to Node.js LLM apps with OpenLLMetry JS so you can debug latency, tool calls, and RAG steps. Works with a standard OTEL backend.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

# openllmetry-js — OpenTelemetry for LLM Apps

> Add OpenTelemetry traces to Node.js LLM apps with OpenLLMetry JS so you can debug latency, tool calls, and RAG steps. Works with a standard OTEL backend.

## Quick Use

1. Install:
   ```bash
   npm install --save @traceloop/node-server-sdk
   ```
2. Run:
   ```bash
   node -e "import('@traceloop/node-server-sdk').then(()=>console.log('openllmetry-js ok')).catch(e=>{console.error(e); process.exit(1);})"
   ```
3. Verify:
   - Emit one trace for a single LLM request and confirm it appears in your OTEL backend with spans for each step.


---

## Intro

Add OpenTelemetry traces to Node.js LLM apps with OpenLLMetry JS so you can debug latency, tool calls, and RAG steps. Works with a standard OTEL backend.

- **Best for:** Node.js teams who want trace-level visibility into LLM calls and tool/RAG pipelines
- **Works with:** Node.js, OpenTelemetry collectors, tracing backends (Jaeger, OTEL-compatible vendors)
- **Setup time:** 14 minutes


### Quantitative Notes

- Setup time ~14 minutes (npm install + OTEL exporter config)
- GitHub stars + forks (verified): see Source & Thanks
- Aim for <1% overhead by sampling traces (e.g., 1/100 requests in prod)


---

## Practical Notes

Good traces answer: where time went and what failed. Model calls, retrieval, tool execution, and output parsing should each be a span. Record request IDs, model name, and high-level outcome, but avoid logging raw prompts—store hashes or redacted summaries to keep privacy and cost under control.

**Safety note:** Treat traces as sensitive: redact prompts, mask PII, and set retention limits.

### FAQ

**Q: Is this vendor-specific?**
A: No. It uses OpenTelemetry so you can export to any OTEL-compatible backend.

**Q: What should I trace first?**
A: Start with LLM latency + token usage (if available), then add spans for retrieval and tools.

**Q: How do I control cost?**
A: Use sampling, redact sensitive attributes, and keep span attributes small.

---

## Source & Thanks

> GitHub: https://github.com/traceloop/openllmetry-js
> Owner avatar: https://avatars.githubusercontent.com/u/125419530?v=4
> License (SPDX): Apache-2.0
> GitHub stars (verified via `api.github.com/repos/traceloop/openllmetry-js`): 398
> GitHub forks (verified via `api.github.com/repos/traceloop/openllmetry-js`): 68


---

<!-- ZH -->

# openllmetry-js——Node.js LLM 观测（OpenTelemetry）

> 为 Node.js 的 LLM 应用接入 OpenTelemetry tracing，定位延迟、工具调用与 RAG 步骤问题；可直接对接标准 OTEL 后端与 Collector，便于统一观测与告警。

## 快速使用

1. 安装：
   ```bash
   npm install --save @traceloop/node-server-sdk
   ```
2. 运行：
   ```bash
   node -e "import('@traceloop/node-server-sdk').then(()=>console.log('openllmetry-js ok')).catch(e=>{console.error(e); process.exit(1);})"
   ```
3. 验证：
   - Emit one trace for a single LLM request and confirm it appears in your OTEL backend with spans for each step.


---

## 简介

为 Node.js 的 LLM 应用接入 OpenTelemetry tracing，定位延迟、工具调用与 RAG 步骤问题；可直接对接标准 OTEL 后端与 Collector，便于统一观测与告警。

- **适合谁（Best for）:** Node.js 团队，希望对 LLM 调用与工具/RAG 流水线做到 trace 级可观测
- **兼容工具（Works with）:** Node.js、OpenTelemetry Collector、各类 tracing 后端（Jaeger/兼容 OTEL 的平台）
- **安装时间（Setup time）:** 14 分钟


### 量化信息

- 跑通约 14 分钟（npm 安装 + 配 OTEL exporter）
- GitHub stars + forks（已核验）：见「来源与感谢」
- 生产建议采样（例如 1/100 请求）把额外开销控制在 <1%


---

## 实战要点

好的 trace 要回答两个问题：时间花在哪、失败发生在哪。建议把模型调用、检索、工具执行、输出解析分别做成 span。记录 request_id、模型名与结果状态即可；不要直接记录原始 prompt，改用 hash 或脱敏摘要以兼顾隐私与成本。

**安全提示：** 把 trace 当敏感数据：脱敏 prompt、屏蔽 PII，并设置合理的留存策略。

### FAQ

**Q: 它绑定某家平台吗？**
A: 不绑定。基于 OpenTelemetry，可导出到任意兼容 OTEL 的后端。

**Q: 最先追什么？**
A: 先追 LLM 延迟与 token 使用（若可用），再补检索与工具调用 span。

**Q: 怎么控制成本？**
A: 用采样、脱敏敏感字段，并把 span attributes 控制得更精简。

---

## 来源与感谢

> GitHub：https://github.com/traceloop/openllmetry-js
> Owner avatar：https://avatars.githubusercontent.com/u/125419530?v=4
> 许可证（SPDX）：Apache-2.0
> GitHub stars（已通过 `api.github.com/repos/traceloop/openllmetry-js` 核验）：398
> GitHub forks（已通过 `api.github.com/repos/traceloop/openllmetry-js` 核验）：68


---
Source: https://tokrepo.com/en/workflows/openllmetry-js-opentelemetry-for-llm-apps
Author: Agent Toolkit