Supported telemetry types
The Cloudflare integration supports these telemetry types:Compatibility
The Cloudflare integration works with:- The Cloudflare GraphQL Analytics API, using the zone-scoped
httpRequests1mGroups,httpRequestsAdaptiveGroups,firewallEventsAdaptiveGroups, anddnsAnalyticsAdaptiveGroupsdatasets. - 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)
Configure the integration
-
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
- In XCOR, open the Integrations Hub and select Cloudflare.
- On the Configurations tab, add or edit a configuration and enter the API token.
-
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. - Save the configuration.
Token validation
When you save, XCOR verifies that the token authenticates. An invalid or revoked token returnscloudflare 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
- 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.
-
In Metrics Explorer,
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.
A result means data is flowing.
-
Confirm the set of collected zones:
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.Metric semantics
Ingested metric names use thecloudflare_ 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.
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.
The following table lists other common problems and how to resolve them:
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. 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.