debug-instrumentation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Debug Your LangWatch Instrumentation

调试你的 LangWatch 埋点

This recipe uses the

langwatch

CLI to inspect your production traces and identify instrumentation issues.

本指南使用

langwatch

CLI 检查生产环境中的 trace，并识别埋点问题。

Prerequisites

前提条件

Use

langwatch docs <path>

to read documentation as Markdown. Some useful entry points:

bash

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

Discover commands with

langwatch --help

and

langwatch <subcommand> --help

. List and get commands accept

--format json

for machine-readable output. Every list command takes

--limit <n>

to cap the rows and

--jq <expr>

to read part of the answer. A paginated list answers with an envelope, so count its rows through the row array (

--jq '.traces | length'

), and read how many there are in all at

.pagination.total

. Bare

--jq length

counts the fields of the envelope, not the rows. Read the docs first instead of guessing SDK APIs or CLI flags.

If no shell is available, fetch the same Markdown over plain HTTP. Append

.md

to any docs path (e.g. https://langwatch.ai/docs/integration/python/guide.md). Index: https://langwatch.ai/docs/llms.txt. Scenario index: https://langwatch.ai/scenario/llms.txt

If anything fails or confuses you while following this skill (broken commands, docs that do not match reality, errors you had to work around), ask the user for permission and run

npx --yes langwatch report --user-approved

with a

--title

and

--summary

(or

--session <transcript.jsonl>

) to send it to the LangWatch team, and it directly shapes what gets fixed. No login or API key needed. Nothing is sent without

--user-approved

, and

--dry-run

prints the exact payload without sending anything. The title, summary and transcript are scrubbed locally first, by pattern: secrets and API keys, plus email addresses, phone numbers, card numbers and public IPv4 addresses. Anything no pattern matches is sent as written, including a contact address passed with

--email

. With

--session

, always run

--dry-run

first and let the user read the payload, because a transcript carries content they never reviewed.

npx --yes langwatch report --help

explains the options.

使用

langwatch docs <path>

以 Markdown 格式阅读文档。一些有用的入口：

bash

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

发现可用命令。

list

和

get

命令支持

--format json

，可获得机器可读的结果。每个

list

命令都可使用

--limit <n>

限制返回行数，并使用

--jq <expr>

读取结果的一部分。分页

list

会返回一个封装对象，因此需要通过 row 数组统计行数（

--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

如果在执行此 skill 时遇到任何问题或困惑（命令失效、文档与实际情况不一致、你不得不绕过的错误），请先征得用户许可，然后运行

npx --yes langwatch report --user-approved

，并使用

--title

和

--summary

（或

--session <transcript.jsonl>

）将其发送给 LangWatch 团队；这会直接影响后续的修复内容。无需登录或 API key。只有指定

--user-approved

后才会发送内容；

--dry-run

会打印确切的 payload，而不会发送任何内容。title、summary 和 transcript 会先在本地按照特定模式进行脱敏，包括 secrets、API keys、email 地址、电话号码、卡号和 public IPv4 地址。任何未被模式匹配的内容都会原样发送，包括通过

--email

传入的联系地址。使用

--session

时，务必先运行

--dry-run

并让用户查看 payload，因为 transcript 可能包含用户从未审阅过的内容。

npx --yes langwatch report --help

会说明各个选项。

Step 1: Fetch Recent Traces

步骤 1：获取最近的 Trace

bash

langwatch trace search --limit 25 --start-date "$(( ($(date +%s) - 7*24*3600) * 1000 ))" --format json

(Widen or narrow the window as needed.

--start-date

accepts an ISO string or epoch milliseconds, and defaults to the last 24 hours. The epoch form above is used because

date -d '7 days ago'

is GNU-only and fails on macOS.)

For each trace, ask:

How many traces are there?
Do they have inputs and outputs populated, or are they
```
<empty>
```
?
Are there labels and metadata (user_id, thread_id)?

langwatch status

is a fast sanity check that the CLI is talking to the right project.

bash

langwatch trace search --limit 25 --start-date "$(( ($(date +%s) - 7*24*3600) * 1000 ))" --format json

（根据需要扩大或缩小时间窗口。

--start-date

接受 ISO 字符串或以毫秒为单位的 epoch 时间戳，默认值为过去 24 小时。之所以使用上面的 epoch 形式，是因为

date -d '7 days ago'

仅适用于 GNU 环境，在 macOS 上会失败。）

对于每条 trace，需要检查：

一共有多少条 trace？
输入和输出是否已填充，还是显示为
```
<empty>
```
？
是否存在 labels 和 metadata（user_id、thread_id）？

langwatch status

可以快速确认 CLI 是否正在与正确的项目通信。

Step 2: Inspect Individual Traces

步骤 2：检查单条 Trace

bash

langwatch trace get <traceId>            # Human-readable digest
langwatch trace get <traceId> -f json    # Full span hierarchy as JSON

For traces that look problematic, check for:

Empty input/output: The most common issue. Check if
```
autotrack_openai_calls(client)
```
(Python) or
```
experimental_telemetry
```
(TypeScript/Vercel AI) is configured.
Disconnected spans: Spans that don't connect to a parent trace. Usually means
```
@langwatch.trace()
```
decorator is missing on the entry function.

Missing labels: No way to filter traces by feature/version. Add labels via

langwatch.get_current_trace().update(metadata={"labels": ["feature_name"]})

Missing user_id/thread_id: Can't correlate traces to users or conversations. Add via trace metadata.
Slow spans: Unusually long completion times may indicate API timeouts or inefficient prompts.

bash

langwatch trace get <traceId>            # Human-readable digest
langwatch trace get <traceId> -f json    # Full span hierarchy as JSON

对于看起来有问题的 trace，检查以下情况：

输入/输出为空：最常见的问题。检查是否已配置
```
autotrack_openai_calls(client)
```
（Python）或
```
experimental_telemetry
```
（TypeScript/Vercel AI）。
未连接的 span：未连接到父 trace 的 span。通常表示入口函数缺少
```
@langwatch.trace()
```
装饰器。
缺少 labels：无法按 feature/version 过滤 trace。可以通过
```
langwatch.get_current_trace().update(metadata={"labels": ["feature_name"]})
```
添加 labels。
缺少 user_id/thread_id：无法将 trace 与用户或对话关联。可以通过 trace metadata 添加。
耗时过长的 span：异常长的 completion 时间可能表示 API 超时或低效的 prompt。

Step 3: Read the Integration Docs

步骤 3：阅读集成文档

Use the CLI to read the integration guide for the project's framework. Compare the recommended setup with what's in the code.

bash

langwatch docs                                  # Browse the docs index
langwatch docs integration/python/guide         # Python (or your framework)
langwatch docs integration/typescript/guide     # TypeScript (or your framework)

使用 CLI 阅读项目框架对应的 integration guide。将推荐的配置方式与代码中的实际配置进行比较。

bash

langwatch docs                                  # Browse the docs index
langwatch docs integration/python/guide         # Python (or your framework)
langwatch docs integration/typescript/guide     # TypeScript (or your framework)

Step 4: Apply Fixes

步骤 4：应用修复

For each issue found:

Identify the root cause in the code
Apply the fix following the framework-specific docs
Run the application to generate new traces

Re-inspect with

langwatch trace search

and

langwatch trace get

to verify the fix

针对发现的每个问题：

在代码中确定 root cause
根据框架专用文档应用修复
运行应用以生成新的 trace
重新使用
```
langwatch trace search
```
和
```
langwatch trace get
```
检查并验证修复效果

Step 5: Verify Improvement

步骤 5：验证改进效果

After fixes, compare before/after:

Are inputs/outputs now populated?
Are spans properly nested?
Are labels and metadata present?

You can also export a sample for diff:

bash

langwatch trace export --format jsonl --limit 50 -o traces.jsonl

修复后，对比修复前后的表现：

输入和输出现在是否已填充？
span 是否已正确嵌套？
labels 和 metadata 是否已存在？

你还可以导出一个样本用于比较差异：

bash

langwatch trace export --format jsonl --limit 50 -o traces.jsonl

Common Issues and Fixes

常见问题与修复方式

Issue	Cause	Fix
All traces show `<empty>` input/output	Missing autotrack or telemetry config	Add `autotrack_openai_calls(client)` or `experimental_telemetry: { isEnabled: true }`
Spans not connected to traces	Missing `@langwatch.trace()` on entry function	Add trace decorator to the main function
No labels on traces	Labels not set in trace metadata	Add `metadata={"labels": ["feature"]}` to trace update
Missing user_id	User ID not passed to trace	Add `user_id` to trace metadata
Traces from different calls merged	Missing `langwatch.setup()` or trace context not propagated	Ensure `langwatch.setup()` called at startup

问题	原因	修复方式
所有 trace 的输入/输出都显示为 `<empty>`	缺少 autotrack 或 telemetry 配置	添加 `autotrack_openai_calls(client)` 或 `experimental_telemetry: { isEnabled: true }`
span 未连接到 trace	入口函数缺少 `@langwatch.trace()`	在主函数中添加 trace 装饰器
trace 上没有 labels	未在 trace metadata 中设置 labels	在 trace update 中添加 `metadata={"labels": ["feature"]}`
缺少 user_id	未将 user ID 传入 trace	在 trace metadata 中添加 `user_id`
不同调用产生的 trace 被合并	缺少 `langwatch.setup()` 或 trace context 未传播	确保启动时调用 `langwatch.setup()`