feat(provide): detailed ipfs provide stat

[guillaumemichel]

• Depends on provider: stats libp2p/go-libp2p-kad-dht#1144
• Closes provider: display stats for new provide system #10900
• Part of Integrate Modernized Provider System from go-libp2p-kad-dht #10881

Introducing stats for the new provide system (sweep), using ipfs provide stat.

Help section

$ ipfs provide stat --help
WARNING:   EXPERIMENTAL, command may change in future releases

USAGE
  ipfs provide stat - Returns statistics about the node's provider system.

SYNOPSIS
  ipfs provide stat [--lan] [--all | -a] [--compact] [--connectivity] [--network] [--schedule]
                    [--timings] [--workers] [--operations] [--queues]

OPTIONS

  --lan           bool - Show stats for LAN DHT only (for Sweep+Dual DHT only).
  -a, --all       bool - Display all provide sweep stats.
  --compact       bool - Display stats in 2-column layout (requires --all).
  --connectivity  bool - Display DHT connectivity status.
  --network       bool - Display network stats (peers, reachability, region size).
  --schedule      bool - Display reprovide schedule (CIDs/regions scheduled, next reprovide time).
  --timings       bool - Display timing information (uptime, cycle start, reprovide interval).
  --workers       bool - Display worker pool stats (active/available/queued workers).
  --operations    bool - Display operation stats (ongoing/past provides, rates, errors).
  --queues        bool - Display provide and reprovide queue sizes.

DESCRIPTION

  Returns statistics about the content the node is reproviding every
  Provide.DHT.Interval according to Provide.Strategy:
  https://github.com/ipfs/kubo/blob/master/docs/config.md#provide
  
  This command displays statistics for the provide system currently in use
  (Sweep or Legacy). If using the Legacy provider, basic statistics are shown
  and no flags are supported. The following behavior applies to the Sweep
  provider only:
  
  By default, displays a brief summary of key metrics including queue sizes,
  scheduled CIDs/regions, average record holders, ongoing/total provides, and
  worker status (if low on workers).
  
  Use --all to display comprehensive statistics organized into sections:
  connectivity (DHT status), queues (pending provides/reprovides), schedule
  (CIDs/regions to reprovide), timings (uptime, cycle info), network (peers,
  reachability, region size), operations (provide rates, errors), and workers
  (pool utilization).
  
  Individual sections can be displayed using their respective flags (e.g.,
  --network, --operations, --workers). Multiple section flags can be combined.
  
  The --compact flag provides a 2-column layout suitable for monitoring with
  'watch' (requires --all). Example: watch ipfs provide stat --all --compact
  
  For Dual DHT setups, use --lan to show statistics for the LAN DHT provider
  instead of the default WAN DHT provider.
  
  This interface is not stable and may change from release to release.

Default behavior

Brief summary of the most important metrics:

$ ipfs provide stat       
Provide queue:       0 CIDs, 0 regions
Reprovide queue:     0 regions
CIDs scheduled:      7k (7,926)
Regions scheduled:   499
Avg record holders:  12.2
Ongoing provides:    0 CIDs, 0 regions
Ongoing reprovides:  0 CIDs, 0 regions
Total CIDs provided: 8k      (8,486)

If the provide is low on workers it also includes additional metrics on workers

Active workers:      15 / 16 (max)
Periodic workers:    1 active,  1 available, 0 queued
Burst workers:       14 active, 0 available, 1 queued

And if the DHT provider is disconnected or offline it also prints the Connectivity:

Status: offline

All metrics

$ ipfs provide stat --all
Connectivity:
  Status: online (2025-10-08 21:04:01)

Queues:
  Provide queue:   0 CIDs, 0 regions
  Reprovide queue: 0 regions

Schedule:
  CIDs scheduled:    7k (7,926)
  Regions scheduled: 499
  Avg prefix length: 9
  Next reprovide at: 21:25:01
  Next prefix:       100010100

Timings:
  Uptime:              3h2m8.7s (2025-10-08 18:21:58)
  Current time offset: 3h2m8.7s
  Cycle started:       2025-10-08 18:21:58
  Reprovide interval:  22h0m0s

Network:
  Avg record holders:     12.2
  Peers swept:            1k (1,731)
  Reachable peers:        1k (1,009) (58%)
  Avg region size:        31.4
  Full keyspace coverage: false
  Replication factor:     20

Operations:
  Ongoing provides:                0 CIDs, 0 regions
  Ongoing reprovides:              0 CIDs, 0 regions
  Total CIDs provided:             8k      (8,504)
  Total records provided:          103k    (103,977)
  Total provide errors:            0
  CIDs provided/min:               17.8
  CIDs reprovided/min:             25.6
  Region reprovide duration:       37.7s
  Avg CIDs/reprovide:              17.2
  Regions reprovided (last cycle): 61

Workers:
  Active workers: 0 / 16 (max)
  Free workers:   13
  Worker stats:      Periodic  Burst
    Active:        0         0
    Dedicated:     2         1
    Available:     15        14
    Queued:        0         0
  Max connections/worker: 16

Compact mode

Since the output of --all stats is quite long, it may not fit on the screen. The compact mode comes to the rescue. It was made to be run with watch to monitor the provide metrics over time (watch ipfs provide stat --all --compact).

$ ipfs provide stat --all --compact
Schedule:                          Connectivity:
  CIDs scheduled: 7k (7,778)         Status: online (2025-10-08 18:22:13)
  Regions scheduled: 512
  Avg prefix length: 9             Queues:
  Next reprovide at: 18:47:45        Provide queue: 596 CIDs, 111 regions
  Next prefix: 101011001             Reprovide queue: 0 regions

Network:                           Timings:
  Avg record holders: 12.3           Uptime: 24m1.3s (2025-10-08 18:21:58)
  Peers swept: 215                   Current time offset: 24m1.3s
  Reachable peers: 130 (60%)         Cycle started: 2025-10-08 18:21:58
  Avg region size: 31.4              Reprovide interval: 22h0m0s
  Full keyspace coverage: false
  Replication factor: 20           Operations:
                                     Ongoing provides: 166 CIDs, 14 regions
Workers:                             Ongoing reprovides: 0 CIDs, 0 regions
  Active: 14 / 16 (max)              Total CIDs provided: 6k     (6,659)
  Free: 0                            Total records provided: 82k (82,321)
  Worker stats:    Periodic  Burst   Total provide errors: 0
    Active:        0         14      CIDs provided/min: 21.1
    Dedicated:     2         1       CIDs reprovided/min: 23.3
    Available:     2         0       Region reprovide duration: 36.7s
    Queued:        0         1       Avg CIDs/reprovide: 14.2
  Max connections/worker: 16         Regions reprovided (last cycle): 8

Section only

It is possible to filter a single stats section

$ ipfs provide stat --network
Avg record holders:     12.2
Peers swept:            1k (1,801)
Reachable peers:        1k (1,055) (58%)
Avg region size:        31.4
Full keyspace coverage: false
Replication factor:     20

Or multiple sections

$ ipfs provide stat --schedule --operations --workers
Schedule:
  CIDs scheduled:    7k (7,926)
  Regions scheduled: 499
  Avg prefix length: 9
  Next reprovide at: 21:30:10
  Next prefix:       100011010

Operations:
  Ongoing provides:                0 CIDs, 0 regions
  Ongoing reprovides:              0 CIDs, 0 regions
  Total CIDs provided:             8k      (8,535)
  Total records provided:          104k    (104,403)
  Total provide errors:            0
  CIDs provided/min:               17.8
  CIDs reprovided/min:             25.7
  Region reprovide duration:       37.5s
  Avg CIDs/reprovide:              17.2
  Regions reprovided (last cycle): 63

Workers:
  Active workers: 0 / 16 (max)
  Free workers:   13
  Worker stats:      Periodic  Burst
    Active:        0         0
    Dedicated:     2         1
    Available:     15        14
    Queued:        0         0
  Max connections/worker: 16

LAN DHT

If using the Dual DHT (default behavior), ipfs provide stat will show numbers about the WAN DHT provider by default. If you want to show stats about the LAN DHT provider, you can use the --lan flag.

$ ipfs provide stat --lan                
Status:              offline
Provide queue:       0 CIDs, 0 regions
Reprovide queue:     0 regions
CIDs scheduled:      7k (7,926)
Regions scheduled:   0
Avg record holders:  N/A
Ongoing provides:    0 CIDs, 0 regions
Ongoing reprovides:  0 CIDs, 0 regions
Total CIDs provided: 0

My LAN client isn't active, since no other peers on my LAN.

When using the accelerated DHT client (along with Provide Sweep), there is only one DHT to display stats (WAN).

Demo

In a terminal session:

rm -rf "${IPFS_PATH:-$HOME/.ipfs}" # remove previous ipfs config/repo, if you want a clean start
ipfs init
ipfs config --json Provide.DHT.SweepEnabled true # enable new provider system
ipfs daemon

Monitor new stats in a second session:

watch ipfs provide stat --all --compact

Import a lot of CIDs in a third session:

ipfs get -p QmdmQXB2mzChmMeKY47C43LxUdg1NDJ5MWcKMKxDu7RgQm # XKCD Archives ~7k CIDs

The newly added CIDs will be added to the provide queue, and will be reprovided as needed.

Sit back and watch as the system gracefully handles the provider announcements in real-time 🚀

Checklist

• Update command description (--help)
• Changelog
• Add metrics description in md file
• Merge provider: stats libp2p/go-libp2p-kad-dht#1144
• Update go-libp2p-kad-dht dependency on master

[guillaumemichel]

@lidel what is the best place to add a brief description about individual metrics?

• don't want to overload the --help section
• don't want to include verbose description in ipfs provide stat command output
• we could link from the --help section to a md document (e.g new kubo/docs/stats.md)?
• alternatively, a --verbose flag could add a short sentence after each metric (not compatible with --compact)

[lidel]

@guillaumemichel ok to include in --help, we have long ones like https://docs.ipfs.tech/reference/kubo/cli/#ipfs-add but if its trully a lot, fine to put a new file in ./docs and have --help refer to https://github.com/ipfs/kubo/blob/master/docs/provide-stats.md for docs.

[lidel]

@guillaumemichel lgtm, feel free to merge libp2p/go-libp2p-kad-dht#1144, then we can switch this to kad-dht@main and squash merge.