@cryptotaxi247 / kubo / commits / 0954d249c

docs: clarify provide stats metric types and calculations (#11041)

add "Understanding the Metrics" section explaining three types: - per-worker rates (multiply by active workers for total throughput) - per-region averages (do NOT multiply by worker count) - system totals (cumulative across all workers) enhance metric descriptions with: - explicit calculation examples showing which worker counts to use - warnings about when NOT to multiply by worker count - cross-references to relevant sections add "Capacity Planning" section with: - step-by-step throughput capacity calculations - diagnostic guidance for common scenarios - worked examples for estimating required vs actual capacity addresses confusion from PR #11034 comments about when to multiply metrics by worker count and how to interpret per-worker rates

Marcin Rataj committed Nov 12, 2025 at 03:24 UTC 0954d249c2be3bb952de1ebcd71bad56b529350f
1 file changed +86 -9
docs/provide-stats.md
+86 -9
@@ -4,6 +4,34 @@ The `ipfs provide stat` command gives you statistics about your local provide
4 system. This file provides a detailed explanation of the metrics reported by
5 this command.
6
7 +## Understanding the Metrics
8 +
9 +The statistics are organized into three types of measurements:
10 +
11 +### Per-worker rates
12 +
13 +Metrics like "CIDs reprovided/min/worker" measure the throughput of a single
14 +worker processing one region. To estimate total system throughput, multiply by
15 +the number of active workers of that type (see [Workers stats](#workers-stats)).
16 +
17 +Example: If "CIDs reprovided/min/worker" shows 100 and you have 10 active
18 +periodic workers, your total reprovide throughput is approximately 1,000
19 +CIDs/min.
20 +
21 +### Per-region averages
22 +
23 +Metrics like "Avg CIDs/reprovide" measure properties of the work units (keyspace
24 +regions). These represent the average size or characteristics of a region, not a
25 +rate. Do NOT multiply these by worker count.
26 +
27 +Example: "Avg CIDs/reprovide: 250,000" means each region contains an average of
28 +250,000 CIDs that get reprovided together as a batch.
29 +
30 +### System totals
31 +
32 +Metrics like "Total CIDs provided" are cumulative counts since node startup.
33 +These aggregate all work across all workers over time.
34 +
35 ## Connectivity
36
37 ### Status
@@ -148,19 +176,31 @@ regions are automatically retried unless the node is offline.
176
177 Average rate of initial provides per minute per worker during the last
178 reprovide cycle (excludes reprovides). Each worker handles one keyspace region
151 -at a time, providing all CIDs in that region. This rate only counts active time
152 -(timer doesn't run when no initial provides are being processed). The overall
153 -provide rate can be higher when multiple workers are providing different
154 -regions concurrently.
179 +at a time, providing all CIDs in that region. This measures the throughput of a
180 +single worker only.
181 +
182 +To estimate total system provide throughput, multiply by the number of active
183 +burst workers shown in [Workers stats](#workers-stats) (Burst > Active).
184 +
185 +Note: This rate only counts active time when initial provides are being
186 +processed. If workers are idle, actual throughput may be lower.
187
188 ### CIDs reprovided/min/worker
189
190 Average rate of reprovides per minute per worker during the last reprovide
191 cycle (excludes initial provides). Each worker handles one keyspace region at a
160 -time, reproviding all CIDs in that region. The overall reprovide rate can be
161 -higher when multiple workers are reproviding different regions concurrently. To
162 -estimate total reprovide rate, multiply by the number of [periodic
163 -workers](./config.md#providedhtdedicatedperiodicworkers) in use.
192 +time, reproviding all CIDs in that region. This measures the throughput of a
193 +single worker only.
194 +
195 +To estimate total system reprovide throughput, multiply by the number of active
196 +periodic workers shown in [Workers stats](#workers-stats) (Periodic > Active).
197 +
198 +Example: If this shows 100 CIDs/min and you have 10 active periodic workers,
199 +your total reprovide throughput is approximately 1,000 CIDs/min.
200 +
201 +Note: This rate only counts active time when regions are being reprovided. If
202 +workers are idle due to network issues or queue exhaustion, actual throughput
203 +may be lower.
204
205 ### Region reprovide duration
206
@@ -170,6 +210,13 @@ Average time to reprovide all CIDs in a region during the last cycle.
210
211 Average number of CIDs per region during the last reprovide cycle.
212
213 +This measures the average size of a region (how many CIDs are batched together),
214 +not a throughput rate. Do NOT multiply this by worker count.
215 +
216 +Combined with [Region reprovide duration](#region-reprovide-duration), this
217 +helps estimate per-worker throughput: dividing Avg CIDs/reprovide by Region
218 +reprovide duration gives CIDs/min/worker.
219 +
220 ### Regions reprovided (last cycle)
221
222 Number of regions reprovided in the last cycle.
@@ -189,11 +236,16 @@ Number of idle workers not reserved for periodic or burst tasks.
236 Breakdown of worker status by type (periodic for scheduled reprovides, burst for
237 initial provides). For each type:
238
192 -- **Active**: Currently processing operations
239 +- **Active**: Currently processing operations (use this count when calculating total throughput from per-worker rates)
240 - **Dedicated**: Reserved for this type
241 - **Available**: Idle dedicated workers + [free workers](#free-workers)
242 - **Queued**: 0 or 1 (workers acquired only when needed)
243
244 +The number of active workers determines your total system throughput. For
245 +example, if you have 10 active periodic workers, multiply
246 +[CIDs reprovided/min/worker](#cids-reprovidedminworker) by 10 to estimate total
247 +reprovide throughput.
248 +
249 See [provide queue](#provide-queue) and [reprovide queue](#reprovide-queue) for
250 regions waiting to be processed.
251
@@ -202,6 +254,31 @@ regions waiting to be processed.
254 Maximum concurrent DHT server connections per worker when sending provider
255 records for a region.
256
257 +## Capacity Planning
258 +
259 +### Estimating if your system can keep up with the reprovide schedule
260 +
261 +To check if your provide system has sufficient capacity:
262 +
263 +1. Calculate required throughput:
264 + - Required CIDs/min = [CIDs scheduled](#cids-scheduled) / ([Reprovide interval](#reprovide-interval) in minutes)
265 + - Example: 67M CIDs / (22 hours × 60 min) = 50,758 CIDs/min needed
266 +
267 +2. Calculate actual throughput:
268 + - Actual CIDs/min = [CIDs reprovided/min/worker](#cids-reprovidedminworker) × Active periodic workers
269 + - Example: 100 CIDs/min/worker × 256 active workers = 25,600 CIDs/min
270 +
271 +3. Compare:
272 + - If actual < required: System is underprovisioned, increase [MaxWorkers](./config.md#providedhtmaxworkers) or [DedicatedPeriodicWorkers](./config.md#providedhtdedicatedperiodicworkers)
273 + - If actual > required: System has excess capacity
274 + - If [Reprovide queue](#reprovide-queue) is growing: System is falling behind
275 +
276 +### Understanding worker utilization
277 +
278 +- High active workers with growing reprovide queue: Need more workers or network connectivity is limiting throughput
279 +- Low active workers with non-empty reprovide queue: Workers may be waiting for network or DHT operations
280 +- Check [Reachable peers](#reachable-peers) to diagnose network connectivity issues
281 +
282 ## See Also
283
284 - [Provide configuration reference](./config.md#provide)