feat(telemetry): collect high level provide DHT sweep settings (#11056)
* telemetry: collect provideDHTSweepEnabled Fixes #11055. * telemetry: track custom Provide.DHT.Interval and MaxWorkers collects whether users customize Interval and MaxWorkers from defaults to help identify if defaults need adjustment * docs: improve telemetry documentation structure and clarity restructure docs/telemetry.md into meaningful sections (routing & discovery, content providing, network configuration), add exact config field paths for all tracked settings, and establish code as source of truth by linking from LogEvent struct while removing redundant field comments --------- Co-authored-by: Marcin Rataj <lidel@lidel.org>
Hector Sanjuan committed
Nov 13, 2025 at 00:28 UTC
d45c615e736be68f9091c8788d9756496e852b3e
3 files changed
+59
-27
docs/telemetry.md
+43
-17
@@ -47,25 +47,51 @@ Or in your IPFS config file:
47
The telemetry plugin collects the following anonymized data:
48
49
### General Information
50
-- **Agent version**: The version of Kubo being used.
51
-- **Platform details**: Operating system, architecture, and container status.
52
-- **Uptime**: How long the node has been running, categorized into buckets.
53
-- **Repo size**: Categorized into buckets (e.g., 1GB, 5GB, 10GB, etc.).
50
+
51
+- **UUID**: Anonymous identifier for this node
52
+- **Agent version**: Kubo version string
53
+- **Private network**: Whether running in a private IPFS network
54
+- **Repository size**: Categorized into privacy-preserving buckets (1GB, 5GB, 10GB, 100GB, 500GB, 1TB, 10TB, >10TB)
55
+- **Uptime**: Categorized into privacy-preserving buckets (1d, 2d, 3d, 7d, 14d, 30d, >30d)
56
+
57
+### Routing & Discovery
58
+
59
+- **Custom bootstrap peers**: Whether custom `Bootstrap` peers are configured
60
+- **Routing type**: The `Routing.Type` configured for the node
61
+- **Accelerated DHT client**: Whether `Routing.AcceleratedDHTClient` is enabled
62
+- **Delegated routing count**: Number of `Routing.DelegatedRouters` configured
63
+- **AutoConf enabled**: Whether `AutoConf.Enabled` is set
64
+- **Custom AutoConf URL**: Whether custom `AutoConf.URL` is configured
65
+- **mDNS**: Whether `Discovery.MDNS.Enabled` is set
66
+
67
+### Content Providing
68
+
69
+- **Provide and Reprovide strategy**: The `Provide.Strategy` configured
70
+- **Sweep-based provider**: Whether `Provide.DHT.SweepEnabled` is set
71
+- **Custom Interval**: Whether custom `Provide.DHT.Interval` is configured
72
+- **Custom MaxWorkers**: Whether custom `Provide.DHT.MaxWorkers` is configured
73
74
### Network Configuration
56
-- **Private network**: Whether the node is running in a private network.
57
-- **Bootstrap peers**: Whether custom bootstrap peers are used.
58
-- **Routing type**: Whether the node uses DHT, IPFS, or a custom routing setup.
59
-- **AutoNAT settings**: Whether AutoNAT is enabled and its reachability status.
60
-- **AutoConf settings**: Whether AutoConf is enabled and whether a custom URL is used.
61
-- **Swarm settings**: Whether hole punching is enabled, and whether public IP addresses are used.
62
-
63
-### TLS and Discovery
64
-- **AutoTLS settings**: Whether WSS is enabled and whether a custom domain suffix is used.
65
-- **Discovery settings**: Whether mDNS is enabled.
66
-
67
-### Reprovider Strategy
68
-- The strategy used for reprovider (e.g., "all", "pinned"...).
75
+
76
+- **AutoNAT service mode**: The `AutoNAT.ServiceMode` configured
77
+- **AutoNAT reachability**: Current reachability status determined by AutoNAT
78
+- **Hole punching**: Whether `Swarm.EnableHolePunching` is enabled
79
+- **Circuit relay addresses**: Whether the node advertises circuit relay addresses
80
+- **Public IPv4 addresses**: Whether the node has public IPv4 addresses
81
+- **Public IPv6 addresses**: Whether the node has public IPv6 addresses
82
+- **AutoWSS**: Whether `AutoTLS.AutoWSS` is enabled
83
+- **Custom domain suffix**: Whether custom `AutoTLS.DomainSuffix` is configured
84
+
85
+### Platform Information
86
+
87
+- **Operating system**: The OS the node is running on
88
+- **CPU architecture**: The architecture the node is running on
89
+- **Container detection**: Whether the node is running inside a container
90
+- **VM detection**: Whether the node is running inside a virtual machine
91
+
92
+### Code Reference
93
+
94
+Data is organized in the `LogEvent` struct at [`plugin/plugins/telemetry/telemetry.go`](https://github.com/ipfs/kubo/blob/master/plugin/plugins/telemetry/telemetry.go). This struct is the authoritative source of truth for all telemetry data, including privacy-preserving buckets for repository size and uptime. Note that this documentation may not always be up-to-date - refer to the code for the current implementation.
95
96
---
97
plugin/plugins/telemetry/telemetry.go
+13
-10
@@ -78,6 +78,7 @@ var uptimeBuckets = []time.Duration{
78
}
79
80
// A LogEvent is the object sent to the telemetry endpoint.
81
+// See https://github.com/ipfs/kubo/blob/master/docs/telemetry.md for details.
82
type LogEvent struct {
83
UUID string `json:"uuid"`
84
@@ -91,7 +92,10 @@ type LogEvent struct {
92
93
UptimeBucket time.Duration `json:"uptime_bucket"`
94
94
- ReproviderStrategy string `json:"reprovider_strategy"`
95
+ ReproviderStrategy string `json:"reprovider_strategy"`
96
+ ProvideDHTSweepEnabled bool `json:"provide_dht_sweep_enabled"`
97
+ ProvideDHTIntervalCustom bool `json:"provide_dht_interval_custom"`
98
+ ProvideDHTMaxWorkersCustom bool `json:"provide_dht_max_workers_custom"`
99
100
RoutingType string `json:"routing_type"`
101
RoutingAcceleratedDHTClient bool `json:"routing_accelerated_dht_client"`
@@ -352,6 +356,7 @@ func (p *telemetryPlugin) Start(n *core.IpfsNode) error {
356
func (p *telemetryPlugin) prepareEvent() {
357
p.collectBasicInfo()
358
p.collectRoutingInfo()
359
+ p.collectProvideInfo()
360
p.collectAutoNATInfo()
361
p.collectAutoConfInfo()
362
p.collectSwarmInfo()
@@ -360,13 +365,6 @@ func (p *telemetryPlugin) prepareEvent() {
365
p.collectPlatformInfo()
366
}
367
363
-// Collects:
364
-// * AgentVersion
365
-// * PrivateNetwork
366
-// * RepoSizeBucket
367
-// * BootstrappersCustom
368
-// * UptimeBucket
369
-// * ReproviderStrategy
368
func (p *telemetryPlugin) collectBasicInfo() {
369
p.event.AgentVersion = ipfs.GetUserAgentVersion()
370
@@ -406,8 +404,6 @@ func (p *telemetryPlugin) collectBasicInfo() {
404
break
405
}
406
p.event.UptimeBucket = uptimeBucket
409
-
410
- p.event.ReproviderStrategy = p.config.Provide.Strategy.WithDefault(config.DefaultProvideStrategy)
407
}
408
409
func (p *telemetryPlugin) collectRoutingInfo() {
@@ -416,6 +412,13 @@ func (p *telemetryPlugin) collectRoutingInfo() {
412
p.event.RoutingDelegatedCount = len(p.config.Routing.DelegatedRouters)
413
}
414
415
+func (p *telemetryPlugin) collectProvideInfo() {
416
+ p.event.ReproviderStrategy = p.config.Provide.Strategy.WithDefault(config.DefaultProvideStrategy)
417
+ p.event.ProvideDHTSweepEnabled = p.config.Provide.DHT.SweepEnabled.WithDefault(config.DefaultProvideDHTSweepEnabled)
418
+ p.event.ProvideDHTIntervalCustom = !p.config.Provide.DHT.Interval.IsDefault()
419
+ p.event.ProvideDHTMaxWorkersCustom = !p.config.Provide.DHT.MaxWorkers.IsDefault()
420
+}
421
+
422
type reachabilityHost interface {
423
Reachability() network.Reachability
424
}
test/cli/telemetry_test.go
+3
@@ -205,6 +205,9 @@ func TestTelemetry(t *testing.T) {
205
"repo_size_bucket",
206
"uptime_bucket",
207
"reprovider_strategy",
208
+ "provide_dht_sweep_enabled",
209
+ "provide_dht_interval_custom",
210
+ "provide_dht_max_workers_custom",
211
"routing_type",
212
"routing_accelerated_dht_client",
213
"routing_delegated_count",