OpenTelemetry

Last updated Sep 24, 2026 AI Gateway supports exporting traces to OpenTelemetry-compatible backends, enabling you to monitor and analyze AI request performance alongside your existing observability infrastructure.

Overview

The OpenTelemetry (OTEL) integration automatically exports trace spans for AI requests processed through your gateway. These spans include detailed information about:

  • Request model and provider
  • Token usage (input and output)
  • Request prompts and completions
  • Cost estimates
  • Custom metadata

This integration follows the OpenTelemetry specification ↗︎ for distributed tracing and uses the OTLP (OpenTelemetry Protocol) format, supporting both JSON and protobuf encoding.

Configuration

To enable OpenTelemetry tracing for your gateway, configure one or more OTEL exporters in your gateway settings. Each exporter accepts:

  • URL (required): The endpoint URL of your OTEL collector
  • Headers (optional): Additional custom headers to include in export requests. If your collector requires authentication, pass it here (for example, Authorization: Bearer <token>).
  • Authorization (optional): A reference to a secret in Secrets Store containing your collector's authorization header value. When set, AI Gateway resolves the secret at runtime and sends it as the Authorization header on export requests. For most use cases, passing authentication via Headers is simpler.
  • Content type (optional): The export format — json (default) or protobuf.

Configuration via Dashboard

  1. Navigate to your AI Gateway in the Cloudflare dashboard.
  2. Go to Settings tab.
  3. Add an OTEL exporter with your collector endpoint URL.
  4. If your collector requires authentication, add an Authorization header in the Headers field with your token value.

Exported Span Attributes

AI Gateway exports spans with the following attributes following the Semantic Conventions for Gen AI ↗︎:

Standard Attributes

Attribute Type Description
gen_ai.request.model string The AI model used for the request
gen_ai.model.provider string The AI provider (e.g., openai, anthropic)
gen_ai.usage.input_tokens int Number of input tokens consumed
gen_ai.usage.output_tokens int Number of output tokens generated
gen_ai.prompt_json string JSON-encoded prompt/messages sent to the model
gen_ai.completion_json string JSON-encoded completion/response from the model
gen_ai.usage.cost double Estimated cost of the request

Custom Metadata

Any custom metadata added to your requests via the cf-aig-metadata header will also be included as span attributes. This allows you to correlate traces with user IDs, team names, or other business context.

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

The above request will include user_id and team as additional span attributes in the exported trace.

Note

Custom metadata attributes that start with gen_ai. are reserved for standard GenAI semantic conventions and will not be added as custom attributes.

Trace Context Propagation

AI Gateway supports trace context propagation, allowing you to link AI Gateway spans with your application's traces. You can provide trace context using custom headers:

  • cf-aig-otel-trace-id (optional): A 32-character hex string to use as the trace ID
  • cf-aig-otel-parent-span-id (optional): A 16-character hex string to use as the 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!"}]
  }'

When these headers are provided, the AI Gateway span will use them to link with your existing trace. If not provided, AI Gateway will generate a new trace ID automatically.

Common OTEL Backends

AI Gateway's OTEL integration works with any OpenTelemetry-compatible backend, including:

Note

AI Gateway supports both OTLP/JSON and OTLP/protobuf export formats. Use the Content type setting to choose the format your collector expects.

Refer to your observability platform's documentation for the correct OTLP endpoint URL and authentication requirements.

Was this helpful?

YesNo

On this page

OpenTelemetry - 图1Docs

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/ai-gateway/observability/otel-integration/#page","headline":"OpenTelemetry","description":"Export AI Gateway trace spans to OpenTelemetry-compatible backends for distributed tracing and performance monitoring.","url":"https://developers.cloudflare.com/ai-gateway/observability/otel-integration/","inLanguage":"en","image":"https://developers.cloudflare.com/ai-gateway/observability/otel-integration/og.png?v=b0737f4554eb83aa","dateModified":"2026-09-24","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Track organization-wide AI spend, attribute usage to identities, and detect anomalous sessions in AI Gateway. title: User Insights image: https://developers.cloudflare.com/ai-gateway/observability/user-insights/og.png?v=7018640ca004e655

Skip to content

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/ai-gateway/llms.txt
Use this file to discover all available pages before exploring further.