テレメトリ拡張機能作成者向けガイド

Visual Studio Code は、製品およびサービスの改善に役立てるため、使用状況データを収集して Microsoft に送信します。詳細については、プライバシー ステートメントおよびテレメトリ ドキュメントをお読みください。

本トピックでは、拡張機能が VS Code のテレメトリ要件およびベストプラクティスに準拠するためのガイドラインを提供します。

注: Microsoft への使用状況データの送信を希望しない場合は、ユーザー設定の telemetry.telemetryLevel を off に設定してください。

テレメトリモジュール

VS Code チームは、VS Code 内で一貫した安全な方法でテレメトリを収集するための @vscode/extension-telemetry npm モジュールを保守しています。このモジュールは、Azure Monitor および Application Insights にテレメトリを報告し、VS Code の旧バージョンとの後方互換性を保証します。

本ガイドに従って Azure Monitor をセットアップし、Application Insights インストゥルメンテーションキーを取得してください。

テレメトリモジュールを使用しない場合

Application Insights を使用したくない拡張機能作成者は、独自のカスタムソリューションを利用してテレメトリを送信できます。その場合でも、拡張機能作成者は isTelemetryEnabled API および onDidChangeTelemetryEnabled API を使用してユーザーの選択を尊重することが求められます。これを行うことで、ユーザーはテレメトリ設定を一元管理できるようになります。

カスタムテレメトリ設定

拡張機能によっては、VS Code のテレメトリとは別に、拡張機能固有のテレメトリに対するユーザー制御を提供したい場合があります。その場合は、特定の拡張機能設定を導入することをお勧めします。カスタムテレメトリ設定には telemetry および usesOnlineServices タグを付けることを推奨します。これにより、ユーザーは設定 UI でそれらをより簡単に検索できるようになります。カスタムテレメトリ設定を追加した場合でも、ユーザーの決定を尊重する義務が免除されるわけではなく、isTelemetryEnabled および onDidChangeTelemetryEnabled フラグを常に尊重する必要があります。isTelemetryEnabled が false を返す場合、たとえ拡張機能の設定が有効であっても、テレメトリを送信してはなりません。

telemetry.json

テレメトリは多くのユーザーにとって繊細なトピックになり得ることを理解しており、可能な限り透明性を保つことを目指しています。VS Code のコア製品およびほとんどの主要な拡張機能には、ルートディレクトリに telemetry.json ファイルが含まれています。これにより、ユーザーは --telemetry フラグを付けて VS Code CLI を使用することで、VS Code が生成するすべてのテレメトリのダンプを取得できます。拡張機能作成者もルートに telemetry.json ファイルを含めることができ、それも CLI ダンプに表示されます。

推奨事項と禁止事項

✔️ するべきこと

• Application Insights で問題ない場合は、@vscode/extension-telemetry npm モジュールを使用してください。
• そうでない場合は、isTelemetryEnabled API および onDidChangeTelemetryEnabled API を尊重してください。
• カスタムテレメトリ設定がある場合は、telemetry および usesOnlineServices タグを付けてください。
• 収集するテレメトリは可能な限り最小限に抑えてください。
• 何を収集するかについて、ユーザーに対して可能な限り透明性を保ってください。

❌ すべきでないこと

• ユーザーの同意を求めないカスタムテレメトリ収集ソリューションを導入することは避けてください。
• 個人を特定できる情報 (PII) は収集しないでください。
• 必要以上にテレメトリを収集しないでください。
• telemetry.telemetryLevel 設定のみを使用しないでください（isTelemetryEnabled と比較して正しくない場合があるためです）。