analytics

使用 LangWatch 分析 Agent 性能

此技能用于查询和呈现分析数据，不会编写代码。

第 1 步：设置 LangWatch CLI

使用 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 输出机器可读数据。请先阅读文档，而不是猜测 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

项目和 API 密钥：请使用真实项目，而不是个人项目。

LangWatch 有两种项目：

• 团队／共享项目：组织内的真实项目。评估、实验、提示词、数据集、模拟和埋点都必须始终以其中一个项目为目标。
• 个人项目：与单个用户关联的私人“My Workspace”临时空间。切勿将用户的评估、实验或生产跟踪数据发送到这里：它仅用于个人探索，而且很容易与真实项目混淆。

身份验证方式有两种：

• .env 中的项目 API 密钥（LANGWATCH_API_KEY）：本技能中所有操作使用的凭据。它仅限于一个真实项目。这是默认方式；除非用户明确提出其他要求，否则优先使用此方式。
• langwatch login --device（AI 工具／SSO）：用于封装编码助手（langwatch claude、langwatch codex 等）的个人设备会话。它不适用于评估、提示词、数据集、场景或 SDK 埋点，并且会指向个人工作区。请勿运行此命令来设置本技能中的工作。

因此，对于本技能中的任何操作：请确保项目的 .env 中包含真实共享项目的 LANGWATCH_API_KEY。如果缺少该密钥，请向用户索取（他们可以在 https://app.langwatch.ai/authorize 为特定项目创建密钥）。不要运行 langwatch login 来选择项目，也绝不要默认使用个人项目。如果设置了 LANGWATCH_ENDPOINT，则表示他们使用可自托管版本，请使用该端点，而不是 app.langwatch.ai。

第 2 步：获取项目概览

langwatch status

此操作会显示资源数量（跟踪数据、评估器、场景、数据集等），并提示你有哪些子命令可用。

第 3 步：查询趋势和聚合数据

使用 langwatch analytics query 查询时间序列数据和聚合指标。先从预设开始：

langwatch analytics query --metric trace-count        # Total traces over the last 7 days
langwatch analytics query --metric total-cost         # Total LLM cost
langwatch analytics query --metric avg-latency        # Average completion latency
langwatch analytics query --metric p95-latency        # P95 completion latency
langwatch analytics query --metric eval-pass-rate     # Evaluation pass rate

使用 --start-date、--end-date、--group-by、--time-scale 和 --aggregation 进一步细化。使用 langwatch analytics query --help 查看所有标志，并使用 --format json 将输出提供给其他工具。

如果不知道有哪些预设名称，或者想查询非预设的指标路径：

langwatch analytics query --help                       # Lists presets and flags
langwatch docs analytics/custom-metrics                # Background on the metric model

第 4 步：查找特定跟踪数据

langwatch trace search -q "error" --limit 10           # Find error traces by keyword
langwatch trace search --start-date 2026-01-01         # Custom date range
langwatch trace search --format json                   # Machine-readable output

第 5 步：检查单条跟踪数据

langwatch trace get <traceId>                          # Human-readable digest (default)
langwatch trace get <traceId> -f json                  # Raw JSON for full detail
langwatch trace export --format csv -o traces.csv      # Bulk export as CSV
langwatch trace export --format jsonl --limit 500      # Bulk export as JSONL

对于每条值得关注的跟踪数据，请查看：

• 完整的请求／响应
• 每个跨度的 Token 数量和成本
• 错误消息和堆栈跟踪
• 多步 Agent 中的单次 LLM 调用

第 6 步：呈现发现

向用户清晰地总结数据：

• 首先列出用户关注的关键数据
• 突出异常或值得关注的趋势（成本激增、延迟上升、错误率变化）
• 在适当时通过与之前的时间段对比来提供背景信息
• 如果发现问题，建议后续步骤（例如：“周二的 p95 延迟激增了——以下是当天最慢的跟踪数据”）

常见错误

• 不要尝试编写代码——此技能会查询现有数据，不需要安装 SDK 或修改代码
• 使用 langwatch analytics query --metric ... 中的预设名称（trace-count、total-cost、avg-latency 等）；除非预设列表无法满足需求，否则不要硬编码原始指标路径
• 不要在此处使用 langwatch evaluator create / langwatch monitor create——此技能仅用于只读分析
• 不要向用户展示原始 JSON——请用清晰易懂的格式总结数据
• 如果 CLI 返回错误，请在回复中原样呈现确切的错误消息，而不要转述——用户通常需要原始错误信息来排查 API 密钥、项目或日期范围问题