Logging

Logging is a fundamental building block for application development. Logs provide insights during the early stages of development and are often critical to understanding issues occurring in production.

Your AI Gateway dashboard shows logs of individual requests, including the user prompt, model response, provider, timestamp, request status, token usage, cost, and duration. When DLP policies are configured, logs for requests that trigger a DLP match also include the DLP action taken (Flag or Block), matched policy IDs, matched profile IDs, and the specific detection entries that were triggered. These logs persist, giving you the flexibility to store them for your preferred duration and do more with valuable request data.

By default, each gateway can store up to 10 million logs. You can customize this limit per gateway in your gateway settings to align with your specific requirements. If your storage limit is reached, new logs will stop being saved. To continue saving logs, you must delete older logs to free up space for new logs. To learn more about your plan limits, refer to Limits.

We recommend using an authenticated gateway when storing logs to prevent unauthorized access and protects against invalid requests that can inflate log storage usage and make it harder to find the data you need. Learn more about setting up an authenticated gateway.

Default configuration

Logs, which include metrics as well as request and response data, are enabled by default for each gateway. This logging behavior will be uniformly applied to all requests in the gateway. If you are concerned about privacy or compliance and want to turn log collection off, you can go to settings and opt out of logs. If you need to modify the log settings for specific requests, you can override this setting on a per-request basis.

To change the default log configuration in the dashboard:

In the Cloudflare dashboard, go to the AI Gateway page.
Go to AI Gateway
Select Settings.
Change the Logs setting to your preference.

Per-request logging

To override the default logging behavior set in the settings tab, you can define headers on a per-request basis.

Collect logs (`cf-aig-collect-log`)

The cf-aig-collect-log header allows you to bypass the default log setting for the gateway. If the gateway is configured to save logs, the header will exclude the log for that specific request. Conversely, if logging is disabled at the gateway level, this header will save the log for that request.

In the example below, we use cf-aig-collect-log to bypass the default setting to avoid saving the log.

curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai/chat/completions \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'cf-aig-collect-log: false \
  --data ' {
        "model": "gpt-4o-mini",
        "messages": [
          {
            "role": "user",
            "content": "What is the email address and phone number of user123?"
          }
        ]
      }
'

DLP fields in logs

When Data Loss Prevention (DLP) policies are enabled on a gateway, log entries for requests that trigger a DLP policy match include additional fields:

Field	Description
DLP Action	The action taken by the DLP policy: `FLAG` or `BLOCK`
DLP Policies Matched	The IDs of the DLP policies that matched
DLP Profiles Matched	The IDs of the DLP profiles that triggered within each matched policy
DLP Entries Matched	The specific detection entry IDs that matched within each profile
DLP Check	Whether the match occurred in the `REQUEST`, `RESPONSE`, or both

These fields are available both in the dashboard log viewer and through the Logs API. You can filter logs by DLP Action in the dashboard to view only flagged or blocked requests. For more details on DLP monitoring, refer to Monitor DLP events.

Managing log storage

To manage your log storage effectively, you can:

Set Storage Limits: Configure a limit on the number of logs stored per gateway in your gateway settings to ensure you only pay for what you need.
Enable Automatic Log Deletion: Activate the Automatic Log Deletion feature in your gateway settings to automatically delete the oldest logs once the log limit you've set or the default storage limit of 10 million logs is reached. This ensures new logs are always saved without manual intervention.

How to delete logs

To manage your log storage effectively and ensure continuous logging, you can delete logs using the following methods:

Automatic Log Deletion

To maintain continuous logging within your gateway's storage constraints, enable Automatic Log Deletion in your Gateway settings. This feature automatically deletes the oldest logs once the log limit you've set or the default storage limit of 10 million logs is reached, ensuring new logs are saved without manual intervention.

Manual deletion

To manually delete logs through the dashboard, navigate to the Logs tab in the dashboard. Use the available filters such as status, cache, provider, cost, or any other options in the dropdown to refine the logs you wish to delete. Once filtered, select Delete logs to complete the action.

See full list of available filters and their descriptions below:

Filter category	Filter options	Filter by description
Status	error, status	error type or status.
Cache	cached, not cached	based on whether they were cached or not.
Provider	specific providers	the selected AI provider.
AI Models	specific models	the selected AI model.
Cost	less than, greater than	cost, specifying a threshold.
Request type	Universal, Workers AI Binding, WebSockets	the type of request.
Tokens	Total tokens, Tokens In, Tokens Out	token count (less than or greater than).
Duration	less than, greater than	request duration.
Feedback	equals, does not equal (thumbs up, thumbs down, no feedback)	feedback type.
Metadata Key	equals, does not equal	specific metadata keys.
Metadata Value	equals, does not equal	specific metadata values.
Log ID	equals, does not equal	a specific Log ID.
Event ID	equals, does not equal	a specific Event ID.
DLP Action	FLAG, BLOCK	the DLP action taken on the request.

API deletion

You can programmatically delete logs using the AI Gateway API. For more comprehensive information on the DELETE logs endpoint, check out the Cloudflare API documentation.