← Cloudflare AI Gateway / ai-gateway / observability

OpenTelemetry

AI Gateway umožňuje export trasování do backendů kompatibilních s OpenTelemetry, takže výkon požadavků AI můžete sledovat a analyzovat společně se svou stávající infrastrukturou pro observabilitu.

Přehled

Integrace OpenTelemetry (OTEL) automaticky exportuje trasovací spany pro AI požadavky zpracované vaším gateway. Tyto spany obsahují podrobné informace o:

Model a poskytovatel požadavku
Využití tokenů (vstupní a výstupní)
Prompty a completions požadavku
Odhady nákladů
Vlastní metadata

Tato integrace se řídí Specifikace OpenTelemetry ↗ pro distribuované trasování a používá formát OTLP (OpenTelemetry Protocol), který podporuje kódování JSON i protobuf.

Konfigurace

Chcete-li povolit trasování OpenTelemetry pro svůj gateway, nakonfigurujte v nastavení gateway jeden nebo více exportérů OTEL. Každý exportér přijímá:

URL (required): URL koncového bodu vašeho kolektoru OTEL
Hlavičky (optional): Další vlastní hlavičky, které se mají zahrnout do exportních požadavků. Pokud váš kolektor vyžaduje ověření, předejte ho zde (například Authorization: Bearer <token>).
Autorizace (optional): Odkaz na secret v Secrets Store obsahující hodnotu autorizační hlavičky vašeho kolektoru. Pokud je nastaveno, AI Gateway při běhu načte tajný klíč a odešle jej jako Authorization hlavičku u požadavků na export. Ve většině případů je jednodušší ověřování pomocí Hlavičky je jednodušší.
Typ obsahu (optional): Formát exportu: json (výchozí) nebo protobuf.

Konfigurace přes dashboard

Přejděte do svého AI Gateway v Cloudflare dashboardu.
Přejděte na Nastavení kartě.
Přidejte exportér OTEL s URL adresou koncového bodu vašeho kolektoru.
Pokud váš collector vyžaduje ověření, přidejte Authorization hlavičku v Hlavičky pole hodnotou vašeho tokenu.

Exportované atributy spanu

AI Gateway exportuje spany s následujícími atributy podle Semantic Conventions for Gen AI ↗:

Standard Attributes

Attribute	Typ	Popis
`gen_ai.request.model`	string	AI model použitý pro požadavek
`gen_ai.model.provider`	string	Poskytovatel AI (např. `openai`, `anthropic`)
`gen_ai.usage.input_tokens`	int	Počet spotřebovaných vstupních tokenů
`gen_ai.usage.output_tokens`	int	Počet vygenerovaných výstupních tokenů
`gen_ai.prompt_json`	string	Prompt/zprávy odeslané modelu, zakódované ve formátu JSON
`gen_ai.completion_json`	string	Completion/odpověď modelu zakódovaná ve formátu JSON
`gen_ai.usage.cost`	double	Odhadované náklady na požadavek

Custom Metadata

Veškerá vlastní metadata přidaná k vašim požadavkům prostřednictvím cf-aig-metadata hlavička bude rovněž zahrnuta jako atributy span. Díky tomu můžete propojit trasy s ID uživatelů, názvy týmů nebo dalším obchodním kontextem.

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!"}]
  }'

Výše uvedený požadavek bude obsahovat user_id a team jako další atributy spanu v exportovaném trasování.

Trace Context Propagation

AI Gateway podporuje šíření kontextu trasování, díky čemuž můžete spany AI Gateway propojit s trasováním své aplikace. Kontext trasování lze zadat pomocí vlastních hlaviček:

cf-aig-otel-trace-id (optional): 32znakový hexadecimální řetězec použitý jako trace ID
cf-aig-otel-parent-span-id (optional): 16znakový hexadecimální řetězec použitý jako parent span ID

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!"}]
  }'

Pokud jsou tyto hlavičky poskytnuty, span AI Gateway je použije k propojení s vaší existující trace. Pokud poskytnuty nejsou, AI Gateway automaticky vygeneruje nové trace ID.

Běžné OTEL backendy

Integrace OTEL v AI Gateway funguje s jakýmkoli backendem kompatibilním s OpenTelemetry, mimo jiné s:

Správnou adresu URL koncového bodu OTLP a požadavky na ověřování najdete v dokumentaci vaší platformy pro sledovatelnost.