1. 文件
  2. Go 遠端監控

Go 遠端監控

目錄

背景
概觀
組態
計數器
報告與上傳
圖表
遠端監控提案
編寫提示
常見問題

背景

Go 遠端監控是 Go 工具程式蒐集其效能和使用方式資料的一種方式。此處的「Go 工具程式」是指 Go 團隊維護的開發者工具，包括 go 指令和補充工具，例如 Go 語言伺服器 gopls 或 Go 安全工具 govulncheck。Go 遠端監控僅供 Go 團隊及其選擇性相依關係維護的程式使用，例如 Delve。

預設情況下，遠端監控資料只會保留在本地電腦，但使用者可以選擇將核准的遠端監控資料子集上傳至 telemetry.go.dev。上傳的資料有助於 Go 團隊藉由了解使用狀況和中斷問題來改善 Go 語言及其工具。

「遙測數據」一詞在開放原始碼軟體的世界中帶有一些負面含義，在許多情況下是應得的。然而，衡量使用者體驗是現代軟體工程的重要元素，而且像 GitHub 問題或年度調查等資料來源是粗略且落後的指標，不足以回答 Go 團隊需要回答的問題類型。Go 遠程監測資料旨在協助工具鏈中的程式收集有關其可靠性、效能和用量的有用資料，同時還能維護使用者期望從 Go 專案取得的透明度和隱私權。若要深入瞭解遙測數據的設計程序和動機，請參閱 遙測數據網誌文章。若要深入瞭解遙測數據與隱私權，請參閱 遙測數據隱私權政策。

本頁詳細說明 Go 遠程監測資料的工作原理。若要快速取得關於常見問題的解答，請參閱 常見問題集。

使用 Go 1.23 或更新版本，若要選擇加入將遙測數據上傳至 Go 團隊，請執行
go telemetry on
若要完全停用遙測數據，包括本機收集，請執行
go telemetry off
若要回復到僅限本機傳輸的預設模式，請執行
go telemetry local
在 Go 1.23 之前，也可使用 golang.org/x/telemetry/cmd/gotelemetry 指令執行此操作。請參閱 組態 以取得更多詳細資訊。

概觀

Go 遠程監測資料使用三個核心資料類型

所有本機 Go 遠程監測資料和組態都儲存在目錄 os.UserConfigDir()/go/telemetry 中。以下我們稱呼這個目錄為 <gotelemetry>。

下方的圖解說明這個資料流程。

在本文件其他部分中，我們將探討此圖解的組成部分。不過首先，我們來深入瞭解控制它的組態。

組態

Go 遠程監測資料的行為由一個值控制：遙測數據的模式。mode 的可能值為 local (預設)、on 或 off。

使用 Go 1.23 或更新版本，下列命令會與遙測模式互動

透過唯讀 Go 環境變數，也可以取得遙測組態的資訊

gotelemetry 命令也可以用來組態遙測模式，以及檢查本機遙測資料。使用此命令來安裝

go install golang.org/x/telemetry/cmd/gotelemetry@latest

如需 gotelemetry 命令列工具的完整使用資訊，請參閱其 套件文件。

計數器

如上述所提，Go 遙測是透過 計數器 來進行測量的。計數器有兩種變體：基本計數器和堆疊計數器。

基本計數器

基本計數器 是一個可增值的數值，名為它所計數的事件的描述。例如，gopls/client:vscode 計數器會記錄 VS Code 初始化 gopls 會話的次數。在此計數器旁邊，我們可能有 gopls/client:neovim、gopls/client:eglot 等，來記錄使用不同編輯器或語言用戶端的會話。如果您在一週內使用多個編輯器，您可能會記錄下列計數器資料

gopls/client:vscode 8
gopls/client:neovim 5
gopls/client:eglot  2

當計數器是以這種方式關聯時，我們有時會將 : 之前的部分稱為 圖表名稱（此例為 gopls/client），而將 : 之後的部份稱為 區塊名稱（vscode）。當我們討論 圖表 時，您將了解為什麼這很重要。

基本計數器也可以表示 直方圖。例如，gopls/completion/latency:<50ms 計數器會記錄自動完成花費少於 50ms 的次數。

gopls/completion/latency:<10ms
gopls/completion/latency:<50ms
gopls/completion/latency:<100ms
...

這種記載直方圖資料的模式是一種慣例：<50ms 區塊名稱並沒有什麼特別之處。此種類型的計數器通常用於測量效能。

堆疊計數器

堆疊計數器 是一種也會在計數增加時記錄 Go 工具鏈程式當前呼叫堆疊的計數器。例如，crash/crash 堆疊計數器會在工具鏈程式發生異常時記錄呼叫堆疊

crash/crash
golang.org/x/tools/gopls/internal/golang.hoverBuiltin:+22
golang.org/x/tools/gopls/internal/golang.Hover:+94
golang.org/x/tools/gopls/internal/server.Hover:+42
...

堆疊計數器通常測量程式不變部分遭到破壞的事件。這些事件最常見的範例是當機，但另一個範例是 gopls/bug 堆疊計數器，它會計數程式設計師預先辨識出的異常情況，例如已復原的恐慌或「不可能發生」的錯誤。堆疊計數器只包含 Go 工具鏈程式內的功能名稱和程式碼行號。它們不包含任何使用者的輸入資訊，例如使用者的原始碼的檔名或內容。

堆疊計數器有助於追蹤罕見或棘手的錯誤，這些錯誤不會透過其他方式回報。自從引入 gopls/bug 計數器以來，我們已發現 許多個實例 在實務中已到達「無法到達」的程式碼，追蹤這些例外情況已導致發現（並修正）許多對使用者可見的錯誤，這些錯誤對於使用者而言要嘛不顯著，要嘛太難回報。尤其是在預先發布測試時，堆疊計數器可以協助我們比無法自動化的情況更有效率地改善產品。

計數器檔案

所有計數器資料會寫入 <gotelemetry>/local 目錄，檔案名稱根據以下架構命名

[program name]@[program version]-[go version]-[GOOS]-[GOARCH]-[date].v1.count

這些檔案會記憶體對映到已編制的程式各個執行個體。使用記憶體對映的檔案表示即使程式當場當機，或是同時執行多個已編制的工具副本，堆疊計數器也會安全地記錄下來。

回報和上傳

大約每週一次，計數器資料會累計到 <gotelemetry>/local 目錄中名為 <date>.json 的報告中。這些報告會加總前一周的所有計數，然後依據用於計數器檔案的相同程式識別符（程式名稱、程式版本、Go 版本、GOOS 和 GOARCH）加以分組。

可以使用 gotelemetry view 指令以圖表方式查看本機報告。以下是 gopls/completion/latency 計數器的範例摘要

上傳

如果已啟用遠端量測上傳，每週報告程序還會產生報告，其中包含 上傳設定檔 中存在的對應項次子集。這些對應項次必須經過下一部分所述的公眾審查程序核准。成功上傳後，上傳報告的副本會儲存在 <gotelemetry>/upload 目錄中。

一旦有足夠多的使用者選擇加入上傳遠端量測資料，上傳程序將會隨機略過上傳一部分報告，以減少收集量並在維持統計顯著性的同時提升隱私性。

圖表

除了接受上傳， telemetry.go.dev 網站也會公開上傳的資料。每日會將上傳報告處理成兩個產出的資料，並會顯示在 telemetry.go.dev 首頁。

圖表會根據 圖表設定檔 套件的格式指定。例如，以下為 gopls/client 圖表的圖表設定檔。

title: Editor Distribution
counter: gopls/client:{vscode,vscodium,vscode-insiders,code-server,eglot,govim,neovim,coc.nvim,sublimetext,other}
description: measure editor distribution for gopls users.
type: partition
issue: https://go.dev.org.tw/issue/61038
issue: https://go.dev.org.tw/issue/62214 # add vscode-insiders
program: golang.org/x/tools/gopls
version: v0.13.0 # temporarily back-version to demonstrate config generation.

這個設定檔描述要產生的圖表，列舉要彙整的一組對應項次，並且指定圖表適用的程式版本。此外，提案程序 還要求已經接受的提案要與圖表關聯。以下是根據該設定檔產生的圖表

遠端量測提案程序

telemetry.go.dev 上的上傳設定檔或圖表組的變更必須經過遠端量測提案程序，此程序的目的是確保遠端量測設定檔變更的透明度。

特別是，這個程序中其實並未區分上傳設定檔與圖表設定檔。上傳設定檔本身會用我們想要在 telemetry.go.dev 上呈現的彙總方式來表示，這項原則的基礎為我們只應該收集我們想要查看的資料。

提案程序如下

  1. 提案者建立一個修改 config.txt 的 CL，針對 chartconfig 套件，包含必要的新的計數器聚合。
  2. 提案者建立 提案 來合併此 CL。
  3. 在問題討論後，Go 團隊的成員將核准或駁回此提案。
  4. 自動化流程將重新產生上傳設定，以允許上傳新圖表所需之計數器。此流程也會定期將相關程式的新版本加入上傳設定，以在它們釋出後上傳。

新的圖表必須要符合以下條件才能通過核准：不能載有敏感的使用者資訊，且必須是有用的以及可行的。圖表必須有明確的目的，提供有用的結果，才稱得上是有用的。圖表必須能夠可靠收集必要的資料，而所產生的量測在統計上具有顯著性，才稱得上是可行的。為了證明可行性，提案者可能會被要求針對目標程式加上計數器，並先在當地收集計數器。

這類提案的全部集合可以在 GitHub 上的 提案專案 中找到。

編寫提示

為了讓遙測功能回答我們想提出的各種問題，我們需要參與上傳功能的使用者不一定要很多，約略 16,000 人參與就能在所需細緻度下進行統計顯著的量測。然而，在建立這些有價值的樣本仍會有一些成本：我們需要詢問大量的 Go 開發者是否願意參與。

此外，即使有大量使用者選擇在 當下 參與（例如，在閱讀 Go 部落格文章後），這些使用者可能會偏向有經驗的 Go 開發者，而隨著時間推移，這個初始樣本將會變得更偏。另外，當人們更換電腦時，他們必須進行主動選擇才能再次參與。在遙測部落格文章系列中，這稱為參與模式的 “參與成本”。

為了讓參與的使用者樣本持續保持新鮮，Go 語言伺服器 gopls 支援提示，詢問使用者是否願意參與 Go 遙測功能。以下是這項提示在 VS Code 中的樣貌

如果使用者選擇“是”，他們的遙測 模式 會設定為 開啟，就好像他們執行了 gotelemetry 開啟 指令一樣。這樣一來，參與方式盡可能簡單，我們可以持續接觸到大量的異質性 Go 開發者樣本。

常見問題

問：如何啟用或停用 Go telemetry？

答：使用可透過 go install golang.org/x/telemetry/cmd/gotelemetry@latest 安裝的 gotelemetry 指令。執行 gotelemetry off 以停用所有內容，甚至本機收集。執行 gotelemetry on 以啟用所有內容，包括將核准的計數器上傳至 telemetry.go.dev。請參閱 設定 部分以取得更多資訊。

問：本機資料儲存在哪裡？

答：在 os.UserConfigDir()/go/telemetry 目錄中。

問：如果我選擇參與，資料上傳頻率為何？

答：大約每週一次。

問：如果我選擇參與，會上傳哪些資料？

答：只有列在 上傳設定 中的計數器才會被上傳。這是從 [圖表設定] 中產生的，它可能更易於讀取。

問：計數器如何新增到上傳設定？

答：透過 公開提案流程。

問：可以在哪裡查看已上傳的 Telemetry 資料？

答：已上傳的資料可以在 telemetry.go.dev 中以圖表或合併摘要的方式取得。

問：Go telemetry 的原始程式碼在哪裡？

答：位於 golang.org/x/telemetry。

go.dev 使用 Google 提供的 Cookie 來傳遞並提升其服務品質，以及分析流量。 了解更多。