Metrics and Logs
AISIX AI Gateway emits several kinds of runtime telemetry. Prometheus metrics show trends across traffic. Access logs and response headers help explain one request. Usage events are the request records that exporters and accounting workflows use.
Each source answers a different operational question. Metrics show aggregate behavior, logs and headers help investigate a specific response, and usage events feed export and accounting workflows.
Telemetry Sources
AISIX exposes four telemetry sources that work together.
Prometheus Metrics
Prometheus metrics are the best starting point for traffic trends, latency, token counters, cost counters, rate-limit outcomes, cache behavior, and exporter delivery health.
The admin listener serves Prometheus metrics at /metrics by default. You can change the path, disable the endpoint, or serve metrics on a dedicated listener through the startup observability settings.
This endpoint is unauthenticated by design. Keep the admin listener or dedicated metrics listener private.
Configure Prometheus exposure in the startup configuration:
observability:
metrics:
prometheus:
enabled: true
path: "/metrics"
Add a listener address only when Prometheus should scrape metrics from a dedicated listener instead of the admin listener.
Scrape the default self-hosted metrics endpoint:
curl -sS "http://127.0.0.1:3001/metrics"
Metric families are registered lazily on first observation. Immediately after boot, GET /metrics can return an empty body. Send one model request, then check again for series such as aisix_requests_total and aisix_tokens_consumed_total.
AISIX emits native metric names with the aisix_ prefix. Use metrics to check request volume, latency, token usage, cost, traffic-control outcomes, routing behavior, cache behavior, and telemetry delivery. For exact metric names, labels, and label privacy notes, see Metrics Reference.
In self-hosted deployments, the local metrics endpoint usually lives on the admin listener. A managed gateway does not bind the local admin listener, so managed images expose /metrics through a dedicated metrics listener, bound to 0.0.0.0:9090 by default.
Access Logs
Access logs describe an individual proxy request. AISIX writes them through the process logger to the standard error stream, so they appear in the container or process logs collected by your runtime.
Configure process logging in the startup configuration:
observability:
log_level: "info"
access_log: true
The process environment can override the configured log level with the RUST_LOG environment variable.
Access log entries are emitted when a proxy request completes and include fields such as method, path, status, latency, provider, model, API key ID, request ID, token counts, and routing outcome when those values are available.
The access-log field is reserved in the current release. Proxy handlers still emit structured access logs, and there is no separate access-log format or sink setting. Collect the standard error stream with your runtime log pipeline when logs need to leave the gateway host.
Response Headers
Response headers provide caller-visible correlation and routing hints. They can identify the request, cache outcome, retry timing, or selected target on supported paths.
Use headers with logs and metrics to join a caller-visible response to backend telemetry. For exact header scope, see Headers and Error Codes.
Usage Events
Usage events are per-request records emitted by supported proxy paths after a request completes. They include request outcome and consumption details when the gateway can observe them.
Unlike Prometheus metrics or access logs, usage events are usually consumed through a sink rather than checked directly on a local endpoint. To send them to OTLP/HTTP, object storage, Aliyun SLS, or Datadog, configure an observability exporter.
Next Steps
You have now seen the main runtime telemetry AISIX emits. Continue with Observability Exporters to send request telemetry to external destinations.