跟踪与访问控制

通过 LLM Gateway 发出的每次调用都会被跟踪到 LangSmith，并且策略违规会显示在 LangSmith Engine 中，以便进行分析处理。

​

网关跟踪记录显示在哪里

默认情况下，所有由网关代理的调用都会被跟踪到与调用方 API 密钥关联的工作区中名为 gateway 的项目，以及一个特定于 API 密钥的项目。该项目采用 gateway-<short_api_key>-<api_key_id> 格式命名。 使用 RBAC 和 ABAC 控制对这些跟踪项目的访问权限。

​

跟踪元数据

网关代理调用与直接 LLM 调用的区别在于它们所属的项目，以及附加到其 span 上的元数据：

• 网关项目： 所有网关流量都会写入每个工作区中的中央网关项目，同时也会写入一个固定的 LangSmith 项目 gateway，并在 gateway-<short_api_key>-<api_key_id> 中为每个 API 密钥保留一份副本，以实现界面隔离。按项目筛选（或按是否存在 langsmith.metadata.gateway.* span 属性筛选），即可找到由网关代理的调用。
• 策略评估结果： 每个网关 span 都会通过 langsmith.metadata.gateway.policy.matched_ids/_names、passed_ids/_names 和 violated_ids/_names 记录所评估的策略及其结果，因此通过和阻止的调用都会被记录。
• 防护规则匹配： 当编辑策略生效时，防护流程会生成一个 rule_id → count 映射，并将其写入 span，字段为 policy.matched_rules、passed_rules 和 violated_rules。这些是规则 ID，而不是个人身份信息（PII）或机密类别标签。
• 成本数据： 令牌数量和成本会在线计算，并计入同一个由消费上限策略强制执行的消费累计器。

​

跟踪内容与计费

当网关数据保留策略中的 Trace content 被禁用时，不会存储请求正文和响应正文。网关仍会生成仅包含元数据的跟踪记录，其中可能包括令牌使用量、延迟、状态和模型信息。由网关生成的仅包含元数据的跟踪记录不计入基于跟踪记录的计费，但模型使用量仍会计入网关消费跟踪。

​

LangSmith Engine 集成

当治理策略触发时（例如达到消费上限、检测到并编辑个人身份信息，或捕获到机密信息），事件会作为元数据记录在跟踪记录中。这些策略违规会显示为 LangSmith Engine 中的问题。 在 Engine 问题中，你可以：

1. 查看违规情况： 哪项策略被触发，以及哪些内容被阻止或编辑。
2. 跳转到跟踪记录： 准确查看策略触发时代理正在执行的操作。
3. 诊断根本原因： 是重试循环耗尽了预算、用户将凭据粘贴到了提示中，还是合法工作负载超出了其上限，等等。
4. 采取措施： 更新代理配置、调整策略或进行升级处理。

​

审计日志

网关会记录两类事件： 审计日志面向 Enterprise 计划的组织管理员提供。

​

权限

​

所需权限

内置的 WORKSPACE_USER 和 WORKSPACE_VIEWER 角色不包含 gateway:invoke，且无法编辑。若要在不授予完整工作区管理员权限的情况下授予网关访问权限，请创建一个包含 gateway:invoke 和 workspaces:read 的自定义工作区角色（需要启用 RBAC 的计划）。相关说明请参阅管理员设置。

​

API 密钥范围

始终为网关使用工作区范围的 API 密钥。不支持使用组织范围的密钥调用网关。

​

集中管理提供商凭据

网关会将提供商 API 密钥集中存储在 LangSmith 工作区机密中。单个开发者和代理使用其 LangSmith API 密钥进行身份验证，无需直接访问提供商密钥。 这意味着：

• 凭据控制： 提供商密钥集中存放，由管理员管理。撤销访问权限意味着撤销 LangSmith API 密钥，而不是寻找分散存储的提供商密钥副本。
• 策略执行： 由于所有调用都经过网关，因此策略能够得到一致执行。只要开发者没有单独访问提供商密钥的权限，就无法通过直接调用提供商来绕过成本限制。

为确保其按预期工作，请勿在授予网关访问权限的同时，将提供商 API 密钥分发给开发者。默认情况下，网关会集中管理提供商凭据。对于 Claude Code Max 等基于 OAuth 的流程，也提供直通模式——如果你的组织希望允许或限制此模式，请联系我们。

​

限制跟踪记录可见性

网关跟踪记录会作为运行记录写入工作区项目，并遵循 LangSmith 的标准工作区成员资格模型。在工作区中拥有 runs:read（以及用于查看项目本身的 projects:read）权限的任何人，都可以查看该工作区网关项目中的跟踪记录。内置角色 WORKSPACE_ADMIN、WORKSPACE_USER 和 WORKSPACE_VIEWER 默认都包含这两项权限。 如果需要限制可以查看网关跟踪记录的人员，有两种选择：

• 单独的工作区（适用于任何计划）：创建一个成员资格受限的工作区，以及另一个供开发者编码代理使用、成员范围更广的工作区。每个工作区都有自己的提供商机密和跟踪项目。
• 项目级访问策略（需要 Enterprise 计划）：编写 ABAC 策略，将网关项目上的 projects:read 和 runs:read 限制为特定用户或角色。

​

后续步骤

• 管理员设置：配置上述所有内容的分步指南。
• 消费策略：为 API 密钥和用户设置成本限制。
• 数据保护：配置数据保护策略。

---