Documentation Plugins Cloudflare Query editor

Cloudflare query editor

Grafana provides a query editor for the Cloudflare data source, which is located on the Explore page. You can also access the Cloudflare query editor from a dashboard panel. Click the ellipsis in the upper right of the panel and select Edit.

Before you begin

Ensure you have configured the Cloudflare data source.

Key concepts

If you’re new to Cloudflare, here are some key terms used in this documentation:

Query types

The Cloudflare data source supports the following query types:

• Accounts: List accounts and view account details
• Zones: List zones in your Cloudflare account
• DNS Analytics: Query DNS analytics reports and time series data
• Radar: Query Cloudflare Radar data for global Internet insights
• Load Balancer: List load balancers and view load balancer details
• Token: List API tokens and view API token details

Create a query

To create a query, select the Action (query type) from the drop-down. Each action represents a Cloudflare API endpoint. After selecting an action, provide the required parameters.

Some actions have mandatory parameters displayed next to the action selector. Optional parameters are available in the Optional parameters section.

You can use dashboard template variables in query fields with the ${variable_name} syntax. For more information, refer to Cloudflare template variables.

Account queries

Accounts are a fundamental entity in Cloudflare. For more information, refer to the Cloudflare accounts documentation.

List accounts

Lists all accounts you have ownership or verified access to.

For API details, refer to List accounts.

Account details

Gets information about a specific account that you’re a member of.

For API details, refer to Account details.

Zone queries

Zones represent domains added to your Cloudflare account. For more information, refer to the Cloudflare zones documentation.

List zones

Lists, searches, sorts, and filters your zones.

For API details, refer to List zones.

DNS Analytics queries

DNS Analytics provides insights into DNS query data for your zones. For detailed information about available parameters, refer to Analytics API properties.

DNS analytics report

Retrieves a list of summarized aggregate metrics over a given time period.

For API details, refer to DNS analytics report.

DNS analytics by time

Retrieves a list of aggregate metrics grouped by time interval, suitable for time series visualizations.

For API details, refer to DNS analytics by time.

Available metrics and dimensions

Both DNS Analytics queries support the same set of metrics and dimensions.

The following metrics are available:

The following dimensions are available to group results:

Radar queries

Cloudflare Radar showcases global Internet traffic, attack, and technology trends. Radar data is powered by Cloudflare’s global network and aggregated data from the 1.1.1.1 public DNS resolver.

The following Radar data is available:

Internet outages and anomalies

The Internet outages and anomalies query has additional filtering options:

For more information about Radar APIs, refer to the Cloudflare Radar documentation.

Load Balancer queries

Load Balancers distribute traffic among pools according to configured policies. For more information, refer to the Cloudflare load balancers documentation.

List load balancers

Lists all configured load balancers that you have ownership or verified access to.

For API details, refer to List Load Balancers.

Load Balancer details

Gets information about a specific configured load balancer that you have ownership or verified access to.

For API details, refer to Load Balancer details.

Token queries

API Tokens have a specific set of permissions that allow access to Cloudflare resources. For more information, refer to the Cloudflare Account API Tokens documentation.

List tokens

Lists all API tokens by account.

For API details, refer to List Tokens.

Token details

Gets information about a specific API token.

For API details, refer to Token details.

Query examples

The following examples demonstrate common query configurations.

Example: Monitor DNS query count over time

To visualize DNS query volume trends for a zone:

1. Select the Cloudflare data source.
2. Set Action to DNS analytics by time.
3. Select your zone from the Zone ID drop-down.
4. In Metrics, select Query Count.
5. Leave Dimensions empty to see total query count, or select Response Code to break down by response type.

This query returns time series data suitable for a Time series panel.

Example: Analyze DNS queries by type and response code

To create a table showing DNS query distribution:

1. Select the Cloudflare data source.
2. Set Action to DNS analytics report.
3. Select your zone from the Zone ID drop-down.
4. In Metrics, select Query Count.
5. In Dimensions, select Query Type and Response Code.
6. Set Limit to 100 to see the top 100 combinations.

This query returns tabular data suitable for a Table panel.

Example: Track global traffic by operating system

To visualize how traffic is distributed across operating systems:

1. Select the Cloudflare data source.
2. Set Action to Get operating systems timeseries.

The query automatically uses the dashboard time range and returns time series data showing percentage distribution by operating system, for example Windows, macOS, Android, and iOS.

Example: Monitor Internet outages in a region

To track Internet outages and anomalies in a specific country:

1. Select the Cloudflare data source.
2. Set Action to Internet outages and anomalies.
3. In Location, enter the country code (for example, US for United States).
4. In Status, select VERIFIED to show only confirmed outages.
5. Set Limit to 10 to show the 10 most recent events.

This query returns a list of outage events with start and end times, suitable for a Table panel or as annotation data.

Use cases

The following real-world scenarios demonstrate how to use the Cloudflare data source effectively.

Monitor DNS performance and reliability

Track DNS query performance to ensure your domains are responding quickly and reliably.

Dashboard setup:

1. Query volume panel: Use the DNS analytics by time query with the Query Count metric to track request volume over time.
2. Response time panel: Use the DNS analytics by time query with the Median response time and 99th percentile response time metrics to monitor latency.
3. Error rate panel: Use the DNS analytics report query with the Query Count metric and Response Code dimension to identify failed queries, such as SERVFAIL and NXDOMAIN.

Alerting: Set up alerts on response time percentiles or error rates to catch issues early.

Investigate traffic anomalies

When you notice unusual traffic patterns, use these queries to investigate.

Investigation workflow:

1. Identify the timeframe: Use the DNS analytics by time query to pinpoint when anomalies occurred.
2. Break down by dimension: Add dimensions like Query Type, Response Code, or Query Name to identify patterns.
3. Compare with Radar data: Use the Internet outages and anomalies query to check if the anomaly correlates with known Internet outages.

Track global Internet trends

Use Cloudflare Radar data to understand broader Internet patterns that may affect your users.

Dashboard setup:

1. Device distribution: Use the Get device type summary query to see mobile compared to desktop traffic trends.
2. Browser trends: Use the Get user agent families timeseries query to track browser adoption over time.
3. Protocol adoption: Use the Get HTTP versions timeseries query to monitor HTTP/2 and HTTP/3 adoption.
4. Outage overlay: Add the Internet outages and anomalies query as an annotation to correlate traffic changes with outages.

Security monitoring

Monitor for potential security issues using DNS analytics patterns.

What to watch for:

Alerting: Create alerts for sudden increases in error responses or unusual query type distributions.

Considerations

Keep the following in mind when you build Cloudflare queries:

• Time range: DNS Analytics queries and most Radar queries automatically use the dashboard time range through the ${__timeFrom} and ${__timeTo} variables. List queries such as List zones and List accounts aren’t time-bound and return the same results regardless of the selected range.
• Result format: Time series queries, such as DNS analytics by time and the Radar time series queries, suit Time series panels. Report and list queries, such as DNS analytics report and List zones, return tabular data suited to Table panels.
• Result limits: The DNS analytics report query defaults its Limit to 100000. Lower it for large zones to reduce the response size. The Internet outages and anomalies query defaults its Limit to 5.
• API rate limits: Frequent dashboard refreshes across many panels can reach Cloudflare API rate limits. If you see rate-limit errors, refer to Troubleshooting.