配置 AWS CDK CLI 遥测 - AWS Cloud Development Kit (AWS CDK) v2
什么是 CDK CLI 遥测？如何选择退出 CDK CLI 遥测将遥测数据发送到本地文件

这是 AWS CDK v2 开发者指南。旧版 CDK v1 于 2022 年 6 月 1 日进入维护阶段，并于 2023 年 6 月 1 日终止支持。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

配置 AWS CDK CLI 遥测

什么是 CDK CLI 遥测？

重要

AWS CDK CLI 遥测仅在 CDK CLI 版本 2.1100. AWS 0 及更高版本中收集。

C AWS loud Development Kit (AWS CDK) 收集有关 CLI 使用情况的遥测数据，以提供汇总的使用模式和错误频率，这将帮助我们识别影响 CDK CLI 用户群的广泛问题。

默认情况下，客户可以选择使用 CLI 遥测数据收集。您可以使用下面列出的方法选择退出 CDK CLI 遥测。

AWS CDK 在收集遥测数据时严格考虑数据最小化，防止识别或归因于特定的用户、账户或组织。下面提供了默认情况下收集的指标的详尽列表及其原因。没有收集进一步的遥测数据或指标。

请注意，我们目前没有收集错误消息、堆栈跟踪和日志，并且此数据收集将在未来的 CDK CLI 版本中以明确的选择方式提供。有关这些指标的更多信息可以在表格中找到。

正在收集的数据如下：

指标 说明 Reason 示例

CDK CLI 版本

CLI 版本 (x.y.z)

收集这些数据将有助于我们按版本将数据一分为二，这可以帮助我们识别有问题的版本。

 
"2.1100.0"

安装 ID

在执行 CLI 命令的本地计算机上存储的随机 UUID

这有助于我们估算受错误影响的不同用户数量。每台独一无二的计算机都有自己的安装 ID，该安装ID是通过 UUID V4 随机生成的。

 
"881d3281-2811-4c86-b7b6-4a8a621cf6f2"

会话 ID

每次调用 CLI 命令时都会生成随机 UUID

这可以帮助我们识别源自同一命令的所有事件。

 
"c47e3d55-bc20-406b-a02a-e0285dd63230"

事件 ID

会话 ID 加上一个计数器

这将为会话中的每个事件创建一个唯一的标识符。

 
"c47e3d55-bc20-406b-a02a-e0285dd63230:0"

Region

AWS 区域

这将帮助我们将数据一分为二，以解决特定区域的问题。

 
"us-east-1"

Timestamp

将数据发送到我们的遥测端点的时间（由客户端生成）

这将帮助我们生成时间序列图。

 
"2025-12-12T00:00:00.000Z"

事件状态

事件的 “结果”。可能的值为 “成功”、“失败”、“已中止”

这将帮助我们跟踪每个 CLI 命令的错误率，并在客户报告潜在的回归之前提醒我们注意这些错误。

 
"SUCCESS"

事件类型

生成数据的事件类型的标识符

这是一个枚举，用于标识所发生的事件类型，因为命令执行中可能有多个事件。

 
"SYNTH"

命令路径

在 CLI 中输入的命令和属性，所有自由文本都经过了编辑

除了命令参数外，这些信息还有助于确定所发生事件的行为，这有助于我们确定爆炸半径和出现问题的原因。

 
["cdk", "deploy", "$STACK1"]

命令参数

在 CLI 中输入的可选参数，所有自由文本都经过了删改

除了命令路径外，这些信息还有助于确定所发生事件的行为，这有助于我们确定爆炸半径和出现问题的原因。

 
{
  all: true,
  concurrency: 4
}

配置

可能影响 CLI 命令的其他参数（即 cdk.context.json 或 cdk.json /中的上下文值~/.cdk.json），且所有自由文本都已被删掉

这将为我们提供可能影响 CLI 行为的所有可能参数的全面视图，从而帮助我们简化调试。

 
{
  context: {
    "@aws-cdk/core:explicitStackTags": true
  }
}

操作系统

正在使用的操作系统

这将帮助我们调试仅影响特定操作系统的问题。

 
{
  platform: "linux",
  release: "5.15.0-1019-aws",
}

CI/CD

是否正在从 CI/CD 环境中调用 CLI 命令

这将帮助我们确定特定于 CI/CD 环境的问题。

 
false

节点版本

环境中使用的节点版本

这将帮助我们调试出现的任何特定于节点的问题。

 
"v22.0.0"

Duration

事件的长度（以毫秒为单位）

这可以帮助我们注意到特定事件需要多长时间的模式。

 
{ total: 300 }

计数器

从 CDK 应用程序和 CLI 执行中得出的各种计数器指标

我们将监控（但不限于）CFN 资源计数等统计数据对部署持续时间的影响。

 
{
  resourceCount: 25,
  errorCount: 0,
  warningCount: 2,
}

依赖项

相关的 AWS 依赖项及其版本

我们计划跟踪可能影响 CLI 结果的 AWS 依赖项，例如 jsii aws-cdk-lib、projen 等。我们只会收集对特定 AWS 拥有的库的依赖关系。

 
[{ "aws-cdk-lib": "2.232.0"}]

错误名称

错误的名称（如果发生错误）。

我们只记录自己控制的错误名称，这有助于识别反复出现的错误类型。

 
"ToolkitError"

以下指标需要明确选择加入，目前尚未收集：

错误消息

如果发生错误，则返回错误消息。已编辑自由格式文本

[需要选择加入] 捕获错误消息将帮助我们以更快的速度汇总遇到错误的数据，并帮助我们调试各个用例中出了什么问题。

目前未收集

错误堆栈跟踪

错误消息的堆栈跟踪（如果发生错误）。已编辑自由格式文本

[需要选择加入] 堆栈跟踪将有助于个人调试，也是我们能够重现可能出现的问题所必需的。

目前未收集

错误日志

CLI 命令失败的日志（如果发生错误）。已编辑自由格式文本

[需要选择加入] 错误日志还将帮助我们调试和重现在 CLI 中看到的问题。

目前未收集

如何选择退出 CDK CLI 遥测

要根据上下文值和环境变量查看当前遥测状态，请运行下面的命令：

cdk cli-telemetry --status

使用上下文值选择退出

如果不同来源的上下文值存在冲突，CDK 将使用下面的优先顺序。

  1. 使用带有 --context 选项的 CDK CLI 命令指定的上下文值

  2. cdk.json 中的上下文值

  3. cdk.context.json 中的上下文值

  4. ~/.cdk.json 中的上下文值

使用 CDK CLI 命令选择退出

运行下面的 CDK CLI 命令来禁用遥测：

cdk cli-telemetry --disable

运行此命令会将操作记录到您的本地 cdk.context.json 文件中，并且仅适用于当前 CDK 应用程序。

使用应用程序配置文件选择退出

在应用程序的 cdk.json 文件中设置 cli-telemetry: false。这会禁用应用程序的遥测。

使用全局配置文件选择退出

在 ~/.cdk.json 文件中设置 cli-telemetry: false，以便为同一台计算机上的所有 CDK 应用程序禁用遥测。您必须在上下文元素中指定此设置，如下所示：

{
  "context": {
    "cli-telemetry": false
  }
}

使用环境变量选择退出

将 CDK_DISABLE_CLI_TELEMETRY 环境变量设置为 true，以便在该环境中禁用 CLI 遥测。

CDK_DISABLE_CLI_TELEMETRY=true

此环境变量的值优先于任何已设置的上下文值。

提示

将此环境变量添加到 shell 启动文件（例如 .bashrc）中，以在每次打开终端窗口时禁用遥测。

使用 DNS 过滤选择退出

遥测端点是。cdk-cli-telemetry.us-east-1.api.aws/metrics在防火墙中屏蔽此域名会禁用 CLI 遥测功能，并且不会影响 CDK CLI 功能。

选择退出所有使用情况数据报告

要选择退出单个命令的所有使用情况数据报告，请使用 --no-version-reporting 全局 CLI 选项。此选项会同时关闭应用程序使用情况数据收集和 CDK CLI 遥测。

如果您当前正在使用 --no-version-reporting 选项选择退出应用程序使用情况数据收集，则无论上下文值如何，您都会自动选择退出该特定命令执行的 CDK CLI 遥测。

注意

如果您在堆栈级别设置 analyticsReporting，则它优先于仅收集应用程序使用情况数据的 --no-version-reporting 选项。

将遥测数据发送到本地文件

如果您想要继续选择加入 CDK CLI 遥测，则可以选择将遥测数据发送到本地文件。然后，您可以查看该文件以审计我们所收集的遥测数据。

在任何 CDK CLI 命令上使用以下选项将遥测数据发送到本地文件：

注意

如果您使用的是低于 2.1100.0 的 AWS CDK CLI 版本，则必须同时指定。--unstable=telemetry --telemetry-file

--telemetry-file='path/to/local/file'

例如，deploy以下命令将遥测数据发送到本地文件：

cdk deploy --telemetry-file='path/to/local/file'