Skip to main content
API7.ai Logo

Observability Exporters

Observability exporters send per-request usage events from the gateway to destinations used for tracing, logging, storage, or accounting. This guide configures an OTLP/HTTP exporter through the self-hosted Admin API, then explains destination choices, content capture, and managed-control-plane behavior.

Prerequisites​

Before starting, prepare the following:

  • A self-hosted AISIX gateway with the admin and proxy listeners available.
  • The admin key from the gateway config.yaml.
  • A telemetry destination for the exporter you plan to use.

Choose an Exporter Kind​

Self-hosted and managed AISIX gateways support the same exporter kinds. Self-hosted gateways use Admin API values in JSON, while the managed control plane shows dashboard labels for the same underlying kinds:

Admin API ValueDashboard LabelUse When
otlp_httpOTLP/HTTPYou already collect traces through an OTLP/HTTP collector or vendor endpoint.
object_storeObject storageYou want batched NDJSON request events in Amazon S3, S3-compatible storage, Google Cloud Storage, or Azure Blob.
datadogDatadogYou use Datadog Logs HTTP intake.
aliyun_slsAlibaba Cloud SLSYou use Alibaba Cloud Simple Log Service as the log destination.

The gateway sends telemetry directly to the selected destination. For the complete resource schema and kind-specific fields, see the Admin API Reference.

Configure an OTLP Exporter​

Set the admin key, collector endpoint, and authorization header used by the example:

# Replace with your values
export AISIX_ADMIN_KEY="YOUR_ADMIN_KEY"
# For local testing, replace the OTLP_ENDPOINT value below with http://localhost:4318/v1/traces.
# Remove the headers block from the create request.
export OTLP_ENDPOINT="https://collector.example.com/v1/traces"
export OTLP_AUTH_HEADER="Bearer YOUR_COLLECTOR_TOKEN"

Create the exporter:

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/observability_exporters" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
  {
    "name": "prod-otlp",
    "kind": "otlp_http",
    "endpoint": "${OTLP_ENDPOINT}",
    "headers": {
      "Authorization": "${OTLP_AUTH_HEADER}"
    },
    "sample_rate": 0.25
  }
EOF

❶ Set static headers only when the OTLP destination requires them. Header values are stored in the exporter resource and can be returned by the Admin API, so restrict Admin API and config-store access accordingly.

❷ sample_rate reduces span volume for this OTLP exporter. When omitted, AISIX exports every request.

You should see a response similar to the following. The authorization value is redacted in this example; the Admin API returns the configured header value.

{
  "id": "b46a9f5d-6a4d-4bb1-ae2c-4ab1b22f5e80",
  "value": {
    "name": "prod-otlp",
    "enabled": true,
    "kind": "otlp_http",
    "endpoint": "https://collector.example.com/v1/traces",
    "headers": {
      "Authorization": "Bearer REDACTED"
    },
    "sample_rate": 0.25
  },
  "revision": 1
}

Save the returned ID for later updates or deletion. Exporters are enabled by default. Set enabled: false to save the resource without sending telemetry.

Configure Other Exporters​

Use another exporter kind when telemetry should go to object storage or a logging service instead of an OTLP trace backend.

Object Storage​

For object storage, choose the storage provider, bucket, and key prefix. The default authentication mode uses a credential reference resolved by the gateway:

{
  "name": "request-events-s3",
  "kind": "object_store",
  "provider": "s3",
  "bucket": "acme-aisix-events",
  "prefix": "ai-gateway",
  "region": "us-east-1",
  "credential_ref": "acme_s3"
}

Object storage supports Amazon S3, Google Cloud Storage, Azure Blob, and S3-compatible targets. Cloud identity is supported only for S3 or GCS when the gateway has an attached identity that can write to the bucket. Use credential_ref for Azure Blob and for S3-compatible targets that require static credentials.

For an S3-compatible target such as MinIO, Cloudflare R2, or Alibaba Cloud OSS, set the target endpoint explicitly. Without an endpoint, the exporter uses the native AWS S3 endpoint.

Alibaba Cloud SLS​

Configure the endpoint host, project, log store, and credential reference:

{
  "name": "request-events-sls",
  "kind": "aliyun_sls",
  "endpoint": "ap-southeast-3.log.aliyuncs.com",
  "project": "acme-observability",
  "logstore": "ai-gateway",
  "credential_ref": "acme_sls"
}

Datadog​

Configure the Datadog site, service name, tags, and credential reference:

{
  "name": "request-events-datadog",
  "kind": "datadog",
  "site": "datadoghq.com",
  "service": "ai-gateway",
  "tags": ["team:platform", "tier:prod"],
  "credential_ref": "acme_datadog"
}

SLS, Datadog, and object-storage exporters keep destination credentials out of the exporter resource by using credential references or cloud identity. The gateway resolves those credentials locally when it sends telemetry.

Configure Content Capture​

Exporters include request status, token counts, model and provider identifiers, request IDs, finish reason, and timing by default. Prompt and response bodies remain excluded unless full content capture is enabled on an OTLP/HTTP, SLS, or Datadog exporter.

Enable Full Content Capture​

In self-hosted deployments, add these fields to the exporter resource you create or update with the Admin API:

{
  "content_mode": "full",
  "content_max_bytes": 131072
}

In the managed control plane, set Content mode to Full, then adjust Max content bytes in the exporter form.

Use full content capture only when the destination is approved to receive end-user prompt and response text. AISIX applies the configured byte cap independently to captured prompt and response fields.

Understand Truncated Records​

When valid JSON exceeds content_max_bytes, AISIX first tries to reduce the value structurally so the exported field remains valid JSON. If the reduced value still cannot fit the configured cap, AISIX falls back to a UTF-8-safe byte cut. The captured prompt is the serialized request body and follows the same behavior.

ContentTruncation Behavior
Long stringKeeps a prefix and adds the inline marker ...[aisix: truncated, N bytes total].
Base64 data URIReplaces the encoded data with a size placeholder.
Long arrayKeeps head and tail samples around an {"_aisix_truncated": true, "omitted_items": N} element that accounts for every omitted item.
Non-JSON content, or JSON that cannot fit after structural reductionCuts the value at a UTF-8 character boundary.

When truncation occurs, OTLP records include aisix.content_truncated: true. Datadog and SLS records include content_truncated: true.

Capture Failed Requests​

Full content capture applies to the supported AI proxy endpoint types summarized below. It does not apply to A2A, MCP, Realtime, passthrough, or job and batch telemetry.

On /v1/chat/completions, /v1/messages, and /v1/responses, a failure that produces a usage event after request parsing records the request body in the prompt field, except for 401 and 403 responses. This includes input guardrail blocks (422), upstream failures other than 401 and 403, and validation failures after parsing, such as an empty messages array. When data masking runs, AISIX captures the post-mask request body. Malformed JSON is rejected before a usage event is created and is not captured.

The following boundaries also apply:

  • Caller authentication failures are rejected before a usage event is created.
  • When every routing target fails, the last attempt's record carries the prompt.
  • A response-side guardrail block never captures the blocked output.

These boundaries keep rejected credentials and blocked output out of exported content while retaining the request context needed to investigate other failures.

Review Captured Content by Endpoint​

Endpoint TypeCaptured Response
Text generationResponse text.
Embeddings, rerank, and image generationFull response JSON.
Audio transcriptionReturned transcript. Uploaded audio is not captured; its SHA-256 checksum is recorded alongside the request's text fields.
Text to speechBinary speech response is not captured.

Model Fields in Exported Telemetry​

Usage telemetry records both the model alias requested by the caller and the model that served an attempt when those values differ. This distinction matters for routed and ensemble traffic, where one caller-facing alias can resolve to several target calls.

Destinations render these values in their own telemetry format. OTLP traces use the following fields:

  • gen_ai.request.model contains the caller-requested alias.
  • gen_ai.response.model contains the concrete response model version when the provider reports one.
  • aisix.model_id identifies the resolved model resource.

Datadog logs use aisix.requested_model for the caller-requested alias, gen_ai.response.model for the concrete response model version, and aisix.model_id for the resolved model resource.

Object storage and Alibaba Cloud SLS retain usage-event field names such as requested_model, model_id, and provider_model_version.

Managed Control Plane​

The managed control plane supports the same exporter kinds, but exporter configuration belongs to an environment and is managed from the dashboard.

Create exporters from the target environment's Observability view. The dashboard collects the destination fields, content mode, and any kind-specific options, then projects the saved exporter configuration to the managed gateways attached to that environment.

The following behavior applies to exporters projected to managed gateways:

  • The managed gateway sends request telemetry directly to your destination. The control plane does not proxy exported telemetry.
  • Prompt and response content stays on the gateway unless you enable full content capture on an exporter.
  • Credential references are resolved by the managed gateway. When a destination needs runtime credentials, the dashboard shows the environment variables to configure on the gateway.
  • Delivery health comes from managed-gateway heartbeat data and shows whether batches are being shipped or whether the gateway is reporting a delivery error.

For OTLP/HTTP exporters, the dashboard provides presets for Langfuse, Honeycomb, and Grafana Cloud Tempo, and accepts custom OTLP endpoints.

The trace UI URL template is optional. Use it when the Request Logs view should link a request record to an external trace UI. The template must include {request_id} so the control plane can replace it with the request ID from the log record.

Next Steps​

Continue with Load Logs into Snowflake to query object-storage telemetry in Snowflake. Use Metrics and Logs to correlate exported records with gateway metrics, access logs, and response headers.