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

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

# 配置 AWS CDK 库使用情况数据报告
<a name="usage-data"></a>

## 什么是 CDK 库使用情况数据报告？
<a name="usage-data-intro"></a>

 AWS 云开发工具包 (AWS CDK) 应用程序配置为收集和报告使用情况数据，以深入了解 AWS CDK 的使用情况。CDK 团队使用此数据执行下面的操作：
+  **与客户沟通** – 使用存在已知安全或可靠性问题的构造来识别堆栈，并就影响客户的主题发送沟通信息。
+  **促进 CDK 开发** – 深入了解 CDK 使用情况，以便更好地促进 CDK 开发。
+  **调查 CDK 问题** – 当报告错误时，使用情况数据可在故障排除时为 CDK 团队提供宝贵的见解。

## 收集哪些使用情况数据？
<a name="usage-data-categories"></a>

CDK 会收集两类应用程序使用情况数据：
+ 常规使用情况数据
+ 其他使用情况数据

### 常规使用情况数据收集
<a name="usage-data-categories-general"></a>

CDK 会从您的 CDK 应用程序中收集以下类型的常规使用情况数据：
+ 使用的 CDK 库版本。
+ 从以下 `NPM`模块中使用的构造名称：
  +  AWS CDK 核心模块
  +  AWS 构造库模块
  +  AWS 解决方案构造模块
  +  AWS 渲染农场部署工具包模块

**注意**  
在 1.93.0 版本之前，AWS CDK 报告的是合成过程中加载的模块的名称和版本，而不是堆栈中使用的构造。

### 其他使用情况数据收集
<a name="usage-data-categories-additional"></a>

从 CDK 版本 2.178.0 开始，使用情况数据收集范围扩大到包括以下使用情况数据：
+  **CDK 定义的属性键** – 当您使用 L2 构造的内置属性时，系统会收集属性键。这包括嵌套在字典对象中的内置属性键。
+  **来自 CDK 定义的属性键的布尔值和枚举值** – 对于 CDK 定义的属性键，仅收集布尔类型和枚举类型的属性值。所有其他类型（例如，字符串值或构造引用）都将被加密。
+  **布尔类型和枚举类型的方法名称、键和属性值** – 当您使用 L2 构造方法时，我们将收集布尔类型和枚举类型的方法名称、属性键和属性值。

对于您创建的唯一属性键和值，整个对象将被加密。例如，如果您使用 ` [InlineApiDefinition](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.InlineApiDefinition.html) ` 定义 OpenAPI 规范并将其传递给 ` [RestApi](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.RestApi.html) ` 构造，则整个 `InlineApiDefinition` 对象将被加密。

有关其他使用情况数据收集的更多信息，包括其好处和潜在问题，请参阅 *aws-cdk 存储库*中的 [CDK Collecting Additional Metadata (under feature flag) \$133198](https://github.com/aws/aws-cdk/discussions/33198) 讨论。

## CDK 如何收集应用程序使用情况数据
<a name="usage-data-how"></a>

合成时，CDK 会从您的应用程序收集使用情况数据，并将其存储在 ` AWS::CDK::Metadata` 资源中。下面是合成的 AWS CloudFormation 中此资源的示例：

```
CDKMetadata:
  Type: "AWS::CDK::Metadata"
  Properties:
    Analytics: "v2:deflate64:H4sIAND9SGAAAzXKSw5AMBAA0L1b2PdzBYnEAdio3RglglY60zQi7u6TWL/XKmNUlxeQSOKwaPTBqrNhwEWU3hGHiCzK0dWWfAxoL/Fd8mvk+QkS/0X6BdjnCdgmOOQKWz+AqqLDt2Y3YMnLYWwAAAA="
```

`Analytics` 属性是堆栈中构造的 gzip、base64 编码、前缀编码列表。

## 如何选择退出或选择加入使用情况数据报告
<a name="usage-data-configure"></a>

您可以选择退出或加入常规使用情况数据报告以及其他使用情况数据报告，具体取决于您最初创建应用程序时使用的 CDK 版本。

默认情况下，CDK 应用程序配置为自动选择加入使用情况数据报告，具体如下：
+  **所有 CDK 应用程序** – 选择加入常规使用情况数据报告。
+  **使用低于 v2.178.0 的版本创建的 CDK 应用程序** – 不自动选择加入其他使用情况数据报告。
+  **使用 v2.178.0 或更高版本创建的 CDK 应用程序** – 选择加入其他使用情况数据报告。

**警告**  
如果您选择退出，CDK 将无法识别您是否受到安全问题的影响，也不会向您发送有关这些问题的通知。

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

要选择退出所有使用情况数据报告，您可以使用 AWS 云开发工具包 (AWS CDK) 命令行界面 (CLI) 或配置项目的 `cdk.json` 文件。

 **使用 CDK CLI 选择退出所有使用情况数据报告**   
+ 将 `--no-version-reporting` 选项与任何 CDK CLI 命令搭配即可选择退出单个命令。以下是模板合成期间选择退出的示例：

  ```
  $ cdk synth --no-version-reporting
  ```

  由于运行 `cdk deploy` 时，CDK 会自动合成模板，因此您还应将 `--no-version-reporting` 与 `cdk deploy` 命令搭配使用。

 **通过配置 cdk.json 文件来选择退出所有使用情况数据报告**   

1. 在 `./cdk.json` 或 `~/.cdk.json` 中将 `versionReporting` 设置为 `false` 默认情况下，这会让您选择退出。以下是示例：

   ```
   {
     "app": "...",
     "versionReporting": false
   }
   ```

1. 配置完成后，您可以覆盖这一行为，通过在单个命令中指定 `--version-reporting` 来选择加入。

### 仅选择退出其他使用情况数据报告
<a name="usage-data-configure-optout-additiona"></a>

如果 CDK 应用程序是使用低于 2.178.0 的 CDK 版本创建的，那么即使您选择加入常规使用情况数据报告，您也会自动选择退出其他使用情况数据报告。您无需执行任何操作即可选择退出其他使用情况数据报告。

如果 CDK 应用程序是使用 CDK 版本 2.178.0 或更高版本创建的，则必须选择退出所有使用情况数据报告。您不能只选择退出其他使用情况数据报告。

### 选择加入使用情况数据报告
<a name="usage-data-configure-optin"></a>

如果 CDK 应用程序是使用 CDK 版本 2.178.0 或更高版本创建的，则可以通过将 `versionReporting` 设置为 `true` 来选择加入所有使用情况数据报告。这是 CDK 应用程序的默认行为。

如果 CDK 应用程序是使用低于 2.178.0 的 CDK 版本创建的，则可以通过将 `versionReporting` 设置为 `true` 来选择加入所有使用情况数据报告。要选择加入其他使用情况数据报告，必须启用功能标志。

**注意**  
这些步骤适用于最初使用低于 2.178.0 的版本创建的 CDK 应用程序

1. 验证您现在使用的是否是 CDK 2.178.0 或更高版本。

1. 在您的 CDK 配置文件中，将 `@aws-cdk/core:enableAdditionalMetadataCollection` 指定为 `true`。以下是示例：

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

1. 您也可以在 ` [FeatureFlags](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.FeatureFlags.html) ` 类中使用 `ENABLE_ADDITIONAL_METADATA_COLLECTION` 值。以下是示例：

   ```
   import * as cdk from 'aws-cdk-lib';
   import { FeatureFlags } from 'aws-cdk-lib';
   import * as cx_api from 'aws-cdk-lib/cx-api';
   import { Construct } from 'constructs';
   
   export class MyStack extends cdk.Stack {
     constructor(scope: Construct, id: string, props?: cdk.StackProps) {
       super(scope, id, props);
   
       // Set the feature flag ENABLE_ADDITIONAL_METADATA_COLLECTION to true
       FeatureFlags.of(this).add(cx_api.ENABLE_ADDITIONAL_METADATA_COLLECTION, true);
   
       // Your stack resources go here
       new cdk.aws_s3.Bucket(this, 'MyBucket');
     }
   }
   
   const app = new cdk.App();
   new MyStack(app, 'MyStack');
   ```

## 示例
<a name="usage-data-examples"></a>

### 从 CDK 应用程序中收集的常规和其他使用情况数据
<a name="usage-data-examples-example1"></a>

以下是 CDK 应用程序文件的示例：

```
import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as s3 from 'aws-cdk-lib/aws-s3';

class MyStack extends cdk.Stack {
  constructor(scope, id, props) {
    super(scope, id, props);

    // Create an S3 bucket (L2 construct)
    const myBucket = new s3.Bucket(this, 'MyBucket', {
      bucketName: 'my-cdk-example-bucket', // String type
      versioned: true,                    // Boolean type
      removalPolicy: cdk.RemovalPolicy.DESTROY, // ENUM type
      lifecycleRules: [{                  // Array of object type
        expirationDate: new Date('2019-10-01'),
        objectSizeLessThan: 600,
        objectSizeGreaterThan: 500,
      }],
    });

    // Use a method of the L2 construct to define additional properties
    myBucket.addLifecycleRule({
      id: 'ExpireOldObjects',
      enabled: true, // Boolean
      expiration: cdk.Duration.days(90), // Expire objects after 90 days
    });
  }
}

// Define the CDK app and stack
const app = new cdk.App();
new MyStack(app, 'MyStack');
app.synth();
```

合成时，将收集、压缩使用情况数据并将其存储在 ` AWS::CDK::Metadata` 资源中。

下面是使用低于 2.178.0 的 CDK 版本收集的常规使用情况数据示例：

```
{
    "fqn": "aws-cdk-lib.aws-s3.Bucket",
    "version": "v2.170.0"
}
```

下面是收集的使用情况数据示例，包括 CDK 版本 2.178.0 中引入的其他使用情况数据：

```
{
    "fqn": "aws-cdk-lib.aws_s3.Bucket",
    "version": "2.170.0",
    "metadata": [
        {
            "type": "aws:cdk:analytics:construct",
            "data": {
                "bucketName": "*",
                "versioned": true,
                "removalPolicy": "cdk.RemovalPolicy.DESTROY",
                "lifecycleRules": [
                    {
                        "expirationDate": "*",
                        "objectSizeLessThan": "*",
                        "objectSizeGreaterThan": "*"
                    }
                ]
            }
        },
        {
            "type": "aws:cdk:analytics:method",
            "data": {
                "name": "addLifecycleRule",
                "prop": {
                    "id": "*",
                    "enabled": true,
                    "expiration": "*",
                }
            }
        }
    ]
}
```