AISIX AI Gateway → OpenObserve

AISIX can export traces directly from the gateway to OpenObserve over OTLP/HTTP. This captures gateway requests, logical model calls, and provider attempts without adding an instrumentation library to every calling application.

This guide uses AISIX 1.2.0 and OpenObserve 1.0.0.

Prerequisites

• AISIX 1.2.0 with a working model and API key
• An OpenObserve account, either Cloud or self-hosted
• Your OpenObserve organization ID and ingestion Authorization header
• The hostname that AISIX uses to reach OpenObserve

In OpenObserve, open Data Sources, select Traces, and copy the OTLP/HTTP endpoint and authorization header for your organization.

Configure the AISIX exporter

Add an observability exporter to your AISIX resources file. Keep the complete OTLP traces path, including /v1/traces, in endpoint.

observability_exporters:
  - name: openobserve-otlp
    kind: otlp_http
    endpoint: https://<openobserve-host>/api/<organization>/v1/traces
    headers:
      Authorization: ${OPENOBSERVE_AUTH_HEADER}
      stream-name: aisix
    sample_rate: 1
    content_mode: metadata_only

Set the copied authorization value in the AISIX process environment instead of writing the credential into the resources file:

export OPENOBSERVE_AUTH_HEADER='Basic <base64-encoded-credentials>'

sample_rate: 1 makes every request eligible for export while you verify the integration. Choose a sampling policy appropriate for your traffic volume after validation.

metadata_only excludes prompt, completion, and system-instruction content from exported spans. Trace metadata can still contain identifiers, source addresses, and user-agent values, so restrict access to the destination stream and apply your normal retention policy.

Validate the resources and start or reload AISIX using your normal deployment workflow:

aisix validate --resources /etc/aisix/resources.yaml

Send a traced request

Send a chat-completions request through an existing AISIX model. The optional traceparent header connects the gateway spans to an upstream distributed trace.

curl -i http://localhost:3000/v1/chat/completions \
  -H "Authorization: Bearer ${GATEWAY_CALLER_KEY}" \
  -H "Content-Type: application/json" \
  -H "traceparent: 00-11111111111111111111111111111111-2222222222222222-01" \
  -d '{
    "model": "your-aisix-model",
    "messages": [
      {"role": "user", "content": "Explain distributed tracing in one sentence."}
    ]
  }'

Record the x-aisix-request-id response header. It provides a direct correlation value when searching the exported spans.

What gets captured

A successful chat-completions request can produce a gateway SERVER span, a logical model-call CLIENT span, and one or more provider-attempt CLIENT spans. Retries or fallback routing can therefore appear as additional attempts under the same logical call.

Attribute availability depends on the request type and the metadata returned by the upstream provider.

View the trace in OpenObserve

1. In OpenObserve, go to Traces.
2. Select the aisix stream.
3. Filter on aisix_request_id using the value from the response header.
4. Open the trace to inspect the gateway, logical-call, and provider-attempt spans.

If the caller supplied a valid W3C traceparent header, the AISIX gateway span appears as a child of that remote parent and preserves the incoming trace ID.

For the versioned setup used to validate this guide, OpenObserve displayed one chat.completions trace from aisix-dp with three connected spans and zero errors.

Troubleshooting

OpenObserve returns 401

Copy the complete Authorization header from the OpenObserve trace-ingestion page and confirm that the variable is available to the AISIX process. Do not commit the value to source control.

The aisix stream does not appear

Confirm that the endpoint contains your organization and the complete /v1/traces suffix. Also verify the stream-name: aisix header and send at least one request through AISIX after the exporter is loaded.

No spans appear for a request

Check the AISIX exporter logs, the configured sampling rate, network access from AISIX to OpenObserve, and the selected time range in the Traces view.

Read More

• AISIX observability exporters
• AISIX source repository
• Exploring traces in OpenObserve
• OpenTelemetry ingestion in OpenObserve