AISIX Observability: Metrics, Logs, Headers, and Usage Events

Key Takeaways

• AISIX exposes four complementary telemetry surfaces: Prometheus metrics, structured access logs, caller-visible response headers, and exportable usage events.
• Metrics summarize gateway health and traffic. Access logs explain one proxy request. Usage events preserve per-attempt outcomes and consumption, including retries and failovers.
• In AISIX 1.4, a streamed request's access log is written when the stream ends and carries the final outcome plus token and provider fields when available.
• x-aisix-request-id is correlation context, not authenticated identity. AISIX may adopt a valid caller-supplied value when startup configuration allows that header.
• AISIX Cloud request logs and audit logs serve different purposes: request investigation versus control-plane change evidence.
• Use the AI Gateway Observability guide for the product-neutral signal model. This article explains how to operate the AISIX signal surfaces.

Choose the AISIX Signal for the Question

AISIX telemetry is intentionally split across several surfaces. Start with the surface that matches the operator's question, then correlate by request, model, provider, or attempt.

The exact fields and metric labels can evolve. Use Metrics and Usage Events and Access Logs and Request Correlation for the gateway version you operate.

Expose Prometheus Metrics Safely

AISIX serves Prometheus metrics through a dedicated metrics listener. The default path is /metrics, and the listener can be changed or disabled in startup configuration:

observability:
  metrics:
    prometheus:
      enabled: true
      path: "/metrics"

The dedicated listener defaults to 0.0.0.0:9090 when Prometheus metrics are enabled. The endpoint is unauthenticated by design, so keep that listener private and restrict network access.

After traffic reaches the gateway, verify that expected families appear:

curl -sS "http://127.0.0.1:9090/metrics" \
  | grep -E 'aisix_(requests|tokens|usage_events)'

Configuration status is published on every scrape, while traffic families can register only after their first observation. An empty traffic query immediately after startup does not by itself prove that metrics are misconfigured.

Use bounded labels for dashboards and alerts. AISIX documents selectable labels for request, model, provider, caller, team, and member context, but enabling every high-cardinality value can make the monitoring backend expensive. Select labels according to the operational question.

Read Access Logs with Streaming Timing in Mind

AISIX writes one structured access log entry per proxy request to the process logger. Depending on the request and available data, an entry can include:

• Method and path.
• Status and latency.
• Provider and resolved model.
• Caller API key ID.
• AISIX request ID.
• Token counts.
• Routing outcome.
• Provider request ID.

For both non-streamed and streamed requests in AISIX 1.4, the entry is written when the request or stream ends. A completed stream can therefore include its final outcome, token counts, provider request ID, served model, and routing counts when those values are available. If the caller disconnects during streaming, the terminal access log and usage event record status 499 and the usage observed before the disconnect.

AISIX also writes a separate provider call completed entry for each provider call that returns an ID. Use those entries to inspect individual retry or failover attempts; the single access log represents the request outcome returned to the caller. Gateways at AISIX 1.2.0 or earlier used the older response-open timing for streamed access logs, so confirm the deployed version before interpreting historical records.

Configure process logging through startup settings, for example:

observability:
  log_level: "info"

The RUST_LOG environment variable can override the configured log level. Confirm the effective runtime setting when a deployment produces more or fewer records than expected.

Correlate Requests Without Treating IDs as Identity

AISIX distinguishes three identifiers:

AISIX returns request_id in the x-aisix-request-id response header. By default, the gateway can accept a valid incoming x-aisix-request-id; startup configuration controls the accepted header list. Invalid or absent values cause AISIX to generate a UUID.

A caller-supplied correlation value is not authenticated user, team, or application identity. Use the authenticated caller API key and its bindings for ownership or authorization decisions. Use request IDs only to join telemetry.

Retries and failovers share the caller request ID while producing distinct attempt records. This makes it possible to reconstruct the full chain instead of examining only the final successful response.

Use Usage Events for Attempts and Consumption

Request metrics and usage events count different units:

• A request metric describes the status returned to the caller.
• A deployment metric describes an upstream attempt for supported routed endpoints.
• A usage event describes one recorded processing attempt, including some attempts stopped before an upstream call.

If a primary target returns 502 and fallback succeeds, the caller-facing request metric can record one 200. Usage events preserve the failed and successful attempts with the same request_id and different attempt_index values.

Each event can include outcome, token consumption, requested model alias, resolved model, latency, provider request ID, and cache information when AISIX can observe those values. In AISIX 1.4, the terminal usage event and access log agree on the final streamed outcome. A caller disconnect during a stream can produce status 499 with the tokens received before the disconnect.

Usage events are delivered through configured observability exporters rather than read from a local usage endpoint. Current exporters can send records to supported external collectors, logging systems, object storage, or warehouse workflows. Monitor delivery health and dropped-event signals before treating exported records as complete accounting data.

See Metrics and Usage Events for the current request-versus-attempt semantics and export fields.

Separate AISIX Cloud Request Logs from Audit Logs

AISIX Cloud provides two evidence trails:

• Request logs are built from gateway telemetry and help investigate request status, models, callers, latency, tokens, and attempts.
• Audit logs record control-plane changes and administrative actions.

A request log does not prove who changed a policy. An audit log does not replace request-level traffic evidence. Use both when investigating an incident caused by a configuration change.

Request logs depend on the gateway reporting telemetry to the correct AISIX Cloud environment. If expected traffic is absent:

1. Confirm the application used the intended gateway and environment.
2. Check the data-plane heartbeat.
3. Check whether aggregate usage is reaching the control plane.
4. Check exporter health separately when an external destination is also configured.

External exporter delivery occurs from the AISIX gateway to the destination. A record can exist in AISIX Cloud while a separate exporter fails because of destination credentials, network access, or receiver configuration.

Follow One Request Through the System

Use this workflow when a caller reports a slow or failed request:

1. Collect the x-aisix-request-id returned to the caller.
2. Find the AISIX access log and determine the caller-visible status and latency.
3. Inspect usage events with the same request ID and order them by attempt_index.
4. Separate gateway rejection, request assembly, provider failure, retry, and fallback.
5. Read provider_request_id from the relevant attempt when provider-side investigation is required.
6. Compare caller-visible latency with upstream-attempt latency and streaming timing.
7. Check the matching rate-limit, budget, guardrail, or routing policy when the gateway denied or redirected traffic.
8. Confirm metrics and exporter health before assuming an absent record means no traffic occurred.

For rate-limit investigations, pair this workflow with AISIX Rate Limit Policies. A provider 429 and an AISIX policy 429 have different owners and remediation paths.

Preserve the Product Boundary

AISIX AI Gateway is a separate Rust-native gateway with its own metrics, logs, headers, usage events, and AISIX Cloud workflows. It is not an observability mode running on Apache APISIX or the API7 Enterprise control plane.

API7 Gateway and Apache APISIX use their own logging, metrics, tracing, and AI plugin integrations. Their signals can feed the same monitoring backend, but field names, configuration, request identity, timing, and feature availability should be documented separately.

Operator Checklist

• Keep the dedicated Prometheus listener private.
• Send traffic before expecting lazily registered metric families.
• Select metric labels deliberately and control cardinality.
• Treat AISIX 1.4 streamed access logs as terminal request records; account for the older response-open behavior only when reviewing gateways at 1.2.0 or earlier.
• Use usage events and provider call completed entries to inspect individual retries, failovers, and attempt-level consumption.
• Treat request IDs as correlation values, not authenticated identities.
• Preserve provider request IDs for upstream support workflows.
• Monitor usage-event exporter health and delivery failures.
• Keep AISIX Cloud request logs and control-plane audit logs distinct.
• Verify exact fields and retention against the deployed AISIX version.

For the complete observability design, continue with the AI Gateway Observability guide. For implementation details, use AISIX Metrics and Usage Events, Access Logs and Request Correlation, and evaluate AISIX AI Gateway.