Logging and Auditing
The AISIX Cloud control plane gives operators two evidence trails: request logs for AISIX gateway traffic and an audit log for control-plane state changes. Together, they help teams understand what happened to a request and who changed the resources that affect traffic.
Use request logs to investigate a specific AISIX gateway request. Use the audit log to investigate configuration, access, and other control-plane changes.
Request Logs
Request logs are built from AISIX gateway telemetry. They show individual request outcomes, including request time, status, requested model, caller API key, latency, token counts, and attempt details when available. Latency is reported from two angles — what the caller waited for and what the upstream spent — so a slow request can be attributed without guesswork.
Rows with an estimated badge contain one or more token counts calculated locally because the upstream response omitted those values or reported zero. This can occur with OpenAI-compatible relays, client disconnects mid-stream, and upstream errors after a partial response. Estimated counts are included in spend and budget calculations alongside provider-reported counts. The badge distinguishes estimated values when investigating usage or spend. See Usage Reporting for the supported endpoints and estimation behavior.
Freshly completed requests can take a few seconds to appear because data planes flush telemetry in batches.
Each row is timestamped with its local date and time, so a window that spans several days stays readable. Hover over a timestamp to see the full date with its time zone.
Start with request logs when you need to verify a live request, inspect an upstream error, confirm a policy rejection, or check how routing and failover resolved a request.
Read the Latency Figures
A request log row shows what the caller waited for. Expand the row to see the measurement broken out, because a single number cannot answer whether a slow request was the provider's fault or the gateway's:
| Field | Measures | Scope |
|---|---|---|
| Caller latency | Gateway received the request until it handed the client something usable: the complete response for a non-streaming request, the first token for a streamed one. | The whole request, including every retry and failover attempt. |
| Upstream latency | How long the attempt that served the request spent talking to the provider. | One attempt. |
| Upstream TTFT | How long that attempt waited for the provider's first generated token. Streaming only. | One attempt. |
Caller latency is the figure to quote in an SLO discussion, and it is what the Latency p50 / p99 card on the Overview page reports.
Reasoning output counts as generated output. On a model that streams reasoning_content deltas ahead of its content deltas, upstream TTFT stops at the first reasoning delta rather than waiting for the answer that follows — which is what the caller sees, since AISIX forwards those deltas as they arrive. Expect TTFT on such a model to be far shorter than the request's total duration, because the whole reasoning phase lands between the first token and the final answer.
For a streamed response, caller latency deliberately stops at the first token rather than the last. A stream's total duration grows with however many tokens the model generated, which says little about the experience; the wait before output starts appearing is what a user notices.
Comparing the fields locates the delay. When caller latency far exceeds upstream TTFT on a request that did not retry, the time went to gateway-side work. The usual cause is an output guardrail that masks responses: it must buffer the whole stream before releasing any of it. When the two figures are close, the provider was the slow part. On a request that retried or failed over, the gap also contains the earlier attempts, so check the attempt rows first.
The Latency p50 / p99 card counts successful requests only. A rejected request is usually fast precisely because little happened, and including those would pull the percentiles down and mask real slowness.
Requests recorded by a data plane older than 0.7 carry a single latency value and no caller-facing figure, so they do not appear in the latency percentiles. The split applies to traffic recorded after the upgrade.
Search Requests
The search box above the filters looks for the text you type anywhere in a request's text fields, ignoring case. It covers the error message and error class, the requested and resolved model names, and the provider and provider key labels. It also covers the client user agent and source IP, the finish reason, and the request ID. Use it when all you have is part of an error a client reported and you do not know which field carries it.
Search combines with the filters rather than replacing them. For example, a search for rate limit together with the 5xx status filter returns only the server errors whose text mentions a rate limit. The dedicated filters remain the precise way to narrow by a known request ID, model, provider key, or caller API key.
Export Requests
Export downloads every request matching the current filters and search, not just the page on screen. Choose CSV for spreadsheet review or JSON for a downstream pipeline; JSON returns the same fields as the control-plane API, wrapped in a data array with a total count.
Both formats carry the request time, request ID and attempt details, and the status and error text. They also carry the requested and resolved model names, caller API key name, token counts, latency, and cost. Both the caller-facing and upstream latency figures are included as separate columns. CSV files are UTF-8 with a byte-order mark, so spreadsheet applications read non-ASCII error messages correctly.
One export returns at most 50,000 requests, newest first. When the filters match more than that, the control plane exports the newest 50,000 and reports the full match count. Narrow the time range or the filters to export the remainder.
Audit Log
The audit log records control-plane state changes for compliance review and operational investigation. It shows who created, updated, or deleted resources such as environments, models, API keys, provider keys, budgets, policies, and admin tokens.
Use the audit log when traffic behavior changes after a configuration update. Request logs can show the request outcome, while the audit log can show whether a control-plane resource changed before that outcome.
Audit log access is restricted to organization owners and admins.
Entries are listed newest first, and the footer below the trail reports how many entries the current filters match in total. Page numbers refer to that whole filtered set rather than to what has been loaded so far, so a review can be resumed at a known position.
Filter and Search the Trail
The filters above the trail narrow it by resource type, actor, and time. The resource-type list offers only the types this organization has actually recorded. The time range offers presets and a Custom range, which takes an explicit start and end time so a review can be pinned to the exact window an incident covers.
The search box looks for the text you type anywhere in an entry's readable fields, ignoring case. It covers the recorded before and after state, which is where a resource's display name lives. It also covers the resource type and identifier, the action, the actor identifier, the client IP address, and the user agent. Use it when a ticket names the resource but not which change touched it.
Search combines with the filters rather than replacing them. For example, a search for a model name together with an actor returns only that person's changes mentioning the model. The dedicated filters remain the precise way to narrow by a known resource type or actor.
Export the Trail
Export downloads every entry matching the current filters and search, not just the page on screen. Choose CSV for spreadsheet review, or JSON for a downstream pipeline or an evidence archive. JSON returns the same fields as the control-plane API, wrapped in a data array with a total count.
Both formats carry the entry time and identifier, the action, the resource type and identifier, the client IP address and user agent, and the complete before and after state. They also carry the actor's email address alongside the actor identifier, so an exported file stays readable for a reviewer who does not have dashboard access. CSV files are UTF-8 with a byte-order mark, so spreadsheet applications read non-ASCII resource names correctly.
One export returns at most 50,000 entries, newest first. When the filters match more than that, the control plane exports the newest 50,000 and reports the full match count. Narrow the time range or the filters to export the remainder.
Investigate a Request Outcome
Send the request through the AISIX gateway endpoint with a caller API key and model alias that belong to the same environment as the gateway.
After the request completes, check request logs for a matching request time, status, requested model, and caller API key. If the request used routing or failover, inspect the resolved model or attempt details when they are available.
An upstream authentication, quota, or provider-side error can still prove that the AISIX gateway path is working. In this case, the request reached AISIX. AISIX selected the configured model and provider key, then the upstream provider returned an error.
Do not treat a provider error as a resource-projection failure unless the log shows the wrong model, provider key, or environment.
Investigate Policy Rejections
AISIX Cloud policies can reject traffic before AISIX calls the upstream provider. Budget hard stops return a budget-related error, and rate-limit policies return a rate-limit error. Guardrails can reject unsafe content before or after the provider call depending on the guardrail hook.
When a request is rejected, first identify whether the response came from AISIX or from the upstream provider. Then use request logs to check the status and request identity.
For budget rejections, compare the returned budget scope with the Budgets view. For rate-limit rejections, check the caller API key, model, team, or member policy that matches the request. For guardrail rejections, check the guardrail scope and the model or caller identity that triggered it.
If Traffic Does Not Appear in Request Logs
If request logs do not show the expected record, check the request path first. Request logs are scoped to AISIX gateway traffic for the selected environment, so requests sent to another gateway endpoint or another environment appear elsewhere.
If the request path is correct, check that the AISIX gateway has a recent heartbeat and can reach the control-plane telemetry endpoint.
Other control-plane signals can help narrow the cause:
| Signal | What it shows |
|---|---|
| Data planes heartbeat | Whether the AISIX gateway is connected to the control plane and reporting from the expected environment. |
| Usage | Whether the control plane received AISIX Cloud gateway telemetry for aggregate usage and budget workflows. |
| Observability exporter health | Whether the gateway has applied exporter configuration and is reporting delivery status for external telemetry destinations. |
External Exporters
Request logs show the control plane's view of AISIX Cloud gateway telemetry. Observability exporters are configured from the environment's Observability view and send usage events from the AISIX gateway to destinations you control.
Use exporters when you need to send request telemetry to an external tracing, logging, storage, or accounting system. Exporter delivery happens from the AISIX gateway directly to the destination. A request log can exist even when an external destination has a credential, network, or receiver-path issue.
Data Retention
The control plane keeps AISIX Cloud gateway telemetry for a per-organization retention window. This includes the data behind both the Request Logs and Usage views. By default, records are kept for 30 days, and the control plane automatically removes older records each day.
Organization owners and admins set the retention window in Settings, under Usage log retention, to any value from 1 to 3650 days. A longer window preserves more history for investigation and reporting. A shorter window reduces how much data is stored. A change applies going forward and takes effect on the next daily cleanup.
Retention is why older traffic eventually stops appearing in Request Logs and Usage. To keep request telemetry beyond the retention window, configure an external exporter to deliver usage events to a destination you control before the records are removed.
Next Steps
Use the AISIX Cloud Admin API Reference for supported automation operations. To deliver gateway telemetry to systems you operate, continue with Observability Exporters.