Observability Exporters

Observability exporters send request telemetry from the gateway to destinations you control. Use them when telemetry delivery should be managed as a dynamic gateway resource instead of only through startup logging and metrics settings.

In this guide, you will create an OTLP/HTTP exporter with the Admin API, then review the other exporter kinds and delivery 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.
• jq to print the exporter create response and capture the returned ID.

Choose an Exporter Kind

Choose the exporter kind based on where the gateway should send request telemetry:

Kind	Use When
otlp_http	You already collect traces through an OTLP/HTTP collector or vendor endpoint.
object_store	You want batched NDJSON request events in object storage.
aliyun_sls	You use Alibaba Cloud Simple Log Service as the log destination.
datadog	You use Datadog Logs HTTP intake.

The gateway sends exporter traffic. The control plane stores the exporter resource but does not open a connection to the exporter destination.

Configure an OTLP Exporter

The example below creates an OTLP/HTTP exporter for a local collector endpoint.

Set the values used by the example:

export AISIX_ADMIN_KEY="admin-local-only-change-me"
export OTLP_ENDPOINT="http://localhost:4318/v1/traces"

Create the exporter and save the response:

EXPORTER_RESPONSE=$(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" \
  -d '{
    "name": "local-otlp",
    "kind": "otlp_http",
    "endpoint": "'"${OTLP_ENDPOINT}"'"
  }')

Print the response and copy the returned ID:

printf '%s\n' "${EXPORTER_RESPONSE}" | jq .
EXPORTER_ID=$(printf '%s\n' "${EXPORTER_RESPONSE}" | jq -r '.id // empty')

You should see a response similar to the following:

{
  "id": "b46a9f5d-6a4d-4bb1-ae2c-4ab1b22f5e80",
  "value": {
    "name": "local-otlp",
    "enabled": true,
    "kind": "otlp_http",
    "endpoint": "http://localhost:4318/v1/traces"
  },
  "revision": 1
}

The returned ID is used later to update or delete the exporter.

For a remote OTLP destination, use an HTTPS endpoint and add any static headers required by the destination:

{
  "name": "prod-otlp",
  "kind": "otlp_http",
  "endpoint": "https://collector.example.com/v1/traces",
  "headers": {
    "Authorization": "Bearer ***"
  }
}

Header values are stored in the dynamic resource. Treat them with the same care as provider-key secrets: restrict access to the config store and keep the gateway trust boundary explicit.

Configure Log and Object Storage Exporters

Use log and object-storage exporters when request telemetry should land outside an OTLP trace backend.

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. Use auth_mode: "cloud_identity" only for S3 or GCS when the gateway runs with an attached cloud identity that can write to the bucket.

For Aliyun 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"
}

For 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 dynamic resource by using credential references or cloud identity. The gateway resolves those credentials locally when it builds the exporter sink.

Control Content Capture

Exporter delivery is metadata-oriented by default. It includes request status, token counts, model and provider identifiers, request IDs, finish reason, and timing.

Prompt and response bodies are not included by default. SLS and Datadog exporters can opt in to full content capture:

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

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

Review Exporter Delivery

Exporter resources default to enabled. Set enabled: false when you want to keep an exporter configured but skip delivery.

Use HTTPS for non-local exporter endpoints. The Admin API allows plain HTTP only for local development targets such as localhost, loopback addresses, and supported test service names.

If telemetry does not arrive downstream, verify the destination, credentials or credential reference, and exporter status. If the destination expects a specific path, set the endpoint to the exact receiver path.

Delete the example exporter when you finish testing:

curl -sS -X DELETE "http://127.0.0.1:3001/admin/v1/observability_exporters/${EXPORTER_ID}" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}"

Next Steps

You have now configured an observability exporter and reviewed delivery behavior. Continue with Troubleshooting to diagnose startup, configuration, upstream, policy, and managed gateway issues.