> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# 追踪

> 查看请求、Agent 执行和工具调用链路，定位质量、权限和成本问题。

追踪用于还原一次请求从入口到模型、知识检索、工具调用和响应返回的关键步骤。它帮助管理员排查问题，同时避免把完整敏感内容暴露给不相关人员。

在受支持的部署中，艾维斯管理后台入口对应 `/admin/tracing`。页面会展示追踪能力入口、产品截图和 `联系销售` 操作。系统已经支持 Braintrust 和 Langfuse 两类 Tracing Provider；部分部署会向管理员开放 Provider 配置流程，托管部署或受控部署则可能需要由运维或 Alephant 联系人启用。

![艾维斯追踪总览页面，展示支出、Token、成功率、延迟、团队预算和模型成本](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/f7a0db509b2279f7f227c46e29a509f506e282f44bfe35fc5b2a8564b4f78689/assets/aivis/tracing/tracing-analytics-overview.webp?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T134506Z&X-Amz-Expires=604800&X-Amz-Signature=a30e2347107ebf539117f1346ea75b17852fbd665330118bfc15cc727a80091b&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

## 可以查看什么

| 问题                      | 查看位置                                                      |
| ----------------------- | --------------------------------------------------------- |
| 本月模型调用花费是多少？            | 在总览中查看支出、Token、成功率、延迟、团队预算和模型成本。                          |
| 哪个团队、Agent、模型或实体导致用量突增？ | 在请求日志中按时间范围、部门、实体、模型和状态筛选。                                |
| 某次请求为什么失败？              | 打开请求记录，对比状态、错误原因、Provider、Token、延迟和外部追踪结果。                |
| 预算或策略是否生效？              | 在预算、告警、限流和模型 fallback 策略视图中，对比测试请求前后的行为。                  |
| 是否能打开外部 trace？          | 确认 Braintrust 或 Langfuse 已配置，再按时间、模型、flow 或请求元数据到外部项目中检索。 |

## 管理边界

| 项目  | 建议                              |
| --- | ------------------------------- |
| 可见性 | 只让运维、管理员或获授权审计人员查看追踪。           |
| 内容  | 优先记录事实、状态和元数据，避免长期保存完整敏感上下文。    |
| 关联  | 使用请求 ID、用户、工作区、Agent 和模型标识关联链路。 |
| 保留  | 按企业审计和隐私要求设置保留周期。               |

## 配置前检查

* 确认哪些人可以打开艾维斯管理后台的追踪页面，哪些人可以管理 Tracing Provider 凭据。
* 在数据离开私有部署前，确认 prompt、回复、工具参数或检索片段是否需要脱敏、采样或缩短保留周期。
* 准备至少一条可测试的模型调用路径，例如聊天请求、Agent 运行、机器人消息、语音调用、图像生成或视频生成。
* 如果需要外部 trace，先准备 Braintrust 或 Langfuse 项目，并确认凭据由环境变量管理，还是由后台 Provider 配置流程管理。
* 将追踪与用量统计、查询历史、请求日志、预算和告警关联起来。

## 打开追踪入口

打开艾维斯管理后台，进入追踪页面。受支持的部署对应 `/admin/tracing`。

当前页面是能力入口，会说明可观测能力，并展示三类预期视图：用量总览、预算与策略控制、请求日志。如果你的部署只显示 `联系销售`，说明该环境没有开放自助 Provider 配置。此时需要联系部署负责人或 Alephant 联系人启用追踪，也可以由运维通过后端环境变量配置 Provider。

## 配置 Tracing Provider

艾维斯支持两类追踪 Provider：

| Provider   | 必填值                       | 可选值                      | 获取位置                                                                                        |
| ---------- | ------------------------- | ------------------------ | ------------------------------------------------------------------------------------------- |
| Braintrust | `API Key`                 | `Project Name`、`API URL` | 在 [Braintrust](https://www.braintrust.dev/app) 创建或复制 API key。除非使用其他区域或自托管端点，否则保持默认 API URL。 |
| Langfuse   | `Secret Key`、`Public Key` | `API Base URL`           | 在 [Langfuse](https://cloud.langfuse.com) 创建或复制密钥。使用其他区域或自托管 Langfuse 时填写自己的 host。           |

如果后台页面开放了 Provider 配置，选择 Provider 后填写字段，并先点击测试再保存。后端会先校验凭据，再保存为已启用状态。

运维管理的部署可以通过环境变量配置同样的值：

| Provider   | 环境变量                                                                 |
| ---------- | -------------------------------------------------------------------- |
| Braintrust | `BRAINTRUST_API_KEY`，可选 `BRAINTRUST_PROJECT`，可选 `BRAINTRUST_API_URL` |
| Langfuse   | `LANGFUSE_SECRET_KEY`、`LANGFUSE_PUBLIC_KEY`，可选 `LANGFUSE_HOST`       |

在多租户托管部署中，艾维斯只从环境变量解析 Tracing Provider。单租户部署中，同一 Provider 的已启用数据库配置可以覆盖环境变量 fallback。

![艾维斯追踪策略控制页面，展示预算、告警、限流和模型 fallback 设置](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/1ff0a52041fd9bb5a8789348d25b6a4f8524073898c4924739d640b18a3a661e/assets/aivis/tracing/tracing-policy-controls.webp?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T134506Z&X-Amz-Expires=604800&X-Amz-Signature=2199cdcff7d97a8c2c424ec0d663ffca0db77a435fd865448d6d4b24882adbaf&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

## 生成测试追踪

1. 保存或启用 Provider 配置。
2. 通过已知路径发送一次受控的艾维斯请求，例如使用测试 Agent 发起一次聊天。
3. 记录请求时间、用户、工作区、Agent、模型和预期结果。
4. 打开请求日志或外部 Tracing Provider，按相同时间范围和模型筛选。
5. 确认记录中包含状态、延迟、Token 用量、成本元数据和正确的 flow 名称。

艾维斯会通过明确的 flow 名称追踪多类 LLM 调用，包括聊天回复、聊天摘要、查询扩展、文档过滤、Embedding、Rerank、图像生成、视频生成、语音转文本、文本转语音、隐私网关调用和 Agent 自动化调用。测试后没有 trace，通常说明 Provider 未生效、该请求路径尚未埋点，或请求在模型调用开始前就失败了。

![艾维斯请求日志页面，展示时间、部门、实体、模型、状态、Token 和成本筛选](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/ec5e2d4c3a029965837f15a653de3a4fbe0a109ab79f9149d250972f05b2da03/assets/aivis/tracing/tracing-request-logs.webp?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T134506Z&X-Amz-Expires=604800&X-Amz-Signature=8eb8d19862728dc3b2c383729d1050abcbe6a4f3a17d962b78dde7197ff1d90d&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

## 验证

* 艾维斯追踪页面只能被获授权的运维、管理员或审计人员打开。
* 一次测试请求能在请求日志中按预期时间范围、模型、状态、Token、成本和延迟找到。
* 如果启用了 Braintrust 或 Langfuse，同一请求能在外部项目中找到。
* 失败或拒绝请求有可定位的原因，同时不会暴露不相关的敏感内容。
* 预算、告警、限流或 fallback 变更能反映到后续请求行为中。

## 常见问题排查

| 现象                       | 优先检查项                                                           |
| ------------------------ | --------------------------------------------------------------- |
| 页面只显示 `联系销售`             | 当前部署未开放自助 tracing 配置。联系运维或 Alephant 联系人启用追踪，或通过环境变量配置 Provider。 |
| Provider 测试失败            | 确认密钥属于所选 Provider，host 或 API URL 可被后端访问，复制时没有多余空格。              |
| Langfuse 拒绝凭据            | 确认 `Secret Key` 和 `Public Key` 来自同一个 Langfuse 项目。               |
| Braintrust trace 写入了错误项目 | 检查 `Project Name` 或 `BRAINTRUST_PROJECT`；只有目标项目就是默认项目时才留空。      |
| 测试请求后没有 trace            | 确认 Provider 已启用、后端 worker 已读取最新配置，并且测试的 flow 已埋点。               |
| 请求日志为空                   | 放宽时间范围，移除部门、实体、模型、状态筛选，并确认请求已到达艾维斯，而不是在上游机器人或网关失败。              |
| Token 或成本为空              | 确认模型 Provider 返回 usage metadata，并且请求执行到 usage processor 可记录的阶段。 |
| 用户能看到过多 trace            | 将追踪权限限制给管理员、运维或审计角色，不要让普通工作区用户查看原始 trace。                       |

## 安全与维护建议

* Provider API key 只应保存到受保护配置或后台凭据存储中。
* 不要把 API key、原始 prompt、私密回复、访问令牌、工具密钥或完整敏感上下文写入文档、工单、截图或 Agent 指令。
* 管理员变更或密钥疑似泄露时，轮换 Braintrust 和 Langfuse 凭据。
* 定期复核追踪页面访问权限，因为 trace 可能包含模型名称、用户 ID、工作区 ID、文档引用、错误和成本模式。
* 隐私要求严格时，原始内容保留周期应短于审计元数据保留周期。

## 相关页面

* [模型凭据](../models/model-credentials) 介绍模型 Provider 凭据的配置位置。
* [语言模型](../models/language-models) 介绍模型路由如何影响被追踪的调用。
* [生成与对话能力](../models/generation-and-chat) 介绍可用于测试 trace 的聊天路径。
* [钩子](./hooks) 介绍可与 trace 关联的受控出站回调。