> ## Documentation Index
> Fetch the complete documentation index at: https://docs-xcor.paloaltonetworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloudflare

> Cloudflare zone analytics from the GraphQL Analytics API: HTTP request, bandwidth, threat, security event, and DNS query metrics per zone.

The Cloudflare integration connects Cortex XCOR with
[Cloudflare](https://www.cloudflare.com/) zone analytics. XCOR polls the
Cloudflare GraphQL Analytics API and ingests HTTP request, bandwidth, threat, security event, and
DNS query metrics for each zone your API token can access.

This integration collects Cloudflare metrics. To ingest Cloudflare logs with Palo Alto Networks
Telemetry Pipeline, see the
[Cloudflare LogPush source plugin](https://docs-xcor.paloaltonetworks.com/ingest/pipeline/plugins/source-plugins/cloudflare.md).

## Supported telemetry types

The Cloudflare integration supports these telemetry types:

| Logs | Metrics | Traces | Events |
| :-: | :-: | :-: | :-: |
| No | Yes | No | No |

## Compatibility

The Cloudflare integration works with:

* The Cloudflare GraphQL Analytics API, using the zone-scoped `httpRequests1mGroups`,
  `httpRequestsAdaptiveGroups`, `firewallEventsAdaptiveGroups`, and `dnsAnalyticsAdaptiveGroups`
  datasets.
* Any zone whose plan grants GraphQL Analytics access. Which datasets a zone exposes depends on its
  plan and settings, so not every zone produces every metric: HTTP metrics require both HTTP
  datasets, security event metrics require both HTTP datasets and the firewall events dataset, and
  DNS metrics require the DNS dataset.
* Every zone the API token can access, across all the accounts it covers, or only the zones listed
  in the configuration. Every series carries the zone and account it belongs to.

## Prerequisites

The Cloudflare integration requires:

* A Cloudflare account with GraphQL Analytics access on the zones you want to collect.
* A Cloudflare API token scoped to the zones you want to collect, or to all zones. User API tokens
  (`cfut_` prefix), account API tokens (`cfat_` prefix), and older unprefixed tokens all work. The
  token must include both of
  these zone permissions:

  * **Zone** > **Zone** > **Read** (to list zones)
  * **Zone** > **Analytics** > **Read** (to query GraphQL Analytics)

  The token is stored write-only through the Integrations Hub **Configurations** tab: it can be
  replaced, but never read back.

## Configure the integration

1. In Cloudflare, create a custom API token under **My Profile** > **API Tokens**. For each
   permission, set the scope to **Zone**, then add:

   * **Zone** > **Zone** > **Read**
   * **Zone** > **Analytics** > **Read**

   Apply both permissions to the zones you want to collect, or to **All zones**.
2. In XCOR, open the Integrations Hub and select **Cloudflare**.
3. On the **Configurations** tab, add or edit a configuration and enter the API token.
4. Optional: under **Collection**, add the zone names to collect in **Zones**, for example
   `example.com`. Leave **Zones** empty to collect every zone the token can access.
5. Save the configuration.

### Token validation

When you save, XCOR verifies that the token authenticates. An invalid or revoked
token returns `cloudflare token is not valid`, and an expired or disabled token returns a message
saying the token is not active. If Cloudflare is briefly unavailable, save fails as temporarily
unavailable. Try again. Save doesn't verify that the token has **Zone** read
or **Analytics** read permissions. A configuration can save successfully and still collect no data
if permissions are insufficient. The configuration's status then reports a problem with the token's
permissions once collection runs.

## Validate metrics ingestion

1. Allow up to about 15 minutes after saving for the first metrics to appear. XCOR syncs
   zone metadata about every five minutes before collection starts. After that, the newest samples
   stay about ten minutes behind real time. See Limitations below.

2. In [Metrics Explorer](https://docs-xcor.paloaltonetworks.com/investigate/querying/metrics/explorer.md),
   query one metric over a range, substituting one of your zones. The newest point is
   about ten minutes old, so a query evaluated only at the current time returns nothing.

   ```text theme={null}
   sum(sum_over_time(cloudflare_http_requests_total{zone_name="<your zone>"}[30m]))
   ```

   A result means data is flowing.

3. Confirm the set of collected zones:

   ```text theme={null}
   count by (zone_name) (count_over_time(cloudflare_http_requests_total[30m]))
   ```

## Dashboards

The integration includes an **Overview** dashboard that summarizes zone traffic, security, caching,
and DNS. Open it from the **Assets** tab on the Cloudflare integration page in the Integrations
Hub. For more about bundled dashboards, see
[Use bundled assets](https://docs-xcor.paloaltonetworks.com/integrate/integrations-hub.md#use-bundled-assets).

## Metric semantics

Ingested metric names use the `cloudflare_` prefix followed by the metric suffix (for example,
`cloudflare_http_requests_total`). Search for the prefix `cloudflare_` in Metrics Explorer to browse
ingested series.

HTTP and DNS counts are stored as delta counters, one sample per one-minute GraphQL bucket. Security
event counts are delta counters too, with one sample per label combination for each one-minute
collection window. Query them with `sum_over_time()` for totals and `sum_per_second()` for rates.
`increase()` and `rate()` need two samples in the window, so they return nothing for a quiet zone
with a single bucket. For more, see
[Querying delta temporality metrics](https://docs-xcor.paloaltonetworks.com/investigate/querying/metrics/delta-queries.md).
The exception is `cloudflare_http_uniques_total`: each sample is a per-minute unique-visitor count,
so summing it over a longer window overcounts visitors who return. Averaged and percentile metrics
are point-in-time gauges.

Every series includes `zone_id`, `zone_name`, `account_id`, and `account_name` labels that identify
the zone and account it belongs to. Additional labels depend on the metric, such as `country`,
`status_code`, or `query_type`. Security event counts carry `action`, `firewall_source`, `rule_id`,
and `host`. The `firewall_source` label holds the Cloudflare `source` field.

For the full metric catalog (names, types, units, and descriptions), open the **Metrics** tab on the
Cloudflare integration page in the Integrations Hub.

## Troubleshooting

The status of a configuration on the **Configurations** tab comes from listing the zones the token
can read and from collecting their analytics. When it reports a problem you can fix, it says what
kind of change the token, the account, or the configuration needs. For this integration, each kind
of status points at the setting in this table. The wording of the status can differ from the first
column. A status that says data is late or missing is a Cloudflare incident, a rate limit, or a
problem on the XCOR side. There is nothing to change in the configuration.

| When the status says that | Look at |
| - | - |
| The credentials aren't valid. | The token expired, was deleted, or was rolled in Cloudflare. Create a token with the permissions listed in the prerequisites and save it in the configuration. |
| A permission is missing. | The token lists no zones, the token lacks **Zone** > **Analytics** > **Read** on a zone it lists, or the account member who created the token left the account. Grant **Zone** > **Zone** > **Read** on the zones you want to collect, edit the token's permissions and zone resources, or create an account-owned token with the permissions listed in the prerequisites. |
| The configuration's details don't match the account. | The token lists zones, but none of them is in the configuration's **Zones** list. Check the zone names, or grant **Zone** > **Zone** > **Read** on the listed zones. |
| The credentials were rejected. | Cloudflare refused the token without saying whether it's invalid or lacks a permission. Check that the token is active, that it isn't restricted to client IP addresses, that the account allows API access, and that it grants both permissions listed in the prerequisites. |
| The plan doesn't include this data. | None of the zones the configuration collects has a plan that exposes the datasets that HTTP or DNS metrics require, so no metrics arrive. The status also appears when a zone's plan no longer exposes a dataset the integration collects. Until the next zone metadata sync excludes the dataset for that zone, collection of it stops for the zones in the same batch. Upgrade the plan of the zones you want to collect. |
| A usage limit was reached. | Cloudflare reported that an account's or a zone's GraphQL Analytics API rate limit is exhausted. That limit is shared with your own dashboards and scripts. Reduce other usage, or ask your Cloudflare account team for a higher limit. |

The following table lists other common problems and how to resolve them:

| Symptom | Resolution |
| - | - |
| Save fails with `cloudflare token is not valid` | The token is missing, revoked, or otherwise rejected during authentication. Create a new token in Cloudflare and save again. |
| Save succeeds but no metrics appear | Confirm the token includes **Zone** > **Zone** > **Read** and **Zone** > **Analytics** > **Read** on the zones you expect. Save only checks authentication, not Analytics access. A token without **Zone** > **Zone** > **Read** lists no zones, and the configuration's status says a permission is missing. |
| No metrics yet after saving | Wait up to about 15 minutes for the first samples. Zone metadata sync runs on a five-minute cadence, and ingested points also trail real time by about ten minutes. |
| A zone never appears in queries | Confirm the token scopes that zone, the zone is in the configuration's **Zones** list if the list isn't empty, the zone's plan exposes the GraphQL datasets, and the zone had HTTP or DNS activity in the collection window. Zones without traffic produce no samples rather than zeros. |
| Security event metrics are missing for a zone | Security event counts need the zone's plan to expose the firewall events dataset, and the zone must also collect HTTP metrics. If Cloudflare fails the security event query for a collection window, security event samples for that window are missing, possibly for several zones at once, and HTTP and DNS metrics still arrive. |

## Limitations

* The integration collects metrics only. It doesn't collect logs, traces, or events.
* The **Zones** list narrows what the API token can access. It can't add zones the token can't
  access, and listed zones the token can't access aren't collected. Zone names match regardless of
  case. Configurations that use the same API token together collect every zone any of them lists,
  and every zone the token can access if any of them leaves **Zones** empty.
* Ingested samples trail real time by about ten minutes because of the ingest delay applied during
  collection.
* Security event counts are estimates from Cloudflare's
  [adaptive sampling](https://developers.cloudflare.com/analytics/graphql-api/sampling/). Each zone
  keeps at most 10,000 combinations of action, source, rule, and host per minute, and the least
  frequent combinations are dropped when a zone exceeds that.


## Related topics

- [Cloudflare LogPush source plugin](https://docs-xcor.paloaltonetworks.com/ingest/pipeline/plugins/source-plugins/cloudflare.md)
- [Palo Alto Networks Telemetry Pipeline release notes](https://docs-xcor.paloaltonetworks.com/ingest/pipeline/v2/release-notes.md)
- [Terraform provider release notes](https://docs-xcor.paloaltonetworks.com/tooling/infrastructure/terraform/release-notes.md)
- [Server integrations](https://docs-xcor.paloaltonetworks.com/ingest/xcor/integrations/server.md)
- [Ingest telemetry data with source plugins](https://docs-xcor.paloaltonetworks.com/ingest/pipeline/plugins/source-plugins.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.