fastly-stats

Fastly stats

Prefer the fastly CLI. Drop to curl only for the seven things the CLI cannot do, listed under Raw API below.

Rules that decide whether the answer is right

1. Bytes to GB is decimal SI: bytes / 1e9. TB is / 1e12. Never 2^30. Fastly bills in decimal units, so a GiB figure is wrong by 7.4% and still reads as a plausible number.
2. For a calendar window, pass explicit UTC boundaries: --from 2026-07-01T00:00:00Z --to 2026-08-01T00:00:00Z returns every day bucket in July. A bucket is emitted only when the whole period falls inside the window, and a relative window opens and closes mid-bucket, so --from "N days ago" --by day returns N-1 buckets, never N, and "1 day ago" returns none at all. Relative strings are safe at --by hour, not at --by day.
3. On the raw API, from=yesterday means 12:00:00 UTC, not midnight, and from=today means now. N days ago / N hours ago are exact offsets. Read back meta.from / meta.to.
4. hit_ratio, edge_hit_ratio and origin_offload are gauges. Never sum or average them across buckets. Recompute from the summed counters: hits / (hits + miss).
5. ts/h on rt.fastly.com covers the last 120 seconds, not an hour, and returns only the seconds that carried traffic. Divide a rate by 120 there, or by the window you bounded when sampling with the CLI; never by the sample count or the recorded span. Print the window beside the rate.
6. fastly stats ... --json emits NDJSON, one object per line, no array. Slurp with jq -s before aggregating. The raw HTTP API returns a normal array in data.
7. Stats responses omit services with zero traffic in the window. Enumerate from fastly service list --json and default sums with add // 0.
8. Do not read the newest bucket. Historical aggregation keeps growing for a few minutes after a period closes.
9. On a Compute service the traffic lands in compute_requests and requests stays 0. Summing requests alone reports zero traffic for a service that is serving fine. Check both.
10. Status codes split the same way. Use all_status_*, never bare status_* or compute_resp_status_*: status_5xx is 0 on Compute, compute_resp_status_5xx is absent on VCL, all_status_5xx is right on both. No all_requests exists, so denominators still need requests + compute_requests.