OpenTelemetry

AI Gateway 支持将跟踪导出到兼容 OpenTelemetry 的后端，使你能够在现有可观测性基础设施旁监控和分析 AI 请求性能。

概览

OpenTelemetry (OTEL) 集成会自动为通过 gateway 处理的 AI 请求导出跟踪 span。这些 span 包含以下详细信息：

请求模型和提供商
Token 使用量（输入和输出）
请求提示和补全
费用估算
自定义元数据

此集成遵循分布式跟踪的 OpenTelemetry 规范 ↗，并使用 OTLP（OpenTelemetry Protocol）格式，同时支持 JSON 和 protobuf 编码。

配置

要为 gateway 启用 OpenTelemetry 跟踪，请在 gateway 设置中配置一个或多个 OTEL 导出器。每个导出器接受：

URL（必填）：OTEL collector 的端点 URL
Headers（可选）：要包含在导出请求中的额外自定义标头。如果 collector 需要身份验证，请在此处传递（例如，Authorization: Bearer <token>）。
Authorization（可选）：对 Secrets Store 中密钥的引用，该密钥包含 collector 的授权标头值。设置后，AI Gateway 会在运行时解析该密钥，并将其作为导出请求上的 Authorization 标头发送。对于大多数用例，通过 Headers（标头） 传递身份验证更简单。
Content type（可选）：导出格式 — json（默认）或 protobuf。

通过仪表板配置

在 Cloudflare 仪表板中导航到你的 AI Gateway。
前往 Settings（设置） 选项卡。
添加一个带有 collector 端点 URL 的 OTEL 导出器。
如果 collector 需要身份验证，在 Headers（标头） 字段中添加带有令牌值的 Authorization 标头。

导出的 Span 属性

AI Gateway 按照 Gen AI 语义约定 ↗ 导出带有以下属性的 span：

标准属性

属性	类型	说明
`gen_ai.request.model`	string	请求所用的 AI 模型
`gen_ai.model.provider`	string	AI 提供商（例如 `openai`、`anthropic`）
`gen_ai.usage.input_tokens`	int	消耗的输入 token 数量
`gen_ai.usage.output_tokens`	int	生成的输出 token 数量
`gen_ai.prompt_json`	string	发送到模型的 JSON 编码提示/消息
`gen_ai.completion_json`	string	来自模型的 JSON 编码补全/响应
`gen_ai.usage.cost`	double	请求的估算费用

自定义元数据

通过 cf-aig-metadata 标头添加到请求的任何自定义元数据也会作为 span 属性包含。这允许你将跟踪与用户 ID、团队名称或其他业务上下文关联。

curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai/chat/completions \
  --header 'Authorization: Bearer {api_token}' \
  --header 'Content-Type: application/json' \
  --header 'cf-aig-metadata: {"user_id": "user123", "team": "engineering"}' \
  --data '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

上述请求将在导出的跟踪中把 user_id 和 team 作为额外的 span 属性包含。

跟踪上下文传播

AI Gateway 支持跟踪上下文传播，允许你将 AI Gateway span 与应用的跟踪关联。你可以使用自定义标头提供跟踪上下文：

cf-aig-otel-trace-id（可选）：用作跟踪 ID 的 32 字符十六进制字符串
cf-aig-otel-parent-span-id（可选）：用作父 span ID 的 16 字符十六进制字符串

curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai/chat/completions \
  --header 'cf-aig-otel-trace-id: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6' \
  --header 'cf-aig-otel-parent-span-id: a1b2c3d4e5f6g7h8' \
  --header 'Authorization: Bearer {api_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

提供这些标头时，AI Gateway span 将使用它们与现有跟踪关联。如果未提供，AI Gateway 将自动生成新的跟踪 ID。

常见 OTEL 后端

AI Gateway 的 OTEL 集成适用于任何兼容 OpenTelemetry 的后端，包括：

请参阅你的可观测性平台文档，了解正确的 OTLP 端点 URL 和身份验证要求。