tracing

为代码添加 LangWatch 跟踪

确定范围

如果用户的请求比较宽泛（“为我的代码添加检测”“添加跟踪”“设置可观测性”）：

• 阅读完整代码库，了解 Agent 的架构
• 研究 Git 历史，了解发生了哪些更改以及原因：重点关注 Agent 行为变更、提示词调整和 Bug 修复。阅读提交消息以了解背景。
• 为所有大模型调用位置添加全面的跟踪

如果用户的请求比较具体（“为支付函数添加跟踪”“跟踪此端点”）：

• 聚焦于指定函数或模块
• 仅在用户要求的位置添加跟踪
• 验证检测在上下文中能正常工作

此技能仅涉及代码：没有通过平台进行跟踪的方式。如果用户没有代码库，请说明跟踪需要通过代码检测来实现。

在 Langy 中，不要打印更改内容让用户手动应用：调用 code_access，并遵循 code-changes 技能，在用户的机器上或通过 GitHub 进行更改。

第 1 步：阅读集成文档

使用 langwatch docs <path> 以 Markdown 格式阅读文档。以下是一些实用的入口：

langwatch docs                                    # Docs index
langwatch docs integration/python/guide           # Python integration
langwatch docs integration/typescript/guide       # TypeScript integration
langwatch docs prompt-management/cli              # Prompts CLI
langwatch scenario-docs                           # Scenario docs index

使用 langwatch --help 和 langwatch <subcommand> --help 查找命令。列表和获取命令支持通过 --format json 输出机器可读结果。每个列表命令都支持 --limit <n> 限制行数，并通过 --jq <expr> 读取部分结果。分页列表会以封装对象的形式返回，因此应通过行数组统计结果数量（--jq '.traces | length'），并在 .pagination.total 读取总数。单独使用 --jq length 统计的是封装对象的字段数，而非行数。请先阅读文档，不要猜测 SDK API 或 CLI 标志。

如果无法使用 shell，可通过普通 HTTP 获取相同的 Markdown 文档。在任意文档路径后追加 .md（例如 https://langwatch.ai/docs/integration/python/guide.md）。索引：https://langwatch.ai/docs/llms.txt。场景索引：https://langwatch.ai/scenario/llms.txt

如果遵循此技能时遇到任何故障或困惑（命令损坏、文档与实际情况不符、需要绕过的错误），请征求用户许可，然后运行 npx --yes langwatch report --user-approved，并附上 --title 和 --summary（或 --session <transcript.jsonl>），将问题报告给 LangWatch 团队，这些反馈会直接影响后续修复。无需登录或 API 密钥。只有使用 --user-approved 才会发送内容；--dry-run 会打印确切的负载，但不会发送。标题、摘要和会话记录会先在本地按模式进行脱敏处理：密钥和 API 密钥，以及电子邮件地址、电话号码、银行卡号和公共 IPv4 地址。任何未匹配到模式的内容都会原样发送，包括通过 --email 传入的联系地址。使用 --session 时，务必先运行 --dry-run，并让用户查看负载，因为会话记录中可能包含用户未查看过的内容。npx --yes langwatch report --help 会说明可用选项。

项目和 API 密钥：目标必须是真实项目，而非个人项目。

LangWatch 有两种项目：

• 团队／共享项目：组织内的真实项目。评估、实验、提示词、数据集、模拟和检测必须始终以其中一个项目为目标。
• 个人项目：与单个用户关联的私有“My Workspace”临时空间。绝不要将用户的评估、实验或生产跟踪数据发送到这里：它仅供个人探索使用，容易被误认为是真实项目。

身份验证方式也有两种：

• .env 中的项目 API 密钥（LANGWATCH_API_KEY）：此技能中所有操作使用的凭据。它的权限仅限于一个真实项目。这是默认方式；除非用户明确要求其他方式，否则应优先使用。
• langwatch login --device（AI 工具／SSO）：用于包装编码助手（langwatch claude、langwatch codex 等）的个人设备会话。它不适用于评估、提示词、数据集、场景或 SDK 检测，并且会指向个人工作区。不要为了设置此技能中的工作而运行此命令。 因此，对于这些技能中任何会读取或写入项目的操作：请确保 CLI 能获取真实共享项目的 LANGWATCH_API_KEY。在本地，该变量位于项目的 .env 文件中；在 CI 中，运行器会将其注入进程环境，CLI 两处都能读取。索取新密钥前，先检查该变量是否已设置，并让 CLI 读取其值：绝不要打印、复制或发送它。不要运行 langwatch login 来选择项目，也绝不要默认使用个人项目。在相同位置查找 LANGWATCH_ENDPOINT：如果已设置，说明该项目位于可自托管实例上，CLI 会使用该端点，而非 app.langwatch.ai。

你读取的内容，不等于你要说的内容。 这些技能是供你参考的工作笔记，不是给读者看的文案。从项目自己的 .env 中读取 LANGWATCH_API_KEY 和 LANGWATCH_ENDPOINT，以此确定工作位置。不要从该文件读取其他内容：其中包含数据库、云服务和提供商凭据，这些都与你无关，而且你读取的每个值都可能进入你的上下文和命令输出。回答中不得出现任何描述你运行环境的信息：工作区路径、容器端口、此工作进程连接的地址。这些只说明工作是如何完成的，而不是完成了什么；我们的主机信息对读者毫无意义。请说明你做了什么，以及可以在 LangWatch 的哪里找到结果。

然后，获取适用于此项目框架的集成指南：

langwatch docs integration/python/guide                      # Python (general)
langwatch docs integration/typescript/guide                  # TypeScript (general)
langwatch docs integration/python/integrations/open-ai       # Framework page
langwatch docs integration/typescript/integrations/mastra    # Framework page

框架页面的路径格式是 integration/<language>/integrations/<framework>，绝不是 integration/<language>/<framework>。框架 slug 使用供应商名称，词与词之间以连字符分隔：open-ai、open-ai-agents、open-ai-azure、aws-bedrock、google-ai、vertex-ai、lite-llm、crew-ai、pydantic-ai、strand-agents、vercel-ai-sdk，以及单词形式的名称（langchain、langgraph、agno、anthropic、mastra、haystack、llamaindex、instructor、dspy、autogen、smolagents、semantic-kernel、promptflow、azure-ai）。

不确定时，运行不带路径的 langwatch docs：它会打印所有页面的索引。docs 会以 Markdown 格式打印页面，不接受 --output、--json、--jq 或 --format；如果获取页面时返回 404，说明路径有误，应查看索引，而不是猜测其他拼写。

至关重要：不要猜测如何进行埋点。不同框架的埋点方式各不相同；务必先阅读对应框架的专属指南。

步骤 2：安装 LangWatch SDK

对于 Python，按以下梯级尝试，遇到第一个可行选项就停止；选择的包管理器以工作区信息为准。若信息中提到 uv、文件夹中有 uv.lock，或 .venv/pyvenv.cfg 中有 uv = 行，则使用 uv add langwatch（uv 创建的虚拟环境中没有 pip）；否则，如果存在 .venv，则使用 .venv/bin/python -m pip install langwatch；最后才尝试 pip install langwatch、pip3 install langwatch、python3 -m pip install langwatch、python -m pip install langwatch。如果命令未找到（退出码 127），就进入下一个梯级，绝不重试：这只是命令名称不存在，并不表示缺少相应能力。若所有梯级都不可用，请在放弃前询问：“请帮我安装 uv”或“我会自行配置 Python”。 对于 TypeScript：如果没有锁文件指定其他包管理器，则使用 npm install langwatch；如果锁文件指定了其他包管理器，则使用 pnpm add langwatch、yarn add langwatch 或 bun add langwatch；指定的包管理器返回 127 时，改用 npm。 uv add 和 JavaScript 包管理器会自行写入清单文件。pip 安装不会写入任何文件，因此请自行将软件包添加到项目自己的 requirements 文件中（requirements.txt，或文件夹使用的文件，例如 requirements/base.txt）：运行 python -m pip show langwatch 可查看版本，然后添加 langwatch==<installed version> 这一行，按文件中其他软件包的方式锁定版本；如果文件中的软件包都未锁定版本，则也不锁定。 编写任何代码之前，请通过安装该软件包的解释器检查安装是否包含相应 API：Python 使用 python -c "import langwatch; langwatch.setup; langwatch.connect_agent"，TypeScript 使用 node -e "require('langwatch')"。低于 1.3.0 的 Python 版本没有这两个 API；如果解释器版本比 SDK 支持的版本更新，pip 安装时不会给出任何提示：包含这些 API 的每个版本都会声明 Python 版本上限，而 pip 会退回到最后一个没有这些 API 的版本。在这种情况下，pip install langwatch --upgrade 无济于事。检查失败意味着需要先询问解释器相关问题，再考虑放弃：“请帮我通过 uv 安装 Python 3.13”或“我会自行选择解释器”。

如果安装因对等依赖冲突而失败，请放宽冲突范围并重试。切勿默默跳过。

第 3 步：添加埋点

按照你在第 1 步阅读的集成指南操作。基本形式如下：

Python：

import langwatch
langwatch.setup()

@langwatch.trace()
def my_function():
    ...

TypeScript：

import { LangWatch } from "langwatch";
const langwatch = new LangWatch();

具体模式取决于框架，因此请遵循文档，而不是这些示例。

图会在图级别接收回调，而不是在图内的模型调用处接收。 LangChain 会从回调附加的位置向下传递回调，因此在 LangGraph 中，回调应放在图调用的配置中：

graph.invoke(state, config={"callbacks": [langwatch.get_current_trace().get_langchain_callback()]})

ainvoke 和 stream 也使用相同的配置参数。运行所触及的每个节点都会成为跟踪下的一个跨度：以节点命名的链跨度、模型调用对应的 LLM 跨度，以及工具调用对应的工具跨度。如果只将回调附加到某个节点内的模型调用，跟踪中就只有 LLM 跨度，其他内容都没有，因此工具节点和普通函数节点都会缺失；检查图是否执行到支付步骤时，也没有可读取的跨度。

环境变量会在 LangWatch 初始化之前加载。 langwatch.setup() 和 new LangWatch() 会在运行时立即从进程环境中读取 LANGWATCH_API_KEY，而 .env 文件在被加载之前并不属于环境变量。一次录制的运行将 langwatch.setup() 放在入口文件顶部，位于调用 load_dotenv() 的导入语句之前，导致进程在导入时因错误 "LangWatch API key is required but not provided" 而退出。

• Python：找到加载环境变量的位置（来自 python-dotenv 的 load_dotenv()、设置模块或配置加载器），并将 langwatch.setup() 放在所有会执行环境变量加载的导入语句之后，绝不要放在入口文件顶部。如果项目依赖 python-dotenv，但入口文件没有加载它，请在经过埋点的入口文件顶部添加 from dotenv import load_dotenv 和 load_dotenv()，放在 import langwatch 之前。
• TypeScript：如果项目使用 dotenv，请将 import "dotenv/config" 作为入口文件的第一条导入语句，放在 langwatch 导入之前；SDK 会在构造时读取密钥。

启动进程之前，请按照项目读取密钥的方式，检查进程是否能看到该密钥。这是第一次也是唯一一次检查：按原样复制对应语言的命令，从项目根目录运行一次，并查看结果。之前不要使用任何变体（例如不带加载器执行 import langwatch 的探测命令会读取原始进程环境，在 dotenv 项目中总是显示缺失），之后也不要再检查。

uv run python -c "from dotenv import load_dotenv; load_dotenv(); import os; print(bool(os.getenv('LANGWATCH_API_KEY')))"

uv run 是项目使用的运行器；如果项目使用 Poetry，则用 poetry run python -c，如果使用 .venv，则用 .venv/bin/python -c。始终使用 -c，绝不要用带 heredoc 的 python -：python-dotenv 的加载器会查找调用者的文件，而标准输入无法满足这一要求。TypeScript：

node -e "require('dotenv').config(); console.log(Boolean(process.env.LANGWATCH_API_KEY))"

该命令只会打印 LANGWATCH_API_KEY 是否已设置，绝不会打印其值。如果项目使用的不是 dotenv，请将加载器替换为项目自己的加载器。False 表示文件不在加载器查找的位置，或上述顺序有误：修正这些问题，绝不要改用其他路径重试检查。

步骤 4：验证

验证完成后才能认为工作已完成。请按顺序执行：

1. 确认依赖已成功安装。
2. 使用能生成至少一条追踪记录的测试输入运行 Agent（了解框架的启动方式；只有在需要你无法启动的基础设施时才放弃）。
3. 检查追踪记录是否已到达：langwatch trace search --limit 5 --format json。运行结束时，追踪记录还不能立即搜索到：导出数据会先离开进程，之后还需要几秒才能完成摄取，因此首次查询结果为空表示“还没到”，而不是“无法工作”。等待约 20 秒后再次查询，最多查询 3 次，到此为止。不要更改命令：搜索范围已涵盖过去 24 小时，有追踪记录就是有。
4. 说明等待结束时的结果。找到追踪记录：说明运行产生了什么。第三次查询后仍未找到：说明已完成埋点，追踪记录尚未到达，并指出要查看的项目；不要声称更改已通过验证。
5. 如果无法验证（没有 Shell 访问权限、无法运行代码、缺少外部服务），请明确告知用户应在 LangWatch 控制面板中检查什么，以及你无法验证的内容和原因。

此步骤只能证明追踪记录已到达。之后要查找特定追踪记录（某位用户、错误、点踩反馈），请使用 find-traces 技能。

常见错误

• 不要臆造埋点模式。请阅读框架专属文档
• 不要在 Python 中跳过 langwatch.setup()
• 不要在加载环境的导入语句之前调用 langwatch.setup()：密钥会在运行 setup() 时读取
• 不要只在图节点内部的模型调用上附加 LangChain 回调：应将其附加到图调用上，否则节点不会成为 Span
• 不要跳过步骤 1；OpenAI、LangGraph、Vercel、Mastra 和 Agno 的埋点模式各不相同，靠猜测可能会导致难以察觉的问题