---
name: cloudflare
description: 'What a Cloudflare account is using, read with a read-only API token -- today''s Worker requests against the daily quota, and where they come from; its traffic over 24 minutes, hours and days, charted and diagnosed. Tools: latency, traffic, usage. Use when a request needs any of these; each tool''s own trigger is in SKILL.md.'
compatibility: Requires fragletc and Docker. Network access required.
metadata:
  tags: engineering, internet
  tools: latency.py, traffic.py, usage.py
---

# Cloudflare

What a Cloudflare account is using, read with a read-only API token -- today's Worker requests against the daily quota, and where they come from; its traffic over 24 minutes, hours and days, charted and diagnosed.

Every tool below is one executable file beside this `SKILL.md`, in the directory the commands below call `<skill-dir>`. Run it directly. Two host requirements: [`fragletc`](https://github.com/ofthemachine/fraglet) (`curl -fsSL https://raw.githubusercontent.com/ofthemachine/fraglet/main/install.sh | sh && fragletc version`) and Docker; the image, parameters, outputs and network reach are declared in the file itself. Before running a tool, print its contract:

```sh
<skill-dir>/latency.py --fraglet-help
```

Parameters are passed as `-p name=value` (a `file` parameter takes a host path); declared outputs are copied out with `--output <name>[=<host path>]`. A missing required parameter fails host-side with exit 2 before any container starts; otherwise the tool's own exit code is the run's. A declared output not named with `--output` is produced and discarded (a stderr note says what you could have copied). Add `--receipt run.json` (or set `FRAGLETC_RECEIPT_DIR`) to record the run: the receipt carries the tool's `procedure_hash`, image digest, parameters, and every input and output by content hash, and `receipt/attest.py` can verify it later without re-running anything.

## Tools

### `latency.py`

How fast a Cloudflare site's origin answers, path by path: requests, p50/p95/p99 and size over the last 24 hours, against the last hour and the 24 hours before, flagging a real slowdown. An address making most of a window's requests is left out of it and named, so a flood cannot skew the numbers. Long polls are labelled and never flagged: their time is waiting. Read-only.

Use when someone asks how fast a Cloudflare site is answering, which path is slow, or whether a change made it faster or slower; for how much traffic and from whom, use cloudflare/traffic.

```sh
<skill-dir>/latency.py -p zone="<zone>" [-p longpoll=] [-p top=12] --output report.md
```

Parameters:
- `zone` (string, required) — The zone (domain) to read, e.g. example.com
- `longpoll` (string, optional, default ``) — Comma-separated paths that wait for news by design, e.g. /v1/since
- `top` (string, optional, default `12`) — How many paths to list
- `CLOUDFLARE_API_TOKEN` (secret, required) — read from the caller's environment, never passed with `-p`; A Cloudflare API token with Zone Analytics read and Zone read (read-only)

Outputs:
- `report.md` — copy out with `--output report.md[=<host path>]`

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.

### `traffic.py`

A Cloudflare zone's traffic over the last 24 minutes, 24 hours and 24 days, drawn and diagnosed: traffic.svg stacks the three as small multiples (requests from clients by status class, the daily Worker quota and today's projection on the days), worker.svg is the Worker's CPU time per hour against the free plan's 10 ms limit, and report.md is a Markdown report (a headline, the golden signals against the 24 hours before, the top talkers by kind of client and path, and diagnostics that name a poller, the side a 5xx came from, CPU headroom and the quota's pace). Clients are counted by kind (a browser by name, else a program). Read-only; cloudflare/usage is the quota alone, as gauges. It names the top client addresses, with country and client.

Use when someone asks what traffic a Cloudflare site or Worker is getting, for a chart of its requests over minutes, hours or days, why it returns errors, who is driving its request count, or how close it is to the daily Workers quota.

```sh
<skill-dir>/traffic.py -p zone="<zone>" [-p quota=100000] [-p tz=UTC] [-p top=5] --output traffic.svg
```

Parameters:
- `zone` (string, required) — The zone (domain) to read, e.g. example.com
- `quota` (string, optional, default `100000`) — Worker requests a day the plan allows (the free plan: 100000)
- `tz` (string, optional, default `UTC`) — The IANA time zone the charts' times are shown in (the quota's day is always UTC's)
- `top` (string, optional, default `5`) — How many top talkers and top addresses to list
- `CLOUDFLARE_API_TOKEN` (secret, required) — read from the caller's environment, never passed with `-p`; A Cloudflare API token with Account Analytics read and Zone read (read-only)

Outputs:
- `traffic.svg` — copy out with `--output traffic.svg[=<host path>]`
- `worker.svg` — copy out with `--output worker.svg[=<host path>]`
- `report.md` — copy out with `--output report.md[=<host path>]`

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.

### `usage.py`

A zone's Worker requests today (the UTC day Cloudflare's daily quota counts) against that quota: how many so far, where the day ends if the last hour's rate holds, and the share of the quota that is, by Worker script; then the last hour's requests to the zone by path and by kind of client (a browser by name, else a program), never by address. The gauges are files (used.txt, projected.txt, share.txt, the projected share as a fraction) and stdout is a short report. Read-only: the token needs only Analytics read and Zone read.

Use when someone asks how close a Cloudflare Workers site is to its daily request limit, what is driving its request count, or whether a client is polling too hard.

```sh
<skill-dir>/usage.py -p zone="<zone>" [-p quota=100000] [-p top=8] --output used.txt
```

Parameters:
- `zone` (string, required) — The zone (domain) whose Workers to read, e.g. example.com
- `quota` (string, optional, default `100000`) — Worker requests a day the plan allows (the free plan: 100000)
- `top` (string, optional, default `8`) — How many paths and clients to list
- `CLOUDFLARE_API_TOKEN` (secret, required) — read from the caller's environment, never passed with `-p`; A Cloudflare API token with Account Analytics read and Zone read (read-only)

Outputs:
- `used.txt` — copy out with `--output used.txt[=<host path>]`
- `projected.txt` — copy out with `--output projected.txt[=<host path>]`
- `share.txt` — copy out with `--output share.txt[=<host path>]`

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.
