---

📚 目录

• ✨ 功能
• 🚀 快速入门
• 🔗 集成
• 🌐 入门指南
• 🏠 自托管
• 📐 架构
• 🤝 贡献
• 🔒 安全
• ❓ 常见问题
• 👥 贡献者
• 📜 许可证

Langtrace 是一款开源可观测性软件，可帮助您捕获、调试并分析来自所有使用 LLM API、向量数据库和基于 LLM 的框架的应用程序的跟踪数据和指标。

✨ 功能

• 📊 Open Telemetry 支持：基于 OTEL 标准构建，提供全面的追踪功能
• 🔄 实时监控：跟踪 LLM API 调用、向量操作及框架使用情况
• 🎯 性能洞察：分析延迟、成本和使用模式
• 🔍 调试工具：追踪并调试您的 LLM 应用工作流
• 📈 分析功能：获取详细的指标和可视化图表
• 🏠 自托管选项：可在您自己的基础设施上部署

🚀 快速入门

# 对于 TypeScript/JavaScript
npm i @langtrase/typescript-sdk

# 对于 Python
pip install langtrace-python-sdk

在代码中初始化：

// TypeScript
import * as Langtrace from '@langtrase/typescript-sdk'
Langtrace.init({ api_key: '<your_api_key>' }) // 在 langtrace.ai 获取您的 API 密钥

# Python
from langtrace_python_sdk import langtrace
langtrace.init(api_key='<your_api_key>') # 在 langtrace.ai 获取您的 API 密钥

有关详细设置说明，请参阅 入门指南。

📊 Open Telemetry 支持

Langtrace 生成的跟踪数据遵循 Open Telemetry 标准(OTEL)。我们正在为本项目生成的跟踪数据开发 语义约定。您可以在 此仓库 中查看当前定义。请注意：这是一项持续进行中的工作，我们鼓励您参与其中，并欢迎您的反馈。

---

📦 SDK 仓库

• Langtrace TypeScript SDK
• Langtrace Python SDK
• 语义跨度属性

---

🚀 入门指南

Langtrace 云服务 ☁️

要使用 Langtrace 的托管 SaaS 版本，请按照以下步骤操作：

1. 访问 此链接 进行注册。
2. 注册后创建一个新项目。项目是用于存储应用程序生成的跟踪数据和指标的容器。如果您只有一个应用程序，只需创建一个项目即可。
3. 进入项目页面生成 API 密钥。
4. 在您的应用程序中安装 Langtrace SDK，并使用第 3 步生成的 API 密钥进行初始化。
5. 安装和设置 SDK 的代码如下所示：

如果您的应用程序使用 TypeScript/JavaScript 构建

npm i @langtrase/typescript-sdk

import * as Langtrace from '@langtrase/typescript-sdk' // 必须在任何 LLM 模块导入之前执行
Langtrace.init({ api_key: <your_api_key> })

或者

import * as Langtrace from "@langtrase/typescript-sdk"; // 必须在任何 LLM 模块导入之前执行
LangTrace.init(); // 将 LANGTRACE_API_KEY 设置为环境变量

如果您的应用程序使用 Python 构建

pip install langtrace-python-sdk

from langtrace_python_sdk import langtrace
langtrace.init(api_key=<your_api_key>)

或者

from langtrace_python_sdk import langtrace
langtrace.init() # 将 LANGTRACE_API_KEY 设置为环境变量

🏠 Langtrace 自托管

要在本地运行 Langtrace，您需要运行三个服务：

• Next.js 应用程序
• Postgres 数据库
• ClickHouse 数据库

[!重要提示] 请查阅我们的 文档，了解各种部署选项和配置。

所需条件：

• Docker
• Docker Compose

.env 文件

您可以根据需要自由修改 .env 文件。

启动服务器

docker compose up

应用程序将可在 http://localhost:3000 访问。

关闭部署

要删除容器和卷：

docker compose down -v

-v 标志用于删除卷。

遥测

如果您自托管 OSS 客户端，Langtrace 不会收集任何遥测数据。您的任何数据都不会离开您的服务器。

---

🔗 支持的集成

Langtrace 会自动捕获来自以下供应商和框架的跟踪数据：

LLM 提供商

提供商	TypeScript SDK	Python SDK
OpenAI	✅	✅
Anthropic	✅	✅
Azure OpenAI	✅	✅
Cohere	✅	✅
DeepSeek	✅	✅
xAI	✅	✅
Groq	✅	✅
Perplexity	✅	✅
Gemini	✅	✅
AWS Bedrock	✅	✅
Mistral	❌	✅

大语言模型框架

框架	TypeScript SDK	Python SDK
Langchain	❌	✅
LlamaIndex	✅	✅
Langgraph	❌	✅
LiteLLM	❌	✅
DSPy	❌	✅
CrewAI	❌	✅
Ollama	❌	✅
VertexAI	✅	✅
Vercel AI	✅	❌
GuardrailsAI	❌	✅
Arch	❌	✅
Graphlit	❌	✅
Agno	❌	✅
Phidata	❌	✅
Cleanlab	❌	✅

向量数据库

数据库	TypeScript SDK	Python SDK
Pinecone	✅	✅
ChromaDB	✅	✅
QDrant	✅	✅
Weaviate	✅	✅
PGVector	✅	✅（使用 SQLAlchemy）
MongoDB	❌	✅
Milvus	❌	✅

---

📐 Langtrace 系统架构

---

💡 功能请求与问题反馈

• 如需请求新功能，请前往 此处发起讨论。
• 如遇到问题或需要报告错误，请前往 此处创建议题。

---

🤝 贡献方式

我们欢迎各位开发者为本项目贡献力量。如想参与开发，可先 fork 本仓库并开始工作。更多参与方式，请加入我们的 Slack 工作空间。

---

🌟 Langtrace 星标历史

---

🔒 安全性

如发现安全漏洞，请发送邮件至 security@scale3labs.com 报告。有关安全性的更多信息，请参阅 此处。

---

📜 许可证

• Langtrace 应用程序（本仓库）采用 AGPL 3.0 许可证授权。您可在此处了解该许可证的详情：AGPL 3.0 许可证。
• Langtrace 的 SDK 则采用 Apache 2.0 许可证授权。您可在此处了解该许可证的详情：Apache 2.0 许可证。

👥 贡献者

---

❓常见问题解答

1. 我能否在自己的云环境中自托管并运行 Langtrace？

可以，完全可以。请按照我们文档中的自托管部署说明进行操作：文档链接。

2. Langtrace 云端服务的定价如何？

目前，Langtrace 云端服务仍处于免费阶段，我们主要希望收集用户反馈以持续改进产品。待我们决定开启商业化时，会及时通知用户。

3. Langtrace 使用的技术栈是什么？

Langtrace 前端和 API 层采用 Next.js 构建，元数据存储使用 Postgres 数据库，而 Span、指标、日志和追踪数据则存储在 ClickHouse 数据库中。

4. 我可以为这个项目做出贡献吗？

当然可以！我们非常欢迎开发者参与贡献。您可以通过加入我们的 Discord 社区尽早参与进来。

5. 参与该项目需要具备哪些技能？

编程语言：TypeScript 和 Python。
框架知识：Next.js。
数据库：Postgres 和 Prisma ORM。
加分项：OpenTelemetry 监测框架经验，以及分布式追踪相关经验。

Langtrace 快速上手指南

Langtrace 是一款开源的 LLM 应用可观测性工具，支持捕获、调试和分析来自 LLM API、向量数据库及各类框架的追踪数据与指标。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows
• 运行时环境（二选一）：
  • Node.js (推荐 v18+) 用于 TypeScript/JavaScript 项目
  • Python (推荐 v3.8+) 用于 Python 项目
• 账号准备：访问 langtrace.ai 注册账号并创建项目，获取 API_KEY。
  • 注：若选择自托管模式，需额外安装 Docker 和 Docker Compose。

安装步骤

根据您的项目语言选择对应的 SDK 进行安装。

TypeScript / JavaScript 项目

npm i @langtrase/typescript-sdk

Python 项目

pip install langtrace-python-sdk

提示：国内用户若下载缓慢，可配置国内镜像源加速：

• npm: npm config set registry https://registry.npmmirror.com
• pip: pip install -i https://pypi.tuna.tsinghua.edu.cn/simple langtrace-python-sdk

基本使用

安装完成后，需在代码中初始化 SDK。请务必将初始化代码置于任何 LLM 模块导入之前。

方式一：直接在代码中传入 API Key

TypeScript 示例：

import * as Langtrace from '@langtrase/typescript-sdk' // 必须位于任何 llm 模块导入之前
Langtrace.init({ api_key: '<your_api_key>' }) 

Python 示例：

from langtrace_python_sdk import langtrace
langtrace.init(api_key='<your_api_key>') 

方式二：使用环境变量（推荐）

将 API Key 设置为环境变量 LANGTRACE_API_KEY，然后调用无参初始化方法。

TypeScript 示例：

import * as Langtrace from "@langtrase/typescript-sdk"; 
LangTrace.init(); 

Python 示例：

from langtrace_python_sdk import langtrace
langtrace.init() 

初始化成功后，Langtrace 将自动捕获支持的 LLM 提供商（如 OpenAI, Anthropic 等）、框架（如 Langchain, LlamaIndex 等）及向量数据库的操作追踪数据，您可以在 Langtrace 控制台实时查看分析结果。