参加你附近的 ,了解 VS Code 中的 AI 辅助开发。

遥测扩展作者指南

Visual Studio Code 收集使用数据并将其发送给 Microsoft,以帮助改进我们的产品和服务。请阅读我们的隐私声明遥测文档以了解更多信息。

本主题包含面向扩展作者的指南,以便他们的扩展能够符合 VS Code 的遥测要求和最佳实践。

注意:如果您不想向 Microsoft 发送使用数据,可以将 telemetry.telemetryLevel 用户设置off

遥测模块

VS Code 团队维护@vscode/extension-telemetry npm 模块,该模块提供了一种一致且安全的方式来在 VS Code 中收集遥测数据。该模块将遥测数据报告给Azure Monitor 和 Application Insights,并保证与以前的 VS Code 版本向后兼容。

请遵循本指南设置 Azure Monitor 并获取您的 Application Insights 检测密钥。

不使用遥测模块

不希望使用 Application Insights 的扩展作者可以利用自己的自定义解决方案发送遥测数据。在这种情况下,仍要求扩展作者通过使用 isTelemetryEnabledonDidChangeTelemetryEnabled API 来尊重用户的选择。通过这样做,用户将有一个集中式的位置来控制他们的遥测设置。

自定义遥测设置

扩展可能希望让用户独立于 VS Code 遥测控制特定于扩展的遥测。在这种情况下,我们建议您引入一个特定的扩展设置。建议自定义遥测设置标记为 telemetryusesOnlineServices,以便用户可以在设置 UI 中更轻松地查询它们。添加自定义遥测设置并不能免除尊重用户决定的责任,并且必须始终尊重 isTelemetryEnabledonDidChangeTelemetryEnabled 标志。如果 isTelemetryEnabled 报告为 false,即使您的设置已启用,也绝不能发送遥测数据。

telemetry.json

我们理解遥测对于许多用户来说可能是一个敏感话题,我们力求尽可能透明。核心 VS Code 产品和大多数第一方扩展都在其根目录中附带一个 telemetry.json 文件。这允许用户使用带有 --telemetry 标志的 VS Code CLI 来接收 VS Code 生成的所有遥测数据的转储。扩展作者可以在其根目录中包含一个 telemetry.json 文件,它也将出现在 CLI 转储中。

须知和禁忌

✔️ 建议

  • 如果使用 Application Insights 适合您,请使用 @vscode/extension-telemetry npm 模块。
  • 否则,请尊重 isTelemetryEnabledonDidChangeTelemetryEnabled API。
  • 如果您有自定义遥测设置,请将其标记为 telemetryusesOnlineServices
  • 尽可能少地收集遥测数据。
  • 尽可能透明地向用户说明您收集了什么。

❌ 不建议

  • 引入一个不要求用户同意的自定义遥测收集解决方案。
  • 收集个人身份信息 (PII)。
  • 收集不必要的遥测数据。
  • 仅使用 telemetry.telemetryLevel 设置,因为它有时可能与 isTelemetryEnabled 不一致。