這是 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 遙測僅在 AWS CDK CLI 2.1100.0 版及更新版本中收集。

 AWS 雲端開發套件 (AWS CDK) 會收集 CLI 用量的遙測資料，以提供彙總用量模式和錯誤頻率，協助我們識別影響 CDK CLI 使用者群的廣泛問題。

根據預設，客戶可以選擇加入 CLI 遙測資料收集。您可以使用[下列方法](#telemetry-opt-out)選擇退出 CDK CLI 遙測。

 AWS CDK 會收集嚴格資料最小化的遙測資料，防止識別或歸因於特定使用者、帳戶或組織。以下提供依預設收集的指標完整清單，以及動機。此清單可能會隨著時間而變更；任何變更一律會伴隨著動機，並遵循匿名性和資料最小化的原則。

我們目前未收集完整的錯誤訊息、堆疊追蹤和日誌。如果此資料曾經在未來的 CDK CLI 版本中收集，則一律會處於明確選擇加入狀態。如需這些指標的詳細資訊，請參閱 資料表。

正在收集的資料如下：


<table>
<thead>
  <tr><th>指標</th><th>Description</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>隨機 UUID 存放在執行 CLI 命令的本機電腦上</td><td>這有助於我們估計受到錯誤影響的不同使用者數量。每個唯一機器都有自己的安裝 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>區域</td><td>AWS 區域</td><td>這將有助於我們劃分資料以解決區域特定的問題。</td><td> 

```
"us-east-1"
``` </td></tr>
  <tr><td>時間戳記</td><td>資料傳送到遙測端點的時間 （由用戶端產生）</td><td>這將有助於我們產生時間序列圖表。</td><td> 

```
"2025-12-12T00:00:00.000Z"
``` </td></tr>
  <tr><td>事件狀態</td><td>事件的「結果」。可能的值為 'SUCCESS'、'FAILURE'、'ABORTED'</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>Configuration</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>Language</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>持續時間</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 相依性，例如 aws-cdk-lib、jsii、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. 使用 CDK CLI 命令搭配 `--context`選項指定的內容值

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`檔案中設定 。這會停用應用程式的遙測。

 **使用全域組態檔案選擇退出** 

`cli-telemetry: false` 在 `~/.cdk.json` 檔案中設定 ，以停用相同電腦上所有 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 命令上使用下列選項，將遙測資料傳送至本機檔案：

**注意**  
如果您使用的 AWS CDK CLI 版本低於 2.1100.0，您必須指定 `--unstable=telemetry`與 `--telemetry-file`。

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

例如，此`deploy`命令會將遙測資料傳送至本機檔案：

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

## 頁面歷史記錄
<a name="history"></a>


| Date | Description | 
| --- | --- | 
| 2026 年 3 月 2 日 | 將「語言」和「客服人員」新增至收集的欄位集，以分割效能數字。 |