O que são relatórios de dados de uso da biblioteca do CDK?Quais dados de uso são coletados?Como o CDK coleta dados de uso da aplicação Como cancelar ou aceitar receber relatórios de dados de uso Exemplos

Configuração de relatórios de dados de uso da Biblioteca do AWS CDK

O que são relatórios de dados de uso da biblioteca do CDK?

As aplicações do kit de desenvolvimento em nuvem da AWS (CDK da AWS) são configurados para coletar e gerar relatórios sobre dados de uso para obter informações sobre como o CDK da AWS está sendo usado. A equipe do CDK usa esses dados para fazer o seguinte:

Comunicar-se com os clientes: identifique pilhas usando um constructo com problemas conhecidos de segurança ou confiabilidade e envie comunicações sobre tópicos que afetam o cliente.
Informar o desenvolvimento do CDK: obtenha informações sobre o uso do CDK para melhor informar o desenvolvimento do CDK.
Investigar problemas do CDK: quando os bugs são relatados, os dados de uso fornecem informações valiosas para a equipe do CDK na solução de problemas.

Quais dados de uso são coletados?

Há duas categorias de dados de uso de aplicações coletados pelo CDK:

Dados gerais de uso
Dados de uso adicionais

Coleta de dados de uso geral

O CDK coleta os tipos de dados de uso geral a seguir de suas aplicações do CDK:

Versões de bibliotecas do CDK usadas.
Nomes de constructos usados nos módulos NPM a seguir:
- Módulos principais do AWS CDK
- Módulos da Biblioteca de Constructos da AWS
- Módulo de constructos das soluções da AWS
- Módulo do kit de implantação do parque de renderização da AWS

nota

Antes da versão 1.93.0, o CDK da AWS relatava os nomes e versões dos módulos carregados durante a síntese, em vez dos constructos usados na pilha.

Coleta de dados de uso adicional

A partir da versão 2.178.0 do CDK, a coleta de dados de uso foi expandida para incluir os dados de uso adicionais a seguir:

Chaves de propriedade definidas pelo CDK: quando você usar uma propriedade integrada de um constructo L2, a chave da propriedade será coletada. Isso inclui chaves de propriedade integradas aninhadas em objetos de dicionário.
Valores booleanos e enumerados de propriedades de chaves de propriedade definidas pelo CDK: para chaves de propriedade definidas pelo CDK, valores de propriedade somente dos tipos booleano e enum serão coletados. Todos os outros tipos, como valores de string ou referências de constructos, serão revistos.
Nome do método, chaves e valores de propriedade dos tipos booleano e enum: quando você usa um método de constructo L2, coletamos o nome do método, as chaves de propriedade e os valores de propriedade dos tipos booleano e enum.

Para chaves de propriedade e valores que você cria de forma exclusiva, o objeto inteiro será revisto. Por exemplo, se você usar InlineApiDefinition para definir uma especificação OpenAPI e passá-la para um constructo RestApi, o objeto InlineApiDefinition inteiro será revisto.

Para obter mais informações sobre a coleta adicional de dados de uso, incluindo seus benefícios e possíveis preocupações, consulte a discussão CDK coletando metadados adicionais (sob o sinalizador de atributos) #33198 no repositório do aws-cdk.

Como o CDK coleta dados de uso da aplicação

Na síntese, o CDK coleta dados de uso da sua aplicação e os armazena no recurso AWS::CDK::Metadata. Veja a seguir um exemplo disso em um modelo sintetizado do AWS CloudFormation:


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

A propriedade Analytics é uma lista compactada com gzip, codificada em base64 e codificada por prefixo dos constructos na pilha.

Como cancelar ou aceitar receber relatórios de dados de uso

Suas opções de cancelar ou aceitar receber relatórios gerais de dados de uso e relatórios adicionais de dados de uso dependem da versão do CDK que você usou para criar sua aplicação originalmente.

Por padrão, as aplicações do CDK são configuradas para ativar automaticamente os relatórios de dados de uso da forma a seguir:

Todas as aplicações do CDK: aceitam receber relatórios de dados de uso geral.
Aplicações do CDK criadas com uma versão anterior à v2.178.0: não aceitam receber automaticamente relatórios adicionais de dados de uso.
Aplicações do CDK criadas com a versão v2.178.0 ou mais recente: aceitam receber relatórios adicionais de dados de uso.

Atenção

Se você optar por não aceitar, o CDK não conseguirá identificar se você foi afetado por problemas de segurança e não enviará notificações sobre eles.

Cancelamento do uso de todos os relatórios de dados de uso

Para cancelar todos os relatórios de dados de uso, é possível usar a interface de linha de comandos (CLI) do kit de desenvolvimento em nuvem da AWS (CDK da AWS) ou configurar o arquivo cdk.json do seu projeto.

Para cancelar o recebimento de relatórios de dados de uso usando o a CLI do CDK

Use a opção --no-version-reporting com qualquer comando da CLI do CDK para cancelar com um comando único. Este é um exemplo de recusa durante a síntese do modelo:
```
$ cdk synth --no-version-reporting
```
Como o CDK sintetiza modelos automaticamente quando você executa cdk deploy, você também deve usar --no-version-reporting com o comando cdk deploy.

Para cancelar o recebimento de relatórios de dados de uso configurando o arquivo cdk.json

Defina versionReporting como false em ./cdk.json ou ~/.cdk.json. Isso exclui você por padrão. Veja um exemplo a seguir:
```
{
  "app": "...",
  "versionReporting": false
}
```
Após a configuração, você pode substituir esse comportamento e optar por participar especificando --version-reporting em um comando individual.

Cancelamento somente dos relatórios adicionais de dados de uso

Se a sua aplicação do CDK foi criada com uma versão do CDK anterior à 2.178.0, você automaticamente cancelou os relatórios adicionais de dados de uso, mesmo que tenha optado por aceitar os relatórios de dados de uso geral. Você não precisa fazer nada para cancelar os relatórios adicionais de dados de uso.

Se a sua aplicação do CDK foi criada com o CDK versão 2.178.0 ou mais recente, é necessário cancelar todos os relatórios de dados de uso. Você não pode cancelar somente os relatórios adicionais de dados de uso

Aceitação dos relatórios de dados de uso

Se a sua aplicação do CDK foi criada com o CDK versão 2.178.0 ou mais recente, é possível aceitar todos os relatórios de dados de uso configurando versionReporting como true. Esse é o comportamento padrão das aplicações do CDK.

Se a sua aplicação do CDK foi criada com uma versão CDK anterior à 2.178.0, é possível aceitar os relatórios de dados de uso geral configurando versionReporting como true. Para aceitar os relatórios adicionais de dados de uso, será necessário ativar um sinalizador de atributo.

nota

Essas etapas são para aplicações do CDK originalmente criadas com uma versão anterior à 2.178.0

Verifique se agora você está usando o CDK versão 2.178.0 ou mais recente.
No seu arquivo de configuração do CDK, especifique @aws-cdk/core:enableAdditionalMetadataCollection comotrue. Veja um exemplo a seguir:
```
{
  "context": {
    "@aws-cdk/core:enableAdditionalMetadataCollection": "true"
  }
}
```

Você também pode usar o valor ENABLE_ADDITIONAL_METADATA_COLLECTION com a classe FeatureFlags. Veja um exemplo a seguir:


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');

Exemplos

Dados de uso gerais e adicionais coletados de uma aplicação do CDK

Veja a seguir um exemplo de uma aplicação do 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();

Na síntese, os dados de uso são coletados, compactados e armazenados no recurso AWS::CDK::Metadata

Veja a seguir um exemplo de dados de uso geral coletados com uma versão do CDK anterior à 2.178.0:


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

Veja a seguir um exemplo de dados de uso coletados, incluindo os dados de uso adicionais introduzidos na versão 2.178.0 do CDK:


{
    "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": "*",
                }
            }
        }
    ]
}

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Telemetria do AWS CDK

Configuração da telemetria da CLI do CDK