Metrics and Logs
AISIX AI Gateway emits runtime telemetry through Prometheus metrics, access logs, response headers, and usage events. Prometheus metrics show traffic trends. Access logs and response headers support request-level investigation. Usage events provide the request records used by exporters and accounting workflows.
Each source supports a different operational question. Metrics show aggregate behavior. Logs and headers help investigate a specific response. Usage events provide data for export and accounting workflows.
Telemetry Sources
AISIX provides four telemetry sources for runtime monitoring and request investigation.
Prometheus Metrics
Prometheus metrics are suited for monitoring traffic trends, latency, token counters, cost counters, rate-limit outcomes, cache behavior, and exporter delivery health.
AISIX serves Prometheus metrics on the dedicated metrics listener at /metrics by default. You can change the path or disable the endpoint through the startup observability settings.
This endpoint is unauthenticated by design. Keep the dedicated metrics listener private.
Configure Prometheus exposure in the startup configuration:
observability:
metrics:
prometheus:
enabled: true
path: "/metrics"
Set a listener address when Prometheus should scrape metrics from an address other than the default.
Scrape the default self-hosted metrics endpoint:
curl -sS "http://127.0.0.1:9090/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.
Self-hosted and managed deployments expose /metrics through the 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. They 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, consumption details, the model alias the caller requested, and the resolved model that served the attempt when the gateway can observe those values.
Unlike Prometheus metrics or access logs, usage events are 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
Continue with Observability Exporters when usage events need to feed an external collector, log destination, object store, or warehouse workflow.