Proposal: Exposing fetch metrics - count

[ahmedRaaft73]

Background & Context

SWR is an exceptionally lightweight, performant, and reliable data-fetching library that has consistently been a go to choice for our modern React stack. Its minimalist API and focus on core cache revalidation principles make it a joy to work with.

The Problem

While scaling a production complex dashboard/application, I encountered a scenario where I needed to track the exact execution count of fetches for a given key.

Upon reviewing the official documentation, I noticed that SWR does not natively expose request metrics (like fetchCount or retry attempt counters) A capability that libraries like TanStack Query offer out of the box.

In large scale applications, enterprise dashboards, or performance monitoring setups, tracking fetch frequency and timing is crucial for:

1. Executing specific business logic or side effects based on revalidation thresholds.
2. Preventing unintended continuous re-fetches during edge case state updates.
3. Telemetry, logging, and debugging cache behaviors at scale.

To solve this in the short term, I had to write a custom React state/ref wrapper around useSWR and the fetcher logic. While completely functional, it adds boilerplate that could ideally be handled more natively or cleanly.

---

Proposal & Discussion

Given SWR’s design philosophy of keeping the core footprint minimal, I propose exploring one of the following approaches:

1. Native Return Property: Exposing a lightweight fetchCount counter on the SWRResponse object.
2. Official Middleware Solution: Introducing a built in telemetry utility under swr/middleware or documenting a standard pattern/recipe in the official docs for metric tracking.

Custom Implementation Reference

For context, here is the lightweight wrapper pattern I implemented to handle this in userland:

import { useRef, useCallback } from 'react';
import useSWR, { SWRConfiguration, SWRResponse } from 'swr';

interface SWRMetrics {
  fetchCount: number;
  lastDurationMs: number;
}

export function useSWRWithMetrics<Data Error="any" any,>(
  key: string | null,
  fetcher: (...args: any[]) => Promise<Data>,
  config?: SWRConfiguration
): SWRResponse<Data, Error> & SWRMetrics {
  const fetchCountRef = useRef<number>(0);
  const lastDurationRef = useRef<number>(0);

  const trackedFetcher = useCallback(
    async (k: string) => {
      fetchCountRef.current += 1;
      const startTime = performance.now();
      try {
        const result = await fetcher(k);
        lastDurationRef.current = performance.now() - startTime;
        return result;
      } catch (error) {
        lastDurationRef.current = performance.now() - startTime;
        throw error;
      }
    },
    [fetcher]
  );

  const swr = useSWR<Data, Error>(key, trackedFetcher, config);

  return {
    ...swr,
    fetchCount: fetchCountRef.current,
    lastDurationMs: lastDurationRef.current,
  };
}

[ismaeelakin]

A middleware recipe seems a good fit for the telemetry part. SWR already documents a fetcher-wrapping request logger, which is the right place to count actual fetcher invocations, rather than hook renders or revalidation requests.

Two semantics are worth making explicit in this proposal:

• Several hooks with the same key can share one deduplicated fetch. A per-hook useRef count is therefore not a shared per-key count.
• Writing lastDurationRef.current does not notify React. If SWR returns unchanged data, a consumer subscribed only to data need not render to expose the new duration. A ref snapshot is fine for internal bookkeeping, but is not a reactive metrics API.

For a non-reactive telemetry sink, this is a small starting point:

import { unstable_serialize } from 'swr';

function createMetrics(report) {
  const counts = new Map();
  return useSWRNext => (key, fetcher, config) => {
    const id = unstable_serialize(key);
    const measured = fetcher && (async (...args) => {
      const count = (counts.get(id) ?? 0) + 1;
      counts.set(id, count);
      const start = performance.now();
      try {
        return await fetcher(...args);
      } finally {
        report({ key: id, count, durationMs: performance.now() - start });
      }
    });
    return useSWRNext(key, measured, config);
  };
}

Create that middleware once per cache/provider session, not during every render, and pass it through SWRConfig's use option. report must not throw; otherwise a telemetry failure could replace the fetcher's result/error. For metrics displayed in the UI, connect the sink to a subscribed external store instead of expecting the ref mutation to cause a render.

I checked this pattern with SWR 2.3.6 / React 18.3.1: two hooks sharing a key produced one initial event; an explicit same-data revalidation produced the second; a rejected attempt produced the third. The counter includes failures/retries, and measures fetcher duration, not necessarily HTTP wire requests: a fetcher may itself cache or make several requests.

That definition also clarifies a native API proposal: specify whether counters belong to a hook, key, cache provider, or application session, and whether UI reactivity is part of the contract. I cannot speak for whether the maintainers plan to add it to core.

[ahmedRaaft73]

Thanks for the great feedback and insight!

You raised a really valid point regarding key deduplication across hooks and the non-reactive nature of useRef.

Just to clarify the context of my original workaround in my specific use case, I was trying to track fetch counts specifically during retry attempts after a request failure. Since SWR updates its internal state (like isValidating or error) on each retry attempt, it naturally triggers a re-render for the component. This made the useRef approach sufficient for my immediate UI needs, even if it relied on SWR's secondary re-renders.

That said, I totally agree that for an official pattern or telemetry middleware, handling shared key counts natively and following proper React reactivity principles is the right way to go.

Glad to hear the idea of adding a Telemetry - Metrics Middleware recipe resonates well! I'm planning to open a PR soon to address this and contribute a proper implementation.