Observing an IPFS gateway from the outside
Cloudflare has run an IPFS gateway since 2018, moving from research experiment to a supported product offering. To guide that evolution, the team needed hard numbers on how the gateway actually performs under real-world conditions. The result is the IPFS Gateway monitor, an open-source tool that runs scripted scenarios against any gateway endpoint and exports the results to Prometheus. The tool has already surfaced some useful findings about cached versus fresh content, IPNS resolution, and DNSLink lookup times.
Why IPFS needs special monitoring
IPFS is a fully distributed storage and retrieval network. Unlike a typical website, an IPFS gateway doesn't just answer HTTP requests — it has to find and fetch content from peers on the network first. That means content routing, peer discovery, and sometimes IPNS name resolution all happen before a byte is returned to the user. Since any of those steps can add latency, basic uptime checks aren't enough. To understand gateway health, you have to measure end-to-end retrieval across different content types and freshness states.
How the monitor is built
The project on GitHub is split into three independent pieces:
ipfs-gw-measure— runs a single measurement scenario against a gateway URL.ipfs-gw-monitor— invokes the measurement tool repeatedly.- Prometheus Exporter — publishes the resulting metrics in Prometheus format.
A scenario is a scripted user action timed against a known network state. For example, measuring how long a gateway takes to retrieve content that was just uploaded versus content that is likely already cached. The accompanying code can also spin up a fresh IPFS node so test content is guaranteed to be hosted and current. The gateway itself is treated as a black box — all measurements go through its public API.
Measuring immutable IPFS content
IPFS content is addressed by content hash, or CID, and is immutable. Users request it by putting the CID in the gateway URL path. Three scenarios cover the most common retrieval patterns.
Content that is popular enough to be cached returns quickly. In the team's measurements, this was around 116ms. Freshly uploaded content is slower — it isn't cached yet, and the gateway has to discover it on the network. The test uploads a random 32-byte block for this scenario. Non-existent content is the worst case. Because IPFS content routing gives no definitive "not found" signal, the gateway can only wait until a timeout fires. On Cloudflare's endpoint, that timeout is currently around five minutes.
Measuring mutable IPNS content
Since CIDs are immutable, IPFS offers the InterPlanetary Naming System (IPNS) to give content a stable, mutable address. An IPNS name is derived from the publisher's public key, and the mapping from name to CID lives in the IPFS DHT. A gateway resolving an IPNS URL has to do two lookups — first the name to CID, then the CID to content.
Beyond the three standard retrieval scenarios, two IPNS-specific cases were measured: resolving an existing IPNS name, and resolving a name immediately after new content is published beneath it.
Measuring DNSLink-hosted sites
DNSLink goes one step further, mapping a regular domain name to IPFS content via a TXT record with a value like dnslink=/ipfs/baf…1. The result is a domain-name-based address that is easier to read and share than either a raw CID or an IPNS name.
DNSLink content can be fetched two ways from a gateway: using the domain directly as the hostname URL (for example, https://ipfs.example.com), or putting the domain in the path of a gateway URL (https://cloudflare-ipfs.com/ipns/ipfs.example.com). Both were measured.
Scenarios | Min (s) | Max (s) | Avg (s) | |
|---|---|---|---|---|
1 | dnslink/ipfs-domain-as-url-hostname | 0.251 | 18.6 | 0.831 |
2 | dnslink/ipfs-domain-as-url-path | 0.148 | 1.70 | 0.346 |
3 | dnslink/ipns-domain-as-url-hostname | 7.87 | 44.2 | 21.0 |
4 | dnslink/ipns-domain-as-url-path | 6.87 | 72.6 | 19.0 |
What the numbers suggest
Across scenarios, caching dominates. Locating content that is already cached is about an order of magnitude faster than discovering fresh content, which aligns with how IPFS publication and propagation work. For mutable naming, DNSLink came out ahead of IPNS in testing. The gap is likely tied to how quickly IPNS name updates propagate through the IPFS DHT — a resolver could speed that up without sacrificing the trust benefits IPNS offers.
The monitor remains an active project on GitHub and will continue to expand. The broader direction is clear: gateways like Cloudflare's can offer lower retrieval latency than going fully peer-to-peer while preserving IPFS content validity for the user. The next measurement round will focus on how Cloudflare's distributed network of data centers can be used to serve the IPFS network more effectively.
