Observability Exporters

Observability exporters send usage events from the gateway to destinations you control. Use them when request telemetry needs to leave the gateway runtime and feed tracing, logging, storage, or accounting systems.

In this guide, you will create an OTLP/HTTP exporter on a self-hosted gateway 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.

Choose an Exporter Kind

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

Self-Hosted Admin API Value	Cloud Dashboard Label	Use When
otlp_http	OTLP/HTTP	You already collect traces through an OTLP/HTTP collector or vendor endpoint.
object_store	Object storage	You want batched NDJSON request events in Amazon S3, S3-compatible storage, Google Cloud Storage, or Azure Blob.
datadog	Datadog	You use Datadog Logs HTTP intake.
aliyun_sls	Alibaba Cloud SLS	You use Alibaba Cloud Simple Log Service as the log destination.

AISIX sends request telemetry from the gateway to the selected destination.

For the complete exporter schema and kind-specific fields, see the Admin API Reference.

Configure an OTLP Exporter

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

Set the values used by the example:

export AISIX_ADMIN_KEY="YOUR_ADMIN_KEY"
# For local testing, set a local collector such as `http://localhost:4318/v1/traces` and 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" \
  -d '{
    "name": "prod-otlp",
    "kind": "otlp_http",
    "endpoint": "'"${OTLP_ENDPOINT}"'",
    "headers": {
      "Authorization": "'"${OTLP_AUTH_HEADER}"'"
    },
    "sample_rate": 0.25
  }'

❶ 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:

{
  "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 if you want to update or delete the exporter later.

Exporter resources are enabled by default. Set enabled: false when you want to save the configuration without sending telemetry yet.

Configure Other Exporters

Use these exporter kinds when request telemetry should be written to logs or object storage instead of 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 cloud identity only for S3 or GCS when the gateway runs with 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, an S3 exporter uses the native AWS S3 endpoint.

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 exporter configuration by using credential references or cloud identity. The gateway resolves those credentials locally when it sends telemetry.

Configure 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. OTLP/HTTP, SLS, and Datadog exporters can opt in to 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 AISIX Cloud, set Content mode to Full and 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 truncates captured prompt and response fields according to the configured byte cap.

Full content capture applies to every proxy endpoint. AISIX captures the prompt from the request body after any configured data masking.

For text-generation endpoints, the captured response is the response text. For embeddings, rerank, and image generation, it is the full response JSON. Uploaded audio files are never captured; exported content represents the file by its SHA-256 checksum alongside the request's text fields. Transcription output is captured as the returned transcript, but binary speech responses from text-to-speech requests are not captured.

Model Fields in Exported Telemetry

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

Different destinations render these values in their own telemetry format. OTLP traces and Datadog logs use OpenTelemetry GenAI-style names where a standard name exists. For example, gen_ai.request.model is the caller-requested alias, and gen_ai.response.model is the concrete response model version when the provider reports one. AISIX also adds aisix.model_id for the resolved model resource. Object storage and Alibaba Cloud SLS keep the underlying usage-event field names, such as requested_model, model_id, and provider_model_version.

AISIX Cloud Exporters

AISIX Cloud supports the same exporter kinds for managed gateways, but exporter configuration belongs to an environment and is managed from the Cloud 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.

Keep these managed-gateway details in mind when configuring exporters in Cloud:

• The managed gateway sends request telemetry directly to your destination. AISIX Cloud 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, Cloud offers dashboard presets for Langfuse, Honeycomb, and Grafana Cloud Tempo, and also accepts custom OTLP endpoints.

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

Next Steps

You have now configured an observability exporter and reviewed delivery behavior. Continue with Load Logs into Snowflake when you export request telemetry to object storage and want to query it in Snowflake.