可观测性导出器

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

本指南将使用 Admin API 创建 OTLP/HTTP 导出器，并说明其它导出器类型和投递行为。

准备工作

请先准备以下内容：

一个 Admin 和代理监听器都可用的自托管 AISIX 网关。
网关 config.yaml 中的 Admin Key。
计划使用的导出器对应的遥测目标。
安装 jq，用于打印导出器创建响应并捕获返回的 ID。

选择导出器类型

请根据网关需要将请求遥测发送到哪里来选择导出器类型：

类型	适用场景
`otlp_http`	已经通过 OTLP/HTTP collector 或厂商端点收集 trace。
`object_store`	希望将批量 NDJSON 请求事件写入对象存储。
`aliyun_sls`	使用阿里云日志服务作为日志目标。
`datadog`	使用 Datadog Logs HTTP intake。

导出器流量由网关进程发送。创建导出器资源本身不会测试目标连通性。

配置 OTLP 导出器

下面示例为本地 collector 端点创建 OTLP/HTTP 导出器。

设置示例使用的值：

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

创建导出器并保存响应：

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}"'",
    "sample_rate": 1.0
  }')

打印响应并复制返回的 ID：

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

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

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

返回的 ID 后续可用于更新或删除导出器。

对于远程 OTLP 目标，请使用 HTTPS 端点，并添加目标要求的静态请求头：

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

请求头值会存储在动态资源中。请像对待服务提供方密钥 secret 一样谨慎处理：限制配置存储访问，并保持清晰的网关信任边界。

可以使用 sample_rate 降低单个导出器的 OTLP span 数量。该值是 0 到 1 的小数；省略时，AISIX 会向该 OTLP 导出器导出每个请求。

配置其它导出器

当请求遥测需要落到 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 使用 auth_mode: "cloud_identity"。

对于阿里云 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 和对象存储导出器通过凭证引用或云身份，让目标凭证不直接进入动态资源。网关在构建导出器 sink 时会在本地解析这些凭证。

配置内容采集

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

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

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

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

查看模型归因

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

OTLP 导出器使用 gen_ai.request.model 表示调用方请求的别名，使用 aisix.model_id 表示解析后的模型资源；当服务提供方报告具体响应模型版本时，使用 gen_ai.response.model。其它导出器类型会在其目标格式中保留相同底层用量字段。

管理导出器投递

导出器资源默认启用。如果希望保留导出器配置但暂时跳过投递，请设置 enabled: false。

非本地导出器端点请使用 HTTPS。Admin API 只允许 localhost、loopback 地址和受支持测试服务名等本地开发目标使用明文 HTTP。

如果遥测没有到达下游，请验证目标、凭证或凭证引用以及导出器状态。如果目标要求特定路径，请将导出器端点设置为精确接收路径。

测试完成后删除示例导出器：

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

下一步

你已经配置了可观测性导出器，并了解了投递行为。当你希望在 Snowflake 中查询导出的请求遥测时，请继续阅读将请求日志加载到 Snowflake。

准备工作​

选择导出器类型​

配置 OTLP 导出器​

配置其它导出器​

配置内容采集​

查看模型归因​

管理导出器投递​

下一步​