← Cloudflare AI Gateway / ai-gateway / observability

OpenTelemetry

AI Gateway поддерживает экспорт трасс в бэкенды, совместимые с OpenTelemetry, что позволяет отслеживать и анализировать производительность AI-запросов наряду с существующей инфраструктурой наблюдаемости.

Обзор

Интеграция OpenTelemetry (OTEL) автоматически экспортирует спаны трассировки для запросов ИИ, обрабатываемых вашим шлюзом. Эти спаны содержат подробную информацию о:

Модель и провайдер запроса
Использование токенов (входные и выходные)
Промпты и completions запроса
Оценки стоимости
Пользовательские метаданные

Эта интеграция соответствует спецификация OpenTelemetry ↗ для распределенной трассировки и использует формат OTLP (OpenTelemetry Protocol), поддерживающий кодирование как в JSON, так и в protobuf.

Конфигурация

Чтобы включить трассировку OpenTelemetry для своего шлюза, настройте один или несколько экспортёров OTEL в настройках шлюза. Каждый экспортёр принимает:

URL (required): URL-адрес конечной точки вашего коллектора OTEL
Headers (optional): дополнительные пользовательские заголовки для запросов экспорта. Если ваш коллектор требует аутентификации, укажите её здесь (например, Authorization: Bearer <token>).
Авторизация (optional): ссылка на секрет в Secrets Store содержащий значение заголовка авторизации вашего коллектора. Если он задан, AI Gateway определяет secret во время выполнения и отправляет его как Authorization заголовок в запросах на экспорт. В большинстве случаев для аутентификации удобнее передавать Headers проще.
Тип контента (optional): формат экспорта: json (по умолчанию) или protobuf.

Настройка через Dashboard

Перейдите в свой AI Gateway в панели управления Cloudflare.
Перейдите в Настройки на вкладке.
Добавьте экспортёр OTEL с URL-адресом эндпойнта вашего коллектора.
Если вашему collector требуется аутентификация, добавьте Authorization заголовок в Headers поле значением вашего токена.

Экспортированные атрибуты спанов

AI Gateway экспортирует спаны со следующими атрибутами в соответствии с Semantic Conventions for Gen AI ↗:

Стандартные атрибуты

Attribute	Тип	Описание
`gen_ai.request.model`	string	Модель ИИ, использованная для запроса
`gen_ai.model.provider`	string	Провайдер ИИ (например, `openai`, `anthropic`)
`gen_ai.usage.input_tokens`	int	Количество потреблённых входных токенов
`gen_ai.usage.output_tokens`	int	Количество сгенерированных выходных токенов
`gen_ai.prompt_json`	string	Закодированный в формате JSON промпт/сообщения, отправленные модели
`gen_ai.completion_json`	string	Закодированный в формате JSON ответ модели (completion/response)
`gen_ai.usage.cost`	double	Расчётная стоимость запроса

Custom Metadata

Любые пользовательские метаданные, добавленные в ваши запросы через cf-aig-metadata заголовок также будет включён в атрибуты спана. Это позволяет сопоставлять трассировки с 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 в качестве дополнительных атрибутов спана в экспортированной трассировке.

Trace Context Propagation

AI Gateway поддерживает распространение контекста трассировки, что позволяет связывать спаны AI Gateway с трассами вашего приложения. Контекст трассировки можно передавать с помощью пользовательских заголовков:

cf-aig-otel-trace-id (optional): 32-значная шестнадцатеричная строка, используемая в качестве идентификатора трассировки
cf-aig-otel-parent-span-id (optional): 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 будет использовать их для связывания с уже существующей трассой. Если они не переданы, AI Gateway автоматически сгенерирует новый идентификатор трассировки.

Распространённые бэкенды OTEL

Интеграция AI Gateway с OTEL работает с любым бэкендом, совместимым с OpenTelemetry, включая:

Точный URL эндпойнта OTLP и требования к аутентификации уточняйте в документации своей платформы наблюдаемости.