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

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

# 配置 AWS CDK CLI 遥测
<a name="cli-telemetry"></a>

## 什么是 CDK CLI 遥测？
<a name="telemetry-intro"></a>

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

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

默认情况下，客户可以选择使用 CLI 遥测数据收集。您可以使用[下面列出的方法](#telemetry-opt-out)选择退出 CDK CLI 遥测。

 AWS CDK 在收集遥测数据时严格考虑数据最小化，防止识别或归因于特定的用户、账户或组织。下面提供了默认收集的指标的详尽列表以及动机。此列表可能会随着时间的推移而变化；任何更改都将始终伴随着动机，并尊重匿名和数据最小化原则。

我们目前没有收集完整的错误消息、堆栈跟踪和日志。如果这些数据是在未来的 CDK CLI 版本中收集的，则它将始终处于明确的选择加入状态。有关这些指标的更多信息可以在表格中找到。

正在收集的数据如下：


<table>
<thead>
  <tr><th>指标</th><th>说明</th><th>Reason</th><th>示例</th></tr>
</thead>
<tbody>
  <tr><td>CDK CLI 版本</td><td>CLI 版本 (x.y.z)</td><td>收集这些数据将有助于我们按版本将数据一分为二，这可以帮助我们识别有问题的版本。</td><td> 

```
"2.1100.0"
``` </td></tr>
  <tr><td>安装 ID</td><td>在执行 CLI 命令的本地计算机上存储的随机 UUID</td><td>这有助于我们估算受错误影响的不同用户数量。每台独一无二的计算机都有自己的安装 ID，该安装ID是通过 UUID V4 随机生成的。</td><td> 

```
"881d3281-2811-4c86-b7b6-4a8a621cf6f2"
``` </td></tr>
  <tr><td>会话 ID</td><td>每次调用 CLI 命令时都会生成随机 UUID</td><td>这可以帮助我们识别源自同一命令的所有事件。</td><td> 

```
"c47e3d55-bc20-406b-a02a-e0285dd63230"
``` </td></tr>
  <tr><td>事件 ID</td><td>会话 ID 加上一个计数器</td><td>这将为会话中的每个事件创建一个唯一的标识符。</td><td> 

```
"c47e3d55-bc20-406b-a02a-e0285dd63230:0"
``` </td></tr>
  <tr><td>Region</td><td>AWS 区域</td><td>这将帮助我们将数据一分为二，以解决特定区域的问题。</td><td> 

```
"us-east-1"
``` </td></tr>
  <tr><td>Timestamp</td><td>将数据发送到我们的遥测端点的时间（由客户端生成）</td><td>这将帮助我们生成时间序列图。</td><td> 

```
"2025-12-12T00:00:00.000Z"
``` </td></tr>
  <tr><td>事件状态</td><td>事件的 “结果”。可能的值为 “成功”、“失败”、“已中止”</td><td>这将帮助我们跟踪每个 CLI 命令的错误率，并在客户报告潜在的回归之前提醒我们注意这些错误。</td><td> 

```
"SUCCESS"
``` </td></tr>
  <tr><td>事件类型</td><td>生成数据的事件类型的标识符</td><td>这是一个枚举，用于标识所发生的事件类型，因为命令执行中可能有多个事件。</td><td> 

```
"SYNTH"
``` </td></tr>
  <tr><td>命令路径</td><td>在 CLI 中输入的命令和属性，所有自由文本都已被删掉</td><td>除了命令参数外，这些信息还有助于确定所发生事件的行为，这有助于我们确定爆炸半径和出现问题的原因。</td><td> 

```
["cdk", "deploy", "$STACK1"]
``` </td></tr>
  <tr><td>命令参数</td><td>在 CLI 中输入的可选参数，所有自由文本都经过了删改</td><td>除了命令路径外，这些信息还有助于确定所发生事件的行为，这有助于我们确定爆炸半径和出现问题的原因。</td><td> 

```
{
  all: true,
  concurrency: 4
}
``` </td></tr>
  <tr><td>配置</td><td>可能影响 CLI 命令的其他参数（即 cdk.context.json 或 `cdk.json` /中的上下文值`~/.cdk.json`），且所有自由文本都已被删掉</td><td>这将为我们提供可能影响 CLI 行为的所有可能参数的全面视图，从而帮助我们简化调试。</td><td> 

```
{
  context: {
    "@aws-cdk/core:explicitStackTags": true
  }
}
``` </td></tr>
  <tr><td>操作系统</td><td>正在使用的操作系统</td><td>这将帮助我们调试仅影响特定操作系统的问题。</td><td> 

```
{
  platform: "linux",
  release: "5.15.0-1019-aws",
}
``` </td></tr>
  <tr><td>语言</td><td>我们对您的应用程序使用的 CDK 实现语言的猜测。</td><td>这将帮助我们按语言细分合成时间慢或错误率较高等问题，以帮助可视化和解决这些问题。</td><td> 

```
"python"
``` </td></tr>
  <tr><td>CI/CD</td><td>是否正在从 CI/CD 环境中调用 CLI 命令</td><td>这将帮助我们确定特定于 CI/CD 环境的问题。</td><td> 

```
false
``` </td></tr>
  <tr><td>座席</td><td>我们对 AI 代理是否在执行命令的最佳猜测</td><td>这将帮助我们调试影响 AI 代理的问题。</td><td> 

```
true
``` </td></tr>
  <tr><td>节点版本</td><td>环境中使用的节点版本</td><td>这将帮助我们调试出现的任何特定于节点的问题。</td><td> 

```
"v22.0.0"
``` </td></tr>
  <tr><td>Duration</td><td>事件的长度（以毫秒为单位）</td><td>这可以帮助我们注意到特定事件需要多长时间的模式。</td><td> 

```
{ total: 300 }
``` </td></tr>
  <tr><td>计数器</td><td>从 CDK 应用程序和 CLI 执行中得出的各种计数器指标</td><td>我们将监控（但不限于）CFN 资源计数等统计数据对部署持续时间的影响。</td><td> 

```
{
  resourceCount: 25,
  errorCount: 0,
  warningCount: 2,
}
``` </td></tr>
  <tr><td>依赖项</td><td>相关的 AWS 依赖项及其版本</td><td>我们计划跟踪可能影响 CLI 结果的 AWS 依赖项，例如 jsii aws-cdk-lib、projen 等。我们只会收集对特定 AWS 拥有的库的依赖关系。</td><td> 

```
[{ "aws-cdk-lib": "2.232.0"}]
``` </td></tr>
  <tr><td>错误名称</td><td>错误的名称或代码（如果发生错误）。</td><td>我们只记录我们控制的错误名称和错误代码。我们用它来识别反复出现的错误类型。</td><td> 

```
"ToolkitError"
``` </td></tr>
  <tr><td colspan="4"> **以下指标需要明确选择加入，目前尚未收集：**</td></tr>
  <tr><td>错误消息</td><td>如果发生错误，则返回错误消息。已编辑自由格式文本。</td><td> **[需要选择加入]** 捕获错误消息将帮助我们调试各个用例中出了什么问题。</td><td> *目前未收集* </td></tr>
  <tr><td>错误堆栈跟踪</td><td>错误消息的堆栈跟踪（如果发生错误）。已编辑自由格式文本。</td><td> **[需要选择加入]** 堆栈跟踪将有助于个人调试，也是我们能够重现可能出现的问题所必需的。</td><td> *目前未收集* </td></tr>
  <tr><td>错误日志</td><td>CLI 命令失败的日志（如果发生错误）。已编辑自由格式文本。</td><td> **[需要选择加入]** 错误日志还将帮助我们调试和重现在 CLI 中看到的问题。</td><td> *目前未收集* </td></tr>
</tbody>
</table>


## 如何选择退出 CDK CLI 遥测
<a name="telemetry-opt-out"></a>

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

```
cdk cli-telemetry --status
```

### 使用上下文值选择退出
<a name="telemetry-context"></a>

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

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

1. cdk.json 中的上下文值

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

1. \~/.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
  }
}
```

### 使用环境变量选择退出
<a name="telemetry-environment-variable"></a>

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

```
CDK_DISABLE_CLI_TELEMETRY=true
```

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

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

### 使用 DNS 过滤选择退出
<a name="telemetry-dns"></a>

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

### 选择退出所有使用情况数据报告
<a name="telemetry-optout-all"></a>

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

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

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

## 将遥测数据发送到本地文件
<a name="telemetry-data-file"></a>

如果您想要继续选择加入 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'
```

## 页面历史记录
<a name="history"></a>


| 日期 | 说明 | 
| --- | --- | 
| 2026年3月2日 | 在收集的字段集中添加 “语言” 和 “代理”，以便对性能数字进行细分。 |