Cloudflare AI Gateway logging configuration should start with the evidence your team needs and the content it should avoid retaining. A dashboard can make requests visible while also creating a new store of prompts, responses and metadata. The correct setting depends on both operational use and the account’s current logging contract.
Establish whether the gateway uses the current Workers Logs arrangement or Legacy Logs, then configure collection and payload storage deliberately. Test the actual request path with synthetic markers and inspect the resulting records. Keep useful operational metadata where appropriate without assuming that disabling payload storage removes data from every other system.
Imagine a support assistant whose prompts include customer correspondence. Engineers need to diagnose provider failures and attribute usage. They do not necessarily need the full correspondence copied into a general diagnostics store. This is a configuration and evidence problem, not a reason to give up observability.
This guide focuses on a proposed operational setup. It does not offer a legal compliance certification or assume that every account has the same pricing, retention and export arrangements.
Cloudflare AI Gateway logging configuration depends on eligibility
The current AI Gateway logging documentation distinguishes customers by when they created their first gateway. Customers creating their first gateway on or after 24 September 2026 follow Workers Logs pricing and retention; earlier customers use Legacy Logs. Verify that eligibility for the account you are configuring.
Do not import a retention period or log allowance from an older article and apply it to every deployment. Record the applicable service arrangement, selected settings and the date checked. Recheck when the account or logging architecture changes.
The same documentation separates collection of a whole log entry from storage of its request and response payloads. That distinction allows a more precise discussion than simply asking whether logging is on or off.
| Decision | Question to settle |
|---|---|
| Logging arrangement | Which current or legacy contract applies to this account? |
| Whole-entry collection | Should a diagnostic record exist for this request class? |
| Payload storage | Is retaining prompt and response content necessary? |
| Access | Who may inspect or export the records? |
| Retention | When do primary and exported copies expire? |
Define the incident questions first
Write down the questions an operator must answer. Which workload failed? Which provider and model route was used? Did the application retry? Was a response returned before the user stopped waiting? Is the destination task still unresolved?
Many of those questions can be answered with bounded metadata and application operation references. They do not always require the full prompt. Conversely, a content-quality investigation may need an explicitly controlled sample that general request metadata cannot explain.
Separate those use cases. The support application’s routine diagnostics can follow one collection policy, while a sanctioned investigation uses a different, reviewed evidence process. Do not keep every customer’s text forever because it might someday help reproduce a defect.
Our existing AI Gateway guide covers the broader proxy and cost-control role. The configuration work here is about establishing which evidence actually exists and proving the chosen collection behaviour.
Configure whole-entry and payload controls separately
Cloudflare documents cf-aig-collect-log for whole-entry collection and cf-aig-collect-log-payload for request/response payload storage. Setting the payload control to false can retain metadata without storing raw bodies; disabling the whole entry suppresses the entry, including metadata. Read the current header semantics before applying them.
The following is an illustrative header policy, not a complete request or proof of the deployed result:
1cf-aig-collect-log-payload: false
Apply policy in a trusted application component. An untrusted caller should not be able to alter the organization’s evidence policy by injecting arbitrary gateway-control headers. Decide which headers are forwarded, set or removed by the server.
Do not infer a default from a single successful request. Verify the gateway-level setting and the per-request override path separately. A configuration that works for the primary model route can still behave differently through a fallback or an alternative client.
Keep a record of the effective policy
Version the application-side configuration and record the relevant gateway settings. Describe which request classes retain payloads, which retain only metadata and which have collection suppressed.
When a developer adds another model integration, the review should include its logging path. Otherwise the application can accumulate several routes with different retention behaviour while the team believes there is one global policy.
Use metadata that does not become another payload
Opaque task and request references can connect gateway evidence to the application’s own records. A support-case identifier may be enough to locate the source under the existing access model. Copying the message subject or customer email into a metadata field can defeat the reason for excluding prompt bodies.
Define an allowed metadata schema. Check values as well as field names. A field called label can still contain personal or confidential content if the application fills it with user text.
| Metadata choice | Operational use | Review concern |
|---|---|---|
| Opaque workload identifier | Attribute usage to an application feature | Avoid embedding customer content |
| Operation reference | Connect an incident to task state | Access to the linked record remains controlled |
| Configuration revision | Reproduce the effective route | Keep secrets out of the value |
| Failure category | Group actionable problems | Avoid raw exception payloads with source content |
Keep application and gateway references consistent enough for investigation. An operator should be able to trace a failure without copying entire prompts between tools or granting every engineer access to the customer system.
Verify collection with synthetic markers
Send a non-sensitive test request containing a distinctive marker. Inspect the applicable logging destination and confirm whether the marker appears in payload storage, metadata, exports or related application logs under the intended policy.
Test a normal response, an upstream error and a fallback route if the application uses one. Error handling is a common place for request bodies to be copied into diagnostic fields outside the normal collection path.
| Test | Expected evidence under a metadata-only policy |
|---|---|
| Normal inference | Useful request metadata without the synthetic body marker |
| Provider error | Failure category and correlation reference without copied payload |
| Application retry | Attempts can be related without duplicating content in labels |
| Unauthorized gateway request | Rejection under the gateway access policy |
| Export or downstream log sink | The agreed content and retention policy still holds |
Cloudflare’s authenticated gateway documentation is the reference for that access control. Check the actual credential and route in the deployment rather than assuming the logging setting also protects the endpoint.
Include exports and other stores in the review
Gateway payload suppression does not prove that the application, model provider or external observability service retains nothing. Draw the actual data path and review each store under its own contract.
If logs are exported, document who can read the destination and when those copies expire. Deleting a record from one service is not proof that an earlier export was removed. The operational runbook should state which system owns which evidence.
Review traces, exception trackers and support screenshots as well. A team can correctly configure the gateway and still paste a customer’s prompt into a ticket visible to a wider group.
Use synthetic cases for routine regression tests. Where actual content is necessary to investigate a defect, establish a specific collection purpose and controlled access rather than changing the general policy without a record.
Budget for useful evidence and its maintenance
Implementation cost includes the data-path review, request-policy wiring, metadata schema, access setup and verification. Recurring cost depends on the applicable logging arrangement, volume and downstream stores, so verify the account’s current rates before estimating.
Ask for a GBP proposal that identifies the gateway arrangement and deliverable tests. A configuration-only task is different from rebuilding application logging across several model routes and export sinks.
The handover should contain the effective policy, ownership, synthetic test results and the procedure for investigating missing evidence. Include the configuration changes that trigger re-verification, especially another client, route or log sink.
We can review this boundary in a scoped AI integration pilot . Request a gateway logging assessment with your account’s eligibility, model routes, current sinks and incident questions. That makes observability useful without collecting content merely because the default permits it.
Frequently Asked Questions
Do all AI Gateway accounts use the same logging arrangement? No. Current documentation distinguishes customers whose first gateway was created on or after 24 September 2026 from earlier customers. Verify whether Workers Logs or Legacy Logs applies before relying on pricing or retention assumptions.
Can we keep metadata without prompt and response bodies? The documented payload collection control supports metadata-only entries when configured appropriately. Verify the effective gateway and per-request policy and inspect test results in the actual logging destination.
What is the difference between the two collection headers? The whole-entry control governs whether the log entry is collected. The payload control governs storage of raw request and response bodies while metadata can remain. Disabling the whole entry also removes its metadata, so choose from the evidence you need.
Does suppressing payloads mean no service stores our data? No. Other application logs, providers, exports and observability tools have their own behaviour and contracts. Review the complete data path rather than treating one gateway setting as a universal retention guarantee.
How can we test logging without customer data? Use synthetic markers in non-sensitive requests and inspect the relevant records and exports. Include normal results, errors, retries and fallback paths. Confirm that metadata does not contain the marker indirectly.
Should clients be allowed to choose their logging policy? Only where that authority is intentional. Apply organizational policy in a trusted server component and define which control headers are accepted or overwritten. An ordinary caller should not silently change the evidence policy.
What should an assessment deliver? It should identify the applicable contract, data stores, effective collection policy, access owners and retention decisions. Include synthetic verification results and a repeatable procedure for checking new model routes or log sinks.