Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 36 ยท Operations and Analytics

Cloudflare Analytics, Logs and Observability

Read Cloudflare analytics, query the GraphQL Analytics API, send logs with Logpush, observe Workers with wrangler tail and Workers Logs, and compute cache hit ratio and error rates.

You cannot run a site you cannot see. Cloudflare sees every request that crosses its network, so it can tell you how many requests you had, how many were served from cache, which countries they came from, which ones were blocked and why. This lesson tours the tools, from the dashboard to raw log files, and ends with the calculations you will actually do on that data.

The analytics themselves are Cloudflare's, so dashboard steps and API calls are read-only. The calculations run on sample log lines in the browser.

The dashboard

Open your site, then Analytics & Logs. Useful views:

  • Traffic: requests, unique visitors, bandwidth, status code classes (2xx, 3xx, 4xx, 5xx), top countries, top paths.
  • Performance: time to first byte and cache behavior.
  • Security: events from the WAF, rate limiting and bot rules; filter by rule, country, IP or path to see exactly what a rule is doing.
  • Cache: hit ratio and bytes served from cache versus from the origin.
  • Web Analytics (separate, privacy-friendly, no cookies): page views and Core Web Vitals from a small script or automatically for proxied sites.

Dashboard data is aggregated and sampled: good for trends, not for proving that one exact request happened. For that you need logs.

The GraphQL Analytics API

All the dashboard graphs come from one GraphQL API at https://api.cloudflare.com/client/v4/graphql. Authenticate with an API token that has Analytics read permission.

Terminal
curl -s https://api.cloudflare.com/client/v4/graphql \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "query": "query ($zone: String!, $from: Date!, $to: Date!) { viewer { zones(filter: {zoneTag: $zone}) { httpRequests1dGroups(limit: 7, filter: {date_geq: $from, date_leq: $to}) { dimensions { date } sum { requests cachedRequests bytes } } } } }",
    "variables": { "zone": "<zone id>", "from": "2026-03-01", "to": "2026-03-07" }
  }'

You choose the dataset (for example httpRequests1dGroups, httpRequestsAdaptiveGroups, firewallEventsAdaptive), the dimensions to group by and the sums to compute. Field names vary by dataset and plan, so use the API's GraphiQL explorer to discover them rather than guessing.

Logs: Logpush and Logpull

For per-request logs, Logpush delivers log lines in batches to a destination you own: R2, Amazon S3, Google Cloud Storage, Azure Blob, Datadog, Splunk or an HTTPS endpoint. You pick a dataset (HTTP requests, firewall events, Access requests, Gateway DNS, Workers trace events...) and the fields to include.

Terminal
curl -X POST "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/logpush/jobs" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" -H "Content-Type: application/json" \
  --data '{
    "name": "http-to-r2",
    "destination_conf": "r2://my-logs/http/{DATE}?account-id=<id>&access-key-id=<key>&secret-access-key=<secret>",
    "dataset": "http_requests",
    "output_options": { "field_names": ["EdgeStartTimestamp","ClientRequestPath","EdgeResponseStatus","CacheCacheStatus","ClientCountry"] },
    "enabled": true
  }'

Logpush is typically an Enterprise feature for zone logs, while some datasets are available on other plans; check current availability. Sampling and privacy matter: logs contain IP addresses, so set retention and access rules for them.

Observability for Workers

Workers have three levels of insight:

  1. console.log in the dashboard and Workers Logs. Enable logs in the Worker's observability settings ("observability": { "enabled": true } in the config) to search structured logs, errors and invocation metrics in the dashboard.

  2. wrangler tail streams live logs and exceptions from a deployed Worker, filterable by status, IP or search text:

    Terminal
    npx wrangler tail --status error --format pretty
    
  3. Metrics: requests, errors, CPU time, duration and subrequests per Worker in its Metrics tab, plus traces for following a request through bindings.

Write logs as JSON so that you can search them:

JavaScript
console.log(JSON.stringify({ level: "info", route: "/api/users", status: 200, ms: 12, country: request.cf?.country }));

Computing the numbers that matter

Most operations work boils down to a few ratios. This stand-in parses sample HTTP log lines (the fields match a Logpush export) and computes them.

JS Cache hit ratio and error rate from logs

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Two definitions of hit ratio appear on purpose. Dynamic requests (API responses not cached) drag the overall ratio down; the ratio over cacheable requests tells you how well your cacheable content is cached, which is the one you can improve with caching rules.

Alerting

Dashboards are for looking; alerts are for sleeping. In Notifications you can create alerts for: origin 5xx spikes, DDoS attacks detected, SSL certificate expiry, tunnel health changes, Worker error rates, and usage thresholds. Send them to email, a webhook (Slack, PagerDuty) or both. Set a low-noise rule first, then tighten.

A simple threshold alert looks like this in code:

JS Error-rate alert logic

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which tool gives you every individual request as a log record delivered to storage you own?

    Logpush batches raw log records to destinations like R2, S3 or a SIEM. Dashboard graphs are aggregates.
  2. 2. How do you watch live errors from a deployed Worker?

    wrangler tail streams console output and exceptions of the deployed Worker in real time.
  3. 3. Why compute cache hit ratio over cacheable requests separately?

    Dynamic requests bypass the cache by design. Excluding them shows whether your cacheable content is actually being cached.
  4. 4. What makes an alert less noisy?

    Requiring a sustained breach filters one-off spikes and keeps alerts meaningful.

Summary

  • The dashboard shows aggregated traffic, performance, security and cache data; the GraphQL Analytics API exposes the same data to your code.
  • Logpush sends raw per-request logs to R2, S3, SIEMs or HTTPS endpoints; mind privacy and retention.
  • Workers have Workers Logs, wrangler tail and metrics; log JSON for searchability.
  • Key numbers: cache hit ratio (overall and for cacheable content), 4xx and 5xx rates, bytes saved at the origin; alert on sustained breaches.

Next: The Cloudflare API, Terraform and Automation