可观测性导出器

可观测性导出器会将网关用量事件发送到用于链路追踪、日志记录、存储或记账的目标。本指南将介绍如何通过 AISIX Cloud 或开源 AISIX 网关配置 OTLP/HTTP 导出器，并说明目标选择、内容采集和投递行为。

准备工作

请先准备以下内容：

以下任一配置路径：
- AISIX Cloud，其中包含一个环境、已关联的网关和具备写入权限的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid Cloud 访问权限，请联系 API7。
- 加载声明式 resources.yaml 文件的开源 AISIX 网关。
计划使用的导出器对应的遥测目标。

对于 AISIX Cloud 示例，请导出 Admin API 基础 URL、Admin Token 和环境 ID：

export AISIX_CP="http://localhost:8080/api"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

选择导出器类型

两种配置路径都支持所有导出器类型。AISIX Cloud API 请求和资源文件条目通过 kind 值选择类型，控制台则显示同一底层类型对应的标签：

`kind` 值	控制台标签	适用场景
`otlp_http`	OTLP/HTTP	已经通过 OTLP/HTTP collector 或厂商端点收集 trace。
`object_store`	对象存储	希望将批量 NDJSON 请求事件写入 Amazon S3、S3 兼容存储、Google Cloud Storage 或 Azure Blob。
`datadog`	Datadog	使用 Datadog Logs HTTP 接收端。
`aliyun_sls`	阿里云 SLS	使用阿里云日志服务作为日志目标。

网关会将遥测直接发送到所选目标。

配置 OTLP 导出器

设置示例使用的收集器端点和授权请求头：

# 请替换为实际值
# 本地测试时，请将下面的 OTLP_ENDPOINT 值替换为 http://localhost:4318/v1/traces。
# 从创建请求中移除 headers 块。
export OTLP_ENDPOINT="https://collector.example.com/v1/traces"
export OTLP_AUTH_HEADER="Bearer YOUR_COLLECTOR_TOKEN"

AISIX Cloud

创建导出器并获取其 ID：

EXPORTER_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/observability_exporters" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-otlp",
    "kind": "otlp_http",
    "endpoint": "'"${OTLP_ENDPOINT}"'",
    "headers": {
      "Authorization": "'"${OTLP_AUTH_HEADER}"'"
    },
    "sample_rate": 0.25
  }' | jq -r '.observability_exporter.id')

❶ 只有当 OTLP 目标要求时才设置静态请求头。请求头值会加密存储，并且读取操作绝不会返回这些值。

❷ sample_rate 会降低该 OTLP 导出器的 span 数量。省略时，AISIX 会导出每个请求。

获取导出器，确认存储的配置：

curl -sS "$AISIX_CP/environments/$ENV_ID/observability_exporters/$EXPORTER_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN"

你应该会看到类似下面的响应。读取操作通过 header_keys 暴露已配置的请求头名称，并通过 headers_set 确认已存储请求头值；但绝不会返回请求头值本身。

{
  "observability_exporter": {
    "id": "b46a9f5d-6a4d-4bb1-ae2c-4ab1b22f5e80",
    "env_id": "0f2f6a1e-9d33-4a8f-9a6e-2a7b6a9c1d2e",
    "name": "prod-otlp",
    "enabled": true,
    "kind": "otlp_http",
    "endpoint": "https://collector.example.com/v1/traces",
    "header_keys": ["Authorization"],
    "headers_set": true,
    "sample_rate": 0.25,
    "created_at": "2026-07-22T08:30:00Z",
    "updated_at": "2026-07-22T08:30:00Z"
  }
}

保存 $EXPORTER_ID，以便后续更新或删除导出器。导出器默认启用。设置 enabled: false 可在不发送遥测的情况下保存资源。

开源 AISIX 网关

在 resources.yaml 的 observability_exporters 下添加导出器。使用环境变量插值可以避免将收集器 Token 写入文件：

resources.yaml
_format_version: "1"

observability_exporters:
  - name: prod-otlp
    kind: otlp_http
    endpoint: ${OTLP_ENDPOINT}
    headers:
      Authorization: ${OTLP_AUTH_HEADER}
    sample_rate: 0.25

验证文件：

aisix validate --resources resources.yaml

在进程环境中设置 OTLP_ENDPOINT 和 OTLP_AUTH_HEADER，然后启动或重启网关。只有当这些变量已经可用于运行中的进程时，才重新加载网关。导出器默认启用；添加 enabled: false 可保留条目但不发送遥测。

当遥测需要发送到对象存储或日志服务，而不是 OTLP trace 后端时，请使用其他导出器类型。使用 AISIX Cloud 时，将以下对象之一作为 POST $AISIX_CP/environments/$ENV_ID/observability_exporters 的请求体。

配置其他导出器

对象存储

对于对象存储，请选择存储服务提供方、bucket 和对象键前缀。默认认证模式使用由网关解析的凭证引用：

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

对象存储支持 Amazon S3、Google Cloud Storage、Azure Blob 和 S3 兼容目标。只有当网关运行时带有可写入 bucket 的附加身份时，才对 S3 或 GCS 使用云身份。对于 Azure Blob，以及要求静态凭证的 S3 兼容目标，请使用 credential_ref。

对于 MinIO、Cloudflare R2 或阿里云 OSS 等 S3 兼容目标，请显式设置目标端点。未设置端点时，S3 导出器会使用原生 AWS S3 端点。

阿里云 SLS

配置端点主机、project、log store 和凭证引用：

{
  "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

配置 Datadog site、服务名称、标签和凭证引用：

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

对于资源文件路径，请在 observability_exporters 下添加相应的一个或多个条目：

resources.yaml
_format_version: "1"

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

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

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

只保留实际使用的目标，然后按照 OTLP 示例所述验证资源文件并启动或重新加载网关。

SLS、Datadog 和对象存储导出器通过凭证引用或云身份，让目标凭证不进入导出器资源。网关发送遥测时会在本地解析这些凭证。

配置内容采集

导出器默认包含请求状态、Token 计数、模型和服务提供方标识、请求 ID、finish reason 和时间信息，但不包含提示词和响应正文。OTLP/HTTP、SLS 和 Datadog 导出器可以选择启用完整内容采集。

启用完整内容采集

创建导出器时添加 content_mode 和 content_max_bytes。在 AISIX Cloud 中，可以使用相同字段修补现有导出器：

curl -sS -X PATCH "$AISIX_CP/environments/$ENV_ID/observability_exporters/$EXPORTER_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content_mode": "full",
    "content_max_bytes": 131072
  }'

在控制台中，将导出器表单的 Content mode 设置为 Full，然后调整 Max content bytes。

对于资源文件路径，请将这些字段添加到导出器条目中，然后验证并重新加载文件：

observability_exporters:
  - name: prod-otlp
    kind: otlp_http
    endpoint: ${OTLP_ENDPOINT}
    headers:
      Authorization: ${OTLP_AUTH_HEADER}
    content_mode: full
    content_max_bytes: 131072

只有当目标已获准接收最终用户提示词和响应文本时，才使用完整内容采集。AISIX 会根据配置的字节上限截断采集到的提示词和响应字段。

了解截断记录

有效 JSON 超过 content_max_bytes 时，AISIX 会先按结构缩减，使导出字段仍为有效 JSON。如果缩减后仍超过上限，则回退到 UTF-8 安全的字节截断。采集的提示词是序列化后的请求体，遵循同样规则。

内容	截断行为
长字符串	保留前缀，并追加 `...[aisix: truncated, N bytes total]` 行内标记。
Base64 数据 URI	用包含原始大小的占位符替换编码数据。
长数组	保留首尾样本，并插入 `{"_aisix_truncated": true, "omitted_items": N}` 元素，其中 `N` 统计全部省略项。
非 JSON 内容，或结构缩减后仍放不下的 JSON	在 UTF-8 字符边界处截断。

发生截断时，OTLP 记录包含 aisix.content_truncated: true，Datadog 和 SLS 记录包含 content_truncated: true。

采集失败请求

完整内容采集适用于下表汇总的受支持 AI 模型代理端点类型，不适用于 A2A、MCP、Realtime、透传、任务或批处理遥测。

在 /v1/chat/completions、/v1/messages 和 /v1/responses 上，请求解析后产生用量事件的失败会把请求体记录到 prompt 字段，但 401 和 403 响应除外。这包括输入安全护栏阻断（422）、除 401 和 403 之外的上游失败，以及解析后的校验失败（例如 messages 数组为空）。执行数据脱敏时，AISIX 采集脱敏后的请求体；格式错误的 JSON 会在创建用量事件前被拒绝，因此不会采集。

还应注意以下边界：

调用方认证失败会在创建用量事件前被拒绝。
所有路由目标都失败时，最后一次尝试的记录携带提示词。
响应侧安全护栏阻断不会采集被阻断的输出。

这些边界既避免导出被拒绝的凭证和阻断输出，也保留调查其它失败所需的请求上下文。

查看各端点采集的内容

端点类型	采集的响应
文本生成	响应文本。
Embeddings、Rerank 和图片生成	完整响应 JSON。
音频转录	返回的 transcript。上传音频不会被采集；其 SHA-256 校验和会与请求文本字段一起记录。
文本转语音	不采集二进制语音响应。

导出遥测中的模型字段

当调用方请求的模型别名与处理某次尝试的模型不同时，用量遥测会同时记录两者。这对路由和合议流量很重要，因为一个面向调用方的别名可能解析为多个目标模型调用。

不同目标会以各自的遥测格式呈现这些值。OTLP trace 使用以下字段：

gen_ai.request.model 包含调用方请求的别名。
gen_ai.response.model 包含服务提供方上报的具体响应模型版本。
aisix.model_id 标识解析后的模型资源。

网关协议 Span

A2A 或 MCP 调用不是模型推理，因此不会被编码成模型推理。A2A 导出为 invoke_agent <agent>，MCP 导出为 execute_tool <tool>，遵循 OpenTelemetry 生成式 AI 语义约定，并携带各自协议的细节：

A2A：gen_ai.agent.name、gen_ai.conversation.id（即 A2A 的 context），以及 aisix.a2a.operation、aisix.a2a.method、aisix.a2a.protocol_version、aisix.a2a.task_id、aisix.a2a.task_state、aisix.a2a.stream_event_count。
MCP：gen_ai.tool.name 和 aisix.mcp.server_name。

模型流量仍然使用 chat.completions 这一 span 名称和 gen_ai.operation.name: chat。在此变更之前按这两个值编写的链路查询也会匹配到 Agent 和工具调用，现在只会匹配模型流量——而这本来就是它想表达的含义。

Datadog 日志使用 aisix.requested_model 表示调用方请求的别名，使用 gen_ai.response.model 表示具体响应模型版本，并使用 aisix.model_id 表示解析后的模型资源。

对象存储和阿里云 SLS 会保留底层用量事件字段名称，例如 requested_model、model_id 和 provider_model_version。

AISIX Cloud 控制面

控制台在目标环境的 Observability 视图中管理相同的导出器资源。导出器表单会收集目标字段、内容模式和各类型专属选项。

无论导出器通过 API 还是控制台保存，控制面都会把配置投射到关联到该环境的 AISIX 网关。

以下行为适用于投射到 AISIX 网关的导出器：

AISIX 网关会直接将请求遥测发送到你的目标。控制面不会代理导出的遥测。
除非在导出器上启用完整内容采集，否则提示词和响应内容会留在网关上。
凭证引用由 AISIX 网关解析。当目标需要运行时凭证时，控制台会展示需要在网关上配置的环境变量。
投递健康状态来自网关心跳数据，会显示批次是否正在发送，或网关是否报告了投递错误。

对于 OTLP/HTTP 导出器，控制台提供 Langfuse、Honeycomb 和 Grafana Cloud Tempo 的预设，也接受自定义 OTLP 端点。

Trace UI URL 模板是可选的。当 Request Logs 视图需要将请求记录链接到外部 Trace UI 时使用它。模板必须包含 {request_id}，以便控制面用日志记录中的请求 ID 替换它。

下一步

如需在 Snowflake 中查询对象存储遥测，请继续阅读将请求遥测加载到 Snowflake。使用指标和日志将导出记录与网关指标、访问日志和响应头关联。

准备工作​

选择导出器类型​

配置 OTLP 导出器​

AISIX Cloud​

开源 AISIX 网关​

配置其他导出器​

对象存储​

阿里云 SLS​

Datadog​

配置内容采集​

启用完整内容采集​

了解截断记录​

采集失败请求​

查看各端点采集的内容​

导出遥测中的模型字段​

网关协议 Span​

AISIX Cloud 控制面​

下一步​