日志与审计

AISIX Cloud 控制面为运维人员提供两类证据链：用于 AISIX 网关流量的请求日志，以及用于控制面状态变更的审计日志。两者结合起来，可以帮助团队了解一次请求发生了什么，以及是谁修改了影响流量的资源。

使用请求日志排查具体的 AISIX 网关请求；使用审计日志排查配置、访问权限和其他控制面变更。

请求日志

请求日志基于 AISIX 网关遥测数据生成。它展示单个请求的结果，包括请求时间、状态、请求模型、调用方 API Key、延迟、Token 数量，以及可用时的尝试详情。延迟会从两个角度报告：调用方等待了多久，以及上游处理花费了多久。这样无需猜测即可判断慢请求的延迟来源。

展开一行会看到 AISIX 分配的请求 ID；如果这次调用到达了会返回 ID 的服务提供方，旁边还会有一个服务提供方请求 ID。二者含义不同：前者由 AISIX 通过 x-aisix-request-id 响应头返回给调用方，也是报障的调用方通常手上唯一有的 ID；后者是上游服务提供方在自己的响应中返回的 ID，例如 OpenAI 的 chat.completion.id 或 Anthropic 的消息 id，服务提供方的控制台和技术支持渠道正是按它检索这次调用的。先用前者查到该请求，再从中读取后者，然后拿它去找服务提供方。

如果本次调用没有产生服务提供方请求 ID，该字段不会显示：包括响应由缓存命中返回、请求在 AISIX 到达服务提供方之前就被拒绝，以及服务提供方响应本身就不带 ID 的端点（如 Embedding、音频和图像生成）。重试或故障转移的请求会按拿到响应的尝试各记录一个，因此请展开实际向调用方返回响应的那次尝试。

带有 estimated 标记的行包含一个或多个本地计算的 Token 数量，因为上游响应省略了这些值或将其报告为零。这种情况可能出现在 OpenAI 兼容中继、客户端在流式传输中途断开，以及上游返回部分响应后出错时。估算的 Token 数量会与服务提供方报告的数量一起计入支出和预算计算。排查用量或支出时，可以通过该标记区分估算值。有关支持的端点和估算行为，请参阅用量上报。

数据面会批量刷新遥测数据，因此刚完成的请求可能需要几秒才会出现。

每行都会显示本地日期和时间，因此跨越多天的时间范围仍易于阅读。将鼠标悬停在时间戳上可查看包含时区的完整日期和时间。

当需要验证实时请求、检查上游错误、确认策略拒绝，或查看路由与故障转移如何解析请求时，请先查看请求日志。

解读延迟数据

请求日志行会显示调用方等待的时间。展开该行可以查看拆分后的测量值，因为单个数字无法判断慢请求是由服务提供方还是网关造成的：

字段	测量内容	范围
调用方延迟	从网关收到请求，到完成非流式响应或开始发送流式响应。	整个请求，包括每次重试和故障转移尝试。
上游延迟	实际处理该请求的尝试与服务提供方通信所花费的时间。	一次尝试。
上游 TTFT	该尝试等待服务提供方首个流式帧的时间，无论帧内容为何——包括 response.created、message_start 等元数据起始帧。仅适用于流式请求。	一次尝试。

讨论 SLO 时应引用调用方延迟；Overview 页面中的 Latency p50 / p99 卡片也使用该指标。

上游 TTFT 在流的首个帧到达时停止计时，而不是首个可见 Token。这与部署在 AISIX 前面的代理和网关的统计口径一致，因此该值可以与它们记录的数据直接对比。如果推理模型在思考期间不输出任何可见内容——例如 /v1/responses 上游会立即打开流、但不输出推理摘要——那么即使回答文本很晚才开始，TTFT 也会很小；这段思考等待计入上游延迟，而不是 TTFT。

对于流式响应，调用方延迟会在流开始时停止计时，而不是等到流结束。流的总持续时间会随模型生成的 Token 数量增加，无法有效反映用户体验；用户真正感知的是输出开始出现前的等待时间。

比较这些字段可以定位延迟。如果请求未重试，而调用方延迟远高于上游 TTFT，说明时间花在网关侧处理上。常见原因是执行脱敏的输出安全护栏：它必须缓冲完整响应流后才能释放内容。如果两者接近，则主要耗时来自服务提供方。对于发生重试或故障转移的请求，差值还包含先前的尝试，因此应先查看尝试记录。

Latency p50 / p99 卡片只统计成功请求。被拒绝的请求通常很快，正是因为系统没有执行多少处理；如果将其计入，会拉低百分位数并掩盖实际的慢请求。

备注

0.7 之前的数据面只记录单一延迟值，没有面向调用方的延迟，因此这些记录不会计入延迟百分位数。升级后记录的流量才会使用拆分后的延迟字段。

语义护栏测到了什么

如果某个基于向量相似度的安全护栏筛查过这个请求，展开该请求还会看到语义护栏相似度。每条记录会给出安全护栏名称和运行的钩子、它比对的是哪个示例列表、实测相似度与其比较的阈值、产生该分数的 embedding 模型，以及最接近的那条示例在该列表中的行号。

放行的请求和被拒绝的请求都会记录，monitor 模式和 block 模式下也都会记录。这正是它对调优有价值的地方：监控命中只在安全护栏本应阻断时才出现，因此一个刚好差一点触发的行——拒绝阈值略高，或允许阈值略低——完全不会产生监控命中，看上去与安全护栏根本没在运行毫无区别。而相似度分数两种情况下都会记录。

有几个端点不会上报，其中包括下面两个：/a2a 会筛查流量却完全不记录任何安全护栏证据；rerank 在上游返回的用量块网关读不出来时根本不会发出用量事件，因此连日志行都不会有。

展开后看不到分数有以下几种原因：没有语义安全护栏筛查过它、它是旧版网关记录的、有别的安全护栏先拒绝了这个请求（链在第一次阻断处停止，因此优先级更高的安全护栏一旦命中，它后面的语义安全护栏就不会执行）、这一行是重试、故障转移或 ensemble 请求中被取代的那次尝试（只有该请求的终态行带有分数，它并不总是列在最后的那一行）、作用在输出钩子上的行，其流式回复超出了 max_buffer_bytes、在安全护栏运行前就被拒绝、没有可筛查的文本（在默认的 text_source: user_messages 下，只带图片的请求不会发起 embedding 调用）、它是 /a2a 的行（该端点会筛查流量，但完全不记录任何安全护栏证据，下文三个失败字段对它同样不适用），或者 embedding 调用失败了。最后这一种是最需要排除的：筛查在失败处中止，此时还没有产生分数，因此在这个区域里，一个正在故障的 embedding 模型看起来与一个安静的安全护栏完全一样。

embedding 调用失败会在同一行的别处留下信号，具体在哪个字段取决于该行的模式。block 且失败关闭（默认）会拒绝该请求，并在 guardrail_enforced_hits 中记录动作 blocked_unavailable，执行命中里显示为检查不可用。monitor 且失败关闭会照常放行，并在 guardrail_monitor_hits 中记录动作 would_block，监控命中里显示为本应拦截——此时另外两个字段都不会写，因此这是最容易误读的一种。两种模式在失败放行时，都会让请求未经该安全护栏筛查就通过——链上其余安全护栏仍然执行了——并记录一条绕过原因（guardrail_bypassed_reason）。在把空白区域理解为「无事发生」之前，请先查这三处。

不同 embedding 模型的分数不可互相比较，因此每个分数旁边都会显示对应的模型。被筛查的文本和示例文本都不会被记录——示例只通过 top_example_index 来标识，它是该方向列表中从 0 开始的序号，而控制台会把它渲染成从 1 开始的行号。如何把这些数值转化为一个阈值，参见校准阈值。

按请求类型筛选

每一行都会携带该请求要求网关做的事情——对话补全、图片生成、视频提交、工具调用——Operation 筛选器可以把日志收窄到其中一类。行上没有别的字段能回答这个问题：所有 OpenAI 兼容端点上报的入站协议相同，因此文本对话和图片生成看起来一样；模型名称也不是替代品，同一个模型可以服务多个端点，而调用方是通过别名和模型组来寻址模型的。

除四个对话类取值（chat、messages、responses、completions，常见情况）外，每一行都会标出操作类型；展开行即可看到取值本身。网关升级之前记录的请求不携带操作类型：它们既不会被标出，也不会被该筛选器选中。该筛选器在所有标签页上都生效——MCP、A2A 和透传流量本身也是操作类型——并且切换标签页后依然保持。它是在标签页之内收窄而不是覆盖标签页，因此一个本就为空的组合（比如在 LLM 标签页上选 mcp）会返回空列表，而不是列出 MCP 流量。

取值清单及各自的含义参见区分请求类型，那里同时说明了同一个字段如何到达外部导出器。

在读计数之前有两点需要了解。操作类型描述的是请求，因此失败或被策略拒绝的行携带的取值与成功请求相同——这正是你能看出拒绝发生在哪个端点的原因。另外，发生重试或故障转移的请求每次尝试产生一行，因此按行计数得到的是尝试数而不是请求数。

搜索请求

筛选器上方的搜索框会在请求的所有文本字段中查找输入内容，且不区分大小写。搜索范围包括错误消息和错误类别、请求模型和解析后的模型名称、服务提供方及服务提供方密钥标签，以及客户端 User-Agent、源 IP、完成原因、请求 ID 和服务提供方请求 ID——因此服务提供方技术支持渠道提供的 ID 也能在这里找到对应的请求。当你只掌握客户端报告的部分错误内容，却不知道它位于哪个字段时，可以使用搜索功能。

搜索会与筛选器组合，而不是替代筛选器。例如，搜索 rate limit 并同时选择 5xx 状态筛选器，只会返回文本中提到限流的服务端错误。已知请求 ID、模型、服务提供方密钥或调用方 API Key 时，专用筛选器仍是更精确的方式。

在请求模型/模型组筛选器中，直接输入会对别名进行不区分大小写的模糊（子串）匹配；从候选项选择模型或模型组时，则会对完整别名进行区分大小写的精确匹配。导出会沿用请求列表当前生效的输入或选择匹配方式。

导出请求

Export 会下载符合当前筛选条件和搜索内容的所有请求，而不仅是屏幕上的当前页。选择 CSV 可在电子表格中审查，选择 JSON 可供下游流水线使用；JSON 会返回与控制面 API 相同的字段，并包装在包含 data 数组和 total 总数的对象中。

两种格式都包含请求时间、请求 ID、尝试详情、状态和错误文本，还包括操作类型、请求模型和解析后的模型名称、调用方 API Key 名称、Token 数量、延迟及成本。调用方延迟和上游延迟会分别写入独立的列。CSV 文件采用带字节顺序标记的 UTF-8 编码，因此电子表格应用可以正确读取非 ASCII 错误消息。安全护栏相关的证据也会随行导出：guardrail_scores 记录各语义安全护栏实测的相似度，在 CSV 中是一列，在 JSON 中是一个数组。

一次最多导出 50,000 个请求，并按时间从新到旧排列。当匹配结果超过该数量时，控制面会导出最新的 50,000 个请求，并报告完整的匹配总数。请缩小时间范围或筛选条件，以导出其余请求。

审计日志

审计日志记录控制面状态变更，用于合规审查和运维调查。它会显示谁创建、更新或删除了环境、模型、API Key、服务提供方密钥、预算、策略和 Admin Token 等资源。

如果配置更新后流量行为发生变化，请使用审计日志。请求日志可以展示请求结果，审计日志则可以确认该结果出现前是否修改了控制面资源。

只有组织 Owner 和 Admin 可以访问审计日志。

条目按时间从新到旧排列，记录列表底部会显示当前筛选条件匹配的条目总数。页码对应完整的已筛选集合，而不是当前已经加载的内容，因此可以从已知位置继续审查。

筛选和搜索审计记录

记录列表上方的筛选器可以按资源类型、Actor 和时间缩小范围。资源类型列表只提供该组织实际记录过的类型。时间范围提供预设值和 Custom range；后者接受明确的开始与结束时间，可将审查锁定到事件发生的精确时间窗口。

搜索框会在条目的可读字段中查找输入文本，且不区分大小写。搜索范围包括变更前后的状态（资源显示名称位于其中）、资源类型和标识符、Action、Actor 标识符、客户端 IP 地址和 User-Agent。如果工单只给出了资源名称，却没有说明是哪次变更影响了它，可以使用搜索功能。

搜索会与筛选器组合，而不是替代筛选器。例如，搜索模型名称并同时选择一个 Actor，只会返回该人员涉及该模型的变更。已知资源类型或 Actor 时，专用筛选器仍是更精确的方式。

导出审计记录

Export 会下载符合当前筛选条件和搜索内容的所有条目，而不仅是屏幕上的当前页。选择 CSV 可在电子表格中审查，选择 JSON 可供下游流水线或证据归档使用。JSON 会返回与控制面 API 相同的字段，并包装在包含 data 数组和 total 总数的对象中。

两种格式都包含条目时间和标识符、Action、资源类型和标识符、客户端 IP 地址和 User-Agent，以及完整的变更前后状态。它们还会同时包含 Actor 的电子邮件地址和 Actor 标识符，使没有控制台访问权限的审查人员也能理解导出文件。CSV 文件采用带字节顺序标记的 UTF-8 编码，因此电子表格应用可以正确读取非 ASCII 资源名称。

一次最多导出 50,000 个条目，并按时间从新到旧排列。当匹配结果超过该数量时，控制面会导出最新的 50,000 个条目，并报告完整的匹配总数。请缩小时间范围或筛选条件，以导出其余条目。

调查请求结果

使用属于同一网关环境的调用方 API Key 和模型别名，通过 AISIX 网关端点发送请求。

请求完成后，在请求日志中检查匹配的请求时间、状态、请求模型和调用方 API Key。如果请求使用了路由或故障转移，请在可用时查看解析后的模型或尝试详情。

上游身份认证、配额或服务提供方侧错误仍可以证明 AISIX 网关路径正常。此时，请求已经到达 AISIX；AISIX 选择了已配置的模型和服务提供方密钥，随后上游服务提供方返回错误。

除非日志显示错误的模型、服务提供方密钥或环境，否则不要把服务提供方错误视为资源投射失败。

调查策略拒绝

AISIX Cloud 策略可以在 AISIX 调用上游服务提供方前拒绝流量。预算硬性限制会返回预算相关错误，限流策略会返回限流错误；安全护栏可以根据钩子点，在服务提供方调用前或调用后拒绝不安全内容。

请求被拒绝时，请先确认响应来自 AISIX 还是上游服务提供方，再通过请求日志检查状态和请求身份。

对于预算拒绝，请把返回的预算 Scope 与 Budgets 视图进行比较。对于限流拒绝，请检查与请求匹配的调用方 API Key、模型、团队或成员策略。对于安全护栏拒绝，请检查安全护栏 Scope，以及触发它的模型或调用方身份。

流量未出现在请求日志中

如果请求日志中没有预期记录，请先检查请求路径。请求日志只包含选中环境的 AISIX 网关流量，因此发送到其他网关端点或其他环境的请求会显示在对应位置。

如果请求路径正确，请检查 AISIX 网关是否有较新的心跳，并确认它可以访问控制面遥测端点。

其他控制面信号也可以帮助缩小原因：

信号	显示内容
数据面心跳	AISIX 网关是否已连接控制面，并且是否从预期环境上报。
用量	控制面是否收到了用于汇总用量和预算工作流的 AISIX Cloud 网关遥测数据。
可观测性导出器健康状态	网关是否已应用导出器配置，并是否正在上报外部遥测目的地的投递状态。

外部导出器

请求日志展示控制面对 AISIX Cloud 网关遥测数据的视图。可观测性导出器从环境的 Observability 视图配置，并将用量事件从 AISIX 网关发送到你控制的目的地。

当需要将请求遥测发送到外部链路追踪、日志、存储或核算系统时，请使用导出器。导出器由 AISIX 网关直接向目标目的地投递数据。即使外部目的地存在凭证、网络或接收路径问题，请求日志仍然可能存在。

数据保留

控制面会根据每个组织的保留窗口保存 AISIX Cloud 网关遥测数据，其中包括 Request Logs 和 Usage 视图背后的数据。默认情况下，记录会保留 30 天，控制面每天自动移除更早的记录。

组织 Owner 和 Admin 可以在 Settings 下的 Usage log retention 中，将保留窗口设置为 1 到 3650 天。较长窗口会保留更多历史记录，便于调查和报告；较短窗口会减少存储的数据量。变更只对后续清理生效，并在下一次每日清理时应用。

由于保留策略，较早的流量最终会从请求日志和用量视图中消失。如需在保留窗口之外保存请求遥测，请配置外部导出器，在记录被移除前把用量事件投递到你控制的目的地。

下一步

有关支持的自动化操作，请使用 AISIX Cloud Admin API 参考。如需将网关遥测数据投递到自有系统，请继续阅读可观测性导出器。