@cryptotaxi247 / kubo
Code Commits Issues Pulls Sessions CI/CD
master
master
md 149 lines 5.55 KB
Rendered Raw
1 # Telemetry Plugin Documentation
2
3 The **Telemetry plugin** is a feature in Kubo that collects **anonymized usage data** to help the development team better understand how the software is used, identify areas for improvement, and guide future feature development.
4
5 This data is not personally identifiable and is used solely for the purpose of improving the Kubo project.
6
7 ---
8
9 ## 🛡️ How to Control Telemetry
10
11 The behavior of the Telemetry plugin is controlled via the environment variable [`IPFS_TELEMETRY`](environment-variables.md#ipfs_telemetry) and optionally via the `Plugins.Plugins.telemetry.Config.Mode` in the IPFS config file.
12
13 ### Available Modes
14
15 | Mode | Description |
16 |----------|-----------------------------------------------------------------------------|
17 | `on` | **Default**. Telemetry is enabled. Data is sent periodically. |
18 | `off` | Telemetry is disabled. No data is sent. Any existing telemetry UUID file is removed. |
19 | `auto` | Like `on`, but logs an informative message about the telemetry and gives user 15 minutes to opt-out before first collection. This mode is automatically used on the first run when `IPFS_TELEMETRY` is not set and telemetry UUID is not found (not generated yet). The informative message is only shown once. |
20
21 You can set the mode in your environment:
22
23 ```bash
24 export IPFS_TELEMETRY="off"
25 ```
26
27 Or in your IPFS config file:
28
29 ```json
30 {
31 "Plugins": {
32 "Plugins": {
33 "telemetry": {
34 "Config": {
35 "Mode": "off"
36 }
37 }
38 }
39 }
40 }
41 ```
42
43 ---
44
45 ## 📦 What Data is Collected?
46
47 The telemetry plugin collects the following anonymized data:
48
49 ### General Information
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
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
98 ## 🧑‍🤝‍🧑 Privacy and Anonymization
99
100 All data collected is:
101 - **Anonymized**: No personally identifiable information (PII) is sent.
102 - **Optional**: Users can choose to opt out at any time.
103 - **Secure**: Data is sent over HTTPS to a trusted endpoint.
104
105 The telemetry UUID is stored in the IPFS repo folder and is used to identify the node across runs, but it does not contain any personal information. When you opt-out, this UUID file is automatically removed to ensure complete privacy.
106
107 ---
108
109 ## 📦 Contributing to the Project
110
111 By enabling telemetry, you are helping the Kubo team improve the software for the entire community. The data is used to:
112
113 - Prioritize feature development
114 - Identify performance bottlenecks
115 - Improve user experience
116
117 You can always disable telemetry at any time if you change your mind.
118
119 ---
120
121 ## 🧪 Testing Telemetry
122
123 If you're testing telemetry locally, you can change the endpoint by setting the `Endpoint` field in the config:
124
125 ```json
126 {
127 "Plugins": {
128 "Plugins": {
129 "telemetry": {
130 "Config": {
131 "Mode": "on",
132 "Endpoint": "http://localhost:8080"
133 }
134 }
135 }
136 }
137 }
138 ```
139
140 This allows you to capture and inspect telemetry data locally.
141
142 ---
143
144 ## 📦 Further Reading
145
146 For more information, see:
147 - [IPFS Environment Variables](docs/environment-variables.md)
148 - [IPFS Plugins](docs/plugins.md)
149 - [IPFS Configuration](docs/config.md)