Go テレメトリー

背景
 概要
 設定
 カウンター
 レポートとアップロード
 チャート
 テレメトリーの提案
 IDE プロンプト
 よくある質問

背景

Go テレメトリーは、Go ツールチェインプログラムがそのパフォーマンスと使用状況に関するデータを収集するための方法です。ここで「Go ツールチェイン」とは、Go チームが保守する開発者ツールを意味し、go コマンドや、Go 言語サーバー gopls や Go セキュリティツール govulncheck などの補助ツールが含まれます。Go テレメトリーは、Go チームが保守するプログラムと、Delve のような選定された依存関係でのみ使用されることを意図しています。

デフォルトでは、テレメトリーデータはローカルコンピューターにのみ保存されますが、ユーザーは承認されたテレメトリーデータのサブセットを telemetry.go.dev にアップロードすることを選択できます。アップロードされたデータは、使用状況や障害を理解するのに役立ち、Go チームが Go 言語とそのツールを改善するのに役立ちます。

「テレメトリー」という言葉は、オープンソースソフトウェアの世界で、多くの場合当然のことながら、否定的な意味合いを持つようになりました。しかし、ユーザーエクスペリエンスを測定することは現代のソフトウェアエンジニアリングの重要な要素であり、GitHub の課題や年次調査などのデータソースは粗く遅延指標であり、Go チームが答える必要がある種類の質問には不十分です。Go テレメトリーは、ユーザーが Go プロジェクトに期待する透明性とプライバシーを維持しながら、ツールチェイン内のプログラムがその信頼性、パフォーマンス、および使用状況に関する有用なデータを収集するのに役立つように設計されています。テレメトリーの設計プロセスと動機について詳しく知るには、テレメトリーブログ記事を参照してください。テレメトリーとプライバシーについて詳しく知るには、テレメトリープライバシーポリシーを参照してください。

このページでは、Go テレメトリーがどのように機能するかを詳しく説明します。よくある質問への簡単な回答については、FAQ を参照してください。

Go 1.23 以降を使用する場合、テレメトリーデータを Go チームにアップロードすることをオプトインするには、以下を実行します。

go telemetry on

ローカル収集を含むテレメトリーを完全に無効にするには、以下を実行します。

go telemetry off

ローカルのみのテレメトリーのデフォルトモードに戻すには、以下を実行します。

go telemetry local

Go 1.23 より前では、golang.org/x/telemetry/cmd/gotelemetry コマンドでもこれを行うことができます。設定で詳細を確認してください。

概要

Go テレメトリーは、3つの主要なデータタイプを使用します。

カウンターは、ツールチェインプログラムで計測される、名前付きイベントの軽量なカウントです。収集が有効になっている場合（モードがlocalまたはon）、カウンターはローカルファイルシステムのメモリマップドファイルに書き込まれます。
レポートは、特定の週のカウンターの集計サマリーです。アップロードが有効になっている場合（モードがon）、承認されたカウンターのレポートは telemetry.go.dev にアップロードされ、公開されます。
チャートは、すべてのユーザーのアップロードされたレポートを要約します。チャートは telemetry.go.dev で表示できます。

すべてのローカル Go テレメトリーデータと設定は、os.UserConfigDir()/go/telemetry ディレクトリに保存されます。以下では、このディレクトリを<gotelemetry>と呼びます。

以下の図は、このデータフローを示しています。

このドキュメントの残りの部分では、この図のコンポーネントについて説明します。しかし、まず、それを制御する構成について学びましょう。

設定

Go テレメトリーの動作は、単一の値、つまりテレメトリーのモードによって制御されます。mode の取りうる値は、local（デフォルト）、on、または off です。

modeがlocalの場合、テレメトリーデータはローカルコンピューターで収集および保存されますが、リモートサーバーにはアップロードされません。
modeがonの場合、データは収集され、サンプリングに応じてアップロードされることがあります。
mode が off の場合、データは収集もアップロードもされません。

Go 1.23 以降では、以下のコマンドがテレメトリーモードと連携します。

go telemetry: 現在のモードを表示します。
go telemetry on: モードをonに設定します。
go telemetry off: モードをoffに設定します。
go telemetry local: モードをlocalに設定します。

テレメトリーの設定に関する情報は、読み取り専用の Go 環境変数からも利用できます。

go env GOTELEMETRYはテレメトリーモードを報告します。
go env GOTELEMETRYDIR はテレメトリーの設定とデータが格納されているディレクトリを報告します。

gotelemetry コマンドは、テレメトリーモードの設定だけでなく、ローカルのテレメトリーデータを検査するためにも使用できます。このコマンドをインストールするには、次のようにします。

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

gotelemetry コマンドラインツールの完全な使用情報については、そのパッケージドキュメントを参照してください。

カウンター

前述の通り、Go テレメトリーはカウンターを介して計測されます。カウンターには、基本カウンターとスタックカウンターの2種類があります。

基本カウンター

基本カウンターは、カウントするイベントを記述する名前を持つインクリメント可能な値です。たとえば、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
...

スタックカウンターは通常、プログラムの不変条件が破られたイベントを測定します。最も一般的な例はクラッシュですが、もう1つの例は gopls/bug スタックカウンターで、プログラマーによって事前に識別された異常な状況 (リカバリされたパニックや「ありえない」エラーなど) をカウントします。スタックカウンターには、Go ツールチェーンプログラム内の関数の名前と行番号のみが含まれます。ユーザーの入力に関する情報 (ユーザーのソースコードの名前や内容など) は一切含まれません。

スタックカウンターは、他の手段では報告されないまれなバグや厄介なバグを追跡するのに役立ちます。gopls/bug カウンターを導入して以来、実際に到達された「到達不能」なコードの数十のインスタンスを発見し、これらの例外を追跡することで、ユーザーには明らかでなかったり、報告するのが難しすぎたりした多くのユーザーに見えるバグの発見（および修正）につながりました。特にプレリリーステストでは、スタックカウンターは自動化なしでは不可能だったよりも効率的に製品を改善するのに役立ちます。

カウンターファイル

すべてのカウンターデータは、<gotelemetry>/local ディレクトリに、以下のスキーマに従って命名されたファイルに書き込まれます。

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

プログラム名は、debug.BuildInfoが報告するプログラムのパッケージパスのベース名です。
プログラムバージョンとGoバージョンもdebug.BuildInfoによって報告されます。
GOOSとGOARCHの値は、runtime.GOOSとruntime.GOARCHによって報告されます。
日付は、カウンターファイルが作成された日付で、YYYY-MM-DD形式です。

これらのファイルは、計測されたプログラムの各実行中のインスタンスにメモリマップされます。メモリマップドファイルを使用することで、プログラムがすぐにクラッシュした場合や、計測されたツールが複数同時に実行されている場合でも、カウンターが安全に記録されます。

レポートとアップロード

約週に一度、カウンターデータは<gotelemetry>/localディレクトリ内の<date>.jsonという名前のレポートに集約されます。これらのレポートは、前週のすべてのカウントを、カウンターファイルで使用されるのと同じプログラム識別子（プログラム名、プログラムバージョン、Goバージョン、GOOS、GOARCH）でグループ化して合計します。

ローカルレポートは、gotelemetry view コマンドでチャートとして表示できます。以下は、gopls/completion/latency カウンターのサマリーの例です。

アップロード

テレメトリーのアップロードが有効になっている場合、週次レポートプロセスは、アップロード設定に存在するカウンターのサブセットを含むレポートも生成します。これらのカウンターは、次のセクションで説明する公開レビュープロセスによって承認される必要があります。アップロードが成功すると、アップロードされたレポートのコピーは<gotelemetry>/uploadディレクトリに保存されます。

十分な数のユーザーがテレメトリーデータのアップロードをオプトインすると、統計的有意性を維持しつつ収集量を減らしプライバシーを高めるために、アップロードプロセスはレポートの一部をランダムにスキップします。

チャート

アップロードの受け入れに加えて、telemetry.go.dev ウェブサイトはアップロードされたデータを公開しています。毎日、アップロードされたレポートは2つの出力に処理され、telemetry.go.dev のホームページで利用できます。

マージされたレポートは、指定された日に受信されたすべてのアップロードからカウンターをマージします。
チャートは、提案プロセスの一部として作成された[チャート設定]に指定されたアップロードデータをプロットします。カウンターの議論から、foo:barのようなカウンター名は、チャート名fooとバケット名barに分解されることを思い出してください。各チャートは、同じチャート名を持つカウンターを対応するバケットに集約します。

チャートは、chartconfig パッケージの形式で指定されます。たとえば、以下は 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.dokyumento.jp/issue/61038
issue: https://go.dokyumento.jp/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 でレンダリングしたい集計の観点から表現されます。

提案プロセスは次のとおりです。

提案者は、chartconfig パッケージの config.txt を変更する CL を作成し、希望する新しいカウンター集計を含めます。
提案者は、この CL をマージするための提案を提出します。
イシューに関する議論が解決されると、提案は Go チームのメンバーによって承認または却下されます。
自動プロセスにより、新しいチャートに必要なカウンターのアップロードを許可するためにアップロード設定が再生成されます。このプロセスでは、関連するプログラムの新しいバージョンがリリースされるたびに、定期的にアップロード設定に追加されます。

承認されるためには、新しいチャートは機密性の高いユーザー情報を含まず、さらに有用かつ実現可能である必要があります。有用であるためには、チャートは特定の目的を果たし、実行可能な成果につながる必要があります。実現可能であるためには、必要なデータを確実に収集できる必要があり、その結果得られる測定値は統計的に有意である必要があります。実現可能性を実証するために、提案者は、まずターゲットプログラムをカウンターで計測し、ローカルで収集するように求められる場合があります。

これらの提案の全セットは、GitHub の提案プロジェクトで入手できます。

IDE プロンプト

テレメトリーが私たちが尋ねたい種類の質問に答えるためには、アップロードにオプトインするユーザーの数が多くなくても構いません。約16,000人の参加者がいれば、希望する粒度で統計的に有意な測定が可能になります。しかし、この健全なサンプルを組み立てるには依然としてコストがかかります。多くのGo開発者にオプトインを希望するかどうか尋ねる必要があります。

さらに、たとえ多くのユーザーが今オプトインすることを選択したとしても（おそらくGoブログの投稿を読んだ後）、それらのユーザーは経験豊富なGo開発者に偏っている可能性があり、時間が経つにつれてその初期サンプルはさらに偏りが大きくなるでしょう。また、人々がコンピューターを交換する際には、再び積極的にオプトインを選択する必要があります。テレメトリーブログ記事シリーズでは、これをオプトインモデルの「キャンペーン費用」と呼んでいます。

参加ユーザーのサンプルを新鮮に保つために、Go 言語サーバー gopls は、ユーザーに Go テレメトリーへのオプトインを促すプロンプトをサポートしています。VS Code では次のように表示されます。

ユーザーが「はい」を選択すると、gotelemetry onを実行したかのように、テレメトリーモードはonに設定されます。このようにして、オプトインは可能な限り簡単になり、私たちはGo開発者の大規模で層別化されたサンプルに継続的に到達することができます。

よくある質問

Q: Go テレメトリーを有効または無効にするにはどうすればよいですか？

A: go install golang.org/x/telemetry/cmd/gotelemetry@latest でインストールできる gotelemetry コマンドを使用してください。ローカル収集を含め、すべてを無効にするには gotelemetry off を実行します。telemetry.go.dev への承認されたカウンターのアップロードを含め、すべてを有効にするには gotelemetry on を実行します。詳細については、設定セクションを参照してください。

Q: ローカルデータはどこに保存されますか？

A: os.UserConfigDir()/go/telemetry ディレクトリに保存されます。

Q: オプトインした場合、データはどのくらいの頻度でアップロードされますか？

A: 約週に一度です。

Q: オプトインした場合、どのようなデータがアップロードされますか？

A: アップロード設定に記載されているカウンターのみがアップロードされます。これは、より読みやすい[チャート設定]から生成されます。

Q: カウンターはどのようにアップロード設定に追加されますか？

A: 公開提案プロセスを通じて。

Q: アップロードされたテレメトリーデータはどこで見られますか？

A: アップロードされたデータは、telemetry.go.devでチャートまたはマージされたサマリーとして利用できます。

Q: Go テレメトリーのソースコードはどこにありますか？

A: golang.org/x/telemetry にあります。