Cloudflare AI Gateway tracing with Future AGI

Save this as otelcol.yaml. Everything it reads from the environment is listed in the next step.

extensions:
  # The endpoint has to be reachable from Cloudflare's network, so it must not be open: anyone who finds it
  # could write into your project.
  bearertokenauth/gateway:
    scheme: Bearer
    token: ${env:GATEWAY_TOKEN}

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318
        auth:
          authenticator: bearertokenauth/gateway
        # Put TLS in front of this (a load balancer, a reverse proxy, or a platform that terminates TLS for
        # you, such as Cloud Run), or set `tls:` here with cert_file and key_file.

processors:
  resource/future_agi:
    attributes:
      - key: project_name
        value: ${env:FI_PROJECT_NAME}
        action: upsert
      - key: project_type
        value: observe
        action: insert

  transform/cloudflare:
    error_mode: ignore
    trace_statements:
      - context: span
        statements:
          # Span type in Observe: a span with a model is an LLM span, anything else a chain.
          - set(attributes["fi.span.kind"], "LLM") where attributes["gen_ai.request.model"] != nil
          - set(attributes["fi.span.kind"], "CHAIN") where attributes["gen_ai.request.model"] == nil
          # Cloudflare sends gen_ai.provider.name; its page names gen_ai.model.provider. Observe reads the first.
          - set(attributes["gen_ai.provider.name"], attributes["gen_ai.model.provider"]) where attributes["gen_ai.model.provider"] != nil
          # Cloudflare's own cost estimate (gen_ai.usage.cost). Observe reads gen_ai.cost.total.
          - set(attributes["gen_ai.cost.total"], attributes["gen_ai.usage.cost"]) where attributes["gen_ai.usage.cost"] != nil
          # Content ON: fill the Input and Output panes from Cloudflare's JSON strings (request and response bodies).
          - set(attributes["input.value"], attributes["gen_ai.input.messages"]) where attributes["gen_ai.input.messages"] != nil and "${env:FI_CAPTURE_CONTENT:-false}" == "true"
          - set(attributes["output.value"], attributes["gen_ai.output.messages"]) where attributes["gen_ai.output.messages"] != nil and "${env:FI_CAPTURE_CONTENT:-false}" == "true"
          - set(attributes["input.value"], attributes["gen_ai.prompt_json"]) where attributes["gen_ai.prompt_json"] != nil and "${env:FI_CAPTURE_CONTENT:-false}" == "true"
          - set(attributes["output.value"], attributes["gen_ai.completion_json"]) where attributes["gen_ai.completion_json"] != nil and "${env:FI_CAPTURE_CONTENT:-false}" == "true"
          - set(attributes["input.mime_type"], "application/json") where attributes["input.value"] != nil and "${env:FI_CAPTURE_CONTENT:-false}" == "true"
          - set(attributes["output.mime_type"], "application/json") where attributes["output.value"] != nil and "${env:FI_CAPTURE_CONTENT:-false}" == "true"
          # Content OFF (the default): the prompt and completion in both of Cloudflare's spellings and in the
          # other OpenTelemetry GenAI spellings, indexed keys included. Content ON keeps nothing twice.
          - delete_key(attributes, "gen_ai.input.messages")
          - delete_key(attributes, "gen_ai.output.messages")
          - delete_key(attributes, "gen_ai.prompt_json")
          - delete_key(attributes, "gen_ai.completion_json")
          - delete_matching_keys(attributes, "^gen_ai\\.(prompt|completion|input\\.messages|output\\.messages)(\\..*)?$") where "${env:FI_CAPTURE_CONTENT:-false}" != "true"
          # Error text can echo the request. Keep the fact of the error, not the words.
          - set(status.message, "error") where status.message != "" and "${env:FI_CAPTURE_CONTENT:-false}" != "true"
      - context: spanevent
        statements:
          - delete_key(attributes, "exception.message") where "${env:FI_CAPTURE_CONTENT:-false}" != "true"
          - delete_key(attributes, "exception.stacktrace") where "${env:FI_CAPTURE_CONTENT:-false}" != "true"

  # Future AGI reads at most 16 MiB per request, so batching keeps requests small.
  batch:
    send_batch_size: 256
    send_batch_max_size: 512
    timeout: 2s

exporters:
  otlp_http/future_agi:
    traces_endpoint: ${env:FI_TRACES_URL}
    encoding: proto
    compression: none          # plain bodies work on every Future AGI version; self-hosted before v1.56.0 rejects gzip
    headers:
      X-Api-Key: ${env:FI_API_KEY}
      X-Secret-Key: ${env:FI_SECRET_KEY}

service:
  extensions: [bearertokenauth/gateway]
  telemetry:
    metrics:
      level: none              # no self-metrics endpoint; the gateway sends traces only
    logs:
      level: warn
  pipelines:
    traces:
      receivers: [otlp]
      processors: [resource/future_agi, transform/cloudflare, batch]
      exporters: [otlp_http/future_agi]

FI_CAPTURE_CONTENT is read as the exact string true. Any other value, or none, keeps content out.

export GATEWAY_TOKEN=$(openssl rand -hex 24)   # the secret Cloudflare will send
export FI_API_KEY=YOUR_API_KEY FI_SECRET_KEY=YOUR_SECRET_KEY

docker run -d --name cloudflare-gateway-otelcol --memory 512m \
  -p 4318:4318 \
  -v "$PWD/otelcol.yaml:/etc/otelcol/config.yaml:ro" \
  -e GATEWAY_TOKEN -e FI_API_KEY -e FI_SECRET_KEY \
  -e FI_PROJECT_NAME=my-cloudflare-gateway \
  -e FI_TRACES_URL=https://api.futureagi.com/tracer/v1/traces \
  otel/opentelemetry-collector-contrib:0.162.0 --config /etc/otelcol/config.yaml

Cloudflare’s exporter runs in Cloudflare’s network, so the collector needs a public HTTPS URL. The collector listens on plain HTTP on port 4318. Put TLS in front of it with a load balancer, a reverse proxy or a platform that terminates TLS for you, or add tls: with cert_file and key_file under the receiver’s http: block. Every request must carry the bearer token; without it the collector answers 401.

For example, deploy the collector on Google Cloud Run with the config file and three secrets in Secret Manager:

PROJECT=my-gcp-project REGION=us-central1
gcloud secrets create cfaig-otelcol-config --project $PROJECT --data-file=otelcol.yaml
printf %s "$GATEWAY_TOKEN" | gcloud secrets create cfaig-gateway-token --project $PROJECT --data-file=-
printf %s "$FI_API_KEY" | gcloud secrets create cfaig-fi-api-key --project $PROJECT --data-file=-
printf %s "$FI_SECRET_KEY" | gcloud secrets create cfaig-fi-secret-key --project $PROJECT --data-file=-
# let the service's runtime service account read the four secrets (roles/secretmanager.secretAccessor)

gcloud run deploy cloudflare-gateway-otelcol --project $PROJECT --region $REGION \
  --image docker.io/otel/opentelemetry-collector-contrib:0.162.0 \
  --args=--config=/etc/cfaig/config.yaml --port 4318 \
  --allow-unauthenticated --no-cpu-throttling --max-instances 1 --memory 512Mi \
  --set-secrets=/etc/cfaig/config.yaml=cfaig-otelcol-config:latest,GATEWAY_TOKEN=cfaig-gateway-token:latest,FI_API_KEY=cfaig-fi-api-key:latest,FI_SECRET_KEY=cfaig-fi-secret-key:latest \
  --set-env-vars=FI_PROJECT_NAME=my-cloudflare-gateway,FI_TRACES_URL=https://api.futureagi.com/tracer/v1/traces

--allow-unauthenticated lets Cloudflare reach the service; the collector’s bearer token is what protects it. --no-cpu-throttling keeps CPU on between requests, because the batch processor sends to Future AGI after Cloudflare’s request has been answered. Store the token without a trailing newline (printf %s, not echo): the collector compares the whole value. The exporter URL is the service URL plus /v1/traces.

In the Cloudflare dashboard open your AI Gateway, go to Settings and add an OTEL exporter.

You can also configure the exporter with the Cloudflare API using a token with AI Gateway Write. The otel list replaces the gateway’s exporters, and an update has to repeat the gateway’s other settings:

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/gateways/$GATEWAY_ID" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "cache_invalidate_on_update": true, "cache_ttl": 0, "collect_logs": true,
    "rate_limiting_interval": 0, "rate_limiting_limit": 0,
    "otel": [{
      "url": "https://gateway-otel.example.com/v1/traces",
      "headers": {"Authorization": "Bearer YOUR_GATEWAY_TOKEN"},
      "content_type": "json"
    }]
  }'

The API returns the header value in its responses, so do not log them.

Any client works. cf-aig-metadata is optional and carries values you choose. cf-aig-otel-trace-id and cf-aig-otel-parent-span-id are optional and link the gateway span to a trace your application already started:

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: {"team": "engineering", "feature": "support-bot"}' \
  --header 'cf-aig-otel-trace-id: 0123456789abcdef0123456789abcdef' \
  --header 'cf-aig-otel-parent-span-id: 0123456789abcdef' \
  --data '{"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello!"}]}'

The trace and span ids must be lowercase hex, 32 and 16 characters. For a streamed request, add "stream_options": {"include_usage": true} so the span gets the provider’s token counts.

Open Observe, select your project, and open the trace. Allow a few seconds for the span to arrive.