可观测性导出器

可观测性导出器会将网关的用量事件发送到你控制的目标。当请求遥测需要离开网关运行时，并进入链路追踪、日志、存储或计费系统时，可以使用导出器。

本指南将使用 Admin API 在自托管网关上创建一个 OTLP/HTTP 导出器，然后介绍其它导出器类型和投递行为。

准备工作

请先准备以下内容：

一个 Admin 和代理监听器都可用的自托管 AISIX 网关。
网关 config.yaml 中的 Admin Key。
计划使用的导出器对应的遥测目标。

选择导出器类型

自托管和托管 AISIX 网关支持相同的导出器类型。自托管网关在 JSON 中使用 Admin API 取值，而托管控制面会为同样的底层类型展示控制台标签：

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

AISIX 会将请求遥测从网关发送到所选目标。

完整的导出器 schema 和各类型专属字段请参见 Admin API 参考。

配置 OTLP 导出器

下面示例为远程 collector 端点创建一个 OTLP/HTTP 导出器。

设置示例使用的值：

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

创建导出器：

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
  }'

❶ 只有当 OTLP 目标要求时才设置静态请求头。请求头值会存储在导出器资源中，并可能被 Admin API 返回，因此请相应地限制 Admin API 和配置存储访问。

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

你应该会看到类似下面的响应：

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

如果后续需要更新或删除该导出器，请保存返回的 ID。

导出器资源默认启用。如果希望保存配置但暂时不发送遥测，请设置 enabled: false。

配置其它导出器

当请求遥测需要写入日志或对象存储，而不是 OTLP trace 后端时，请使用以下导出器类型。

对象存储

对于对象存储，请选择存储服务提供方、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"
}

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

配置内容采集

导出器投递默认以元数据为主，包括请求状态、Token 计数、模型和服务提供方标识、请求 ID、finish reason 和时间信息。

默认不包含提示词和响应正文。OTLP/HTTP、SLS 和 Datadog 导出器可以选择启用完整内容采集。

启用完整内容采集

在自托管部署中，请把以下字段加入你通过 Admin API 创建或更新的导出器资源：

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

在托管控制面中，请在导出器表单中将 Content mode 设置为 Full，并调整 Max content bytes。

只有当目标已获准接收最终用户提示词和响应文本时，才使用完整内容采集。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 标识解析后的模型资源。

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

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

托管控制面

托管控制面支持相同的导出器类型，但导出器配置归属于某个环境，并从控制台管理。

请在目标环境的 Observability 视图中创建导出器。控制台会收集目标字段、content mode 和各类型专属选项，然后将保存的导出器配置投射到该环境下挂载的托管网关。

配置导出器时，请记住以下托管网关细节：

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

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

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

下一步

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

准备工作​

选择导出器类型​

配置 OTLP 导出器​

配置其它导出器​

对象存储​

阿里云 SLS​

Datadog​

配置内容采集​

启用完整内容采集​

了解截断记录​

采集失败请求​

查看各端点采集的内容​

导出遥测中的模型字段​

托管控制面​

下一步​