

# Telemetry and identification

The AWS CDK Blocks CLI collects anonymized usage data to help improve the developer experience. This topic explains what data is collected, how it’s used, and how to opt out of telemetry collection.

You can review all collected data, understand privacy protections, and choose the opt-out method that works best for your workflow. CDK Blocks CLI telemetry is enabled by default. You can opt out at any time using any of the methods described on this page.

Deployed apps also identify CDK Blocks in two other places: the AWS CloudFormation template metadata and the user agent of requests to AWS services. These are separate from CLI telemetry. For more information, see [CloudFormation template metadata](#template-metadata) and [Service request user agent](#user-agent).

## CDK Blocks CLI telemetry overview
<a name="what-is-cli-telemetry"></a>

The CDK Blocks CLI collects anonymized usage data each time you run a command. This data cannot identify you or your organization. No personal information, source code, resource names, or AWS account identifiers are ever collected.

The data helps the CDK Blocks team understand which commands are used most frequently and identify commands that fail often. It also helps prioritize fixes, track adoption of new features and CDK Blocks, optimize performance for common workflows, and understand which environments and tools developers use.

You can review an exhaustive list of the collected data in the following table. This list may change over time as new metrics are added. Any new data collection will follow the same privacy principles.

### Data collected
<a name="_data_collected"></a>

The following table describes all telemetry data that the CDK Blocks CLI collects. It includes the metric name, description, reason for collection, and example values.


| Metric | Description | Reason | Example | 
| --- | --- | --- | --- | 
| Telemetry Version | Version of the telemetry event format | This lets us read events correctly when the format changes. |  `"1.0.0"`  | 
| CDK Blocks Version | Version of the `@aws-cdk-blocks/core` package that ran the command (x.y.z). For `npm create @aws-cdk-blocks/blocks-app`, the version of `@aws-cdk-blocks/create-blocks-app`. | Collecting this helps us bisect our data by version, which can help us identify problematic versions. |  `"0.8.0"`  | 
| Installation ID | Random UUID stored on local machines executing CLI commands, at `~/.blocks/telemetry/installation-id`  | This helps us estimate the distinct number of users who are affected by an error. Each unique machine has its own Installation ID. The ID is generated randomly using UUID V4. |  `"87c785a7-983c-41de-a106-614d5f1d7ac0"`  | 
| Project ID | Random UUID generated per project, stored as `telemetry.projectId` in `.blocks/config.json`. `npm create @aws-cdk-blocks/blocks-app` sends a new random UUID for each run and does not store it | This helps us understand usage patterns across different projects without identifying the project itself. |  `"a5e82e34-c12f-47ee-a507-8244d8f51893"`  | 
| Event ID | Random UUID generated for each telemetry event | This creates a unique identifier for each event, helping us deduplicate data. |  `"f76343c7-f665-4b83-ad79-01071935f935"`  | 
| Timestamp | The time (generated by the client) the event is created | This helps us generate time series graphs and identify when issues occur. |  `"2026-06-10T08:08:04.877Z"`  | 
| Command Name | The CLI command that was run. Possible values are `create-blocks-app`, `dev`, `sandbox`, `sandbox:destroy`, `deploy`, `destroy`, `cleanup`, `console`, `vendorize`  | Along with command state, this information helps us understand feature usage and prioritize improvements. |  `"deploy"`, `"dev"`, `"sandbox"`  | 
| Command State | The result of the command. Possible values are `SUCCESS`, `FAIL`, `ABORTED`  | This helps us track error rates on each CLI command and alert us to potential regressions before they are reported by customers. |  `"SUCCESS"`  | 
| Duration | The length of the command execution in milliseconds | This helps us notice performance patterns and identify bottlenecks in specific commands. |  `4500`  | 
| Error Code | A categorized error code, if an error occurs | We use this to identify recurring error types and prioritize fixes. |  `"CDK_DEPLOY_FAILED"`  | 
| Error Phase | Which phase of execution the error occurred in | This helps us narrow down where failures happen in the command lifecycle. |  `"deploy"`  | 
| Operating System | The OS platform being used | This helps us debug issues that only affect specific operating systems. |  `"darwin"`, `"linux"`, `"win32"`  | 
| Node Version | The Node.js runtime version used in the environment | This helps us debug any Node.js-specific issues that arise and ensure compatibility. |  `"22.12.0"`  | 
| CI/CD | Whether or not the CLI command is being invoked from a CI/CD environment | This helps us identify issues specific to CI/CD environments. |  `false`  | 
| Package Manager | The package manager user agent string | This helps us understand the developer toolchain and debug package-manager-specific issues. |  `"npm/10.8.2 node/v22.12.0"`  | 
| Agent | Our best guess at whether a coding agent is executing the command, and which one | This helps us debug issues that affect coding agent workflows. |  `"amazon-q"`  | 
| Framework | The frontend framework in use, for `deploy` and `sandbox`. Possible values are `nextjs`, `nitro`, `nuxt`, `astro`, `sveltekit`, `spa`, `static`. Projects without a frontend report none. | This helps us prioritize framework-specific improvements. |  `"nextjs"`, `"spa"`, `"static"`  | 
| Template | The project template name and version used with `npm create @aws-cdk-blocks/blocks-app`  | This helps us understand which starter templates are popular and maintain them accordingly. |  `{"name": "nextjs", "version": "0.1.0"}`  | 
| Blocks | The names and versions of the CDK Blocks that AWS provides and that the project uses. Names of custom CDK Blocks are never sent. | This helps us understand CDK Block adoption and prioritize development of popular CDK Blocks. |  `[{"name": "KVStore", "version": "0.4.0"}, {"name": "Auth", "version": "0.1.0"}]`  | 
| Block Count | The total number of CDK Blocks in the project | This helps us understand project complexity and plan for scale. |  `3`  | 
| Custom Blocks | The number of custom (user-authored) CDK Blocks | This helps us track custom CDK Block adoption and improve the authoring experience. |  `1`  | 

### AWS CDK CLI telemetry
<a name="_aws_cdk_cli_telemetry"></a>

Some CDK Blocks commands (such as `sandbox`, `deploy`, and `destroy`) use the AWS CDK CLI under the hood. When this happens, the AWS CDK CLI also collects its own telemetry data on behalf of AWS CDK.

For information about AWS CDK CLI telemetry collection, see [Configure AWS CDK CLI telemetry](https://docs.aws.amazon.com/cdk/v2/guide/cli-telemetry.html) in the *AWS CDK Developer Guide*.

**Note**  
When you disable CDK Blocks CLI telemetry using any of the methods described on this page, telemetry for CDK Blocks-spawned CDK CLI invocations is also disabled automatically. You do not need to separately configure the CDK CLI opt-out.

### Data NOT collected
<a name="_data_not_collected"></a>

CDK Blocks does **not** collect:
+ Your AWS account ID or credentials
+ Source code, file contents, or resource names
+ File names or directory paths
+ IP addresses (not logged server-side)
+ Environment variable values
+ Any personally identifiable information (PII)

## How to opt out of CDK Blocks CLI telemetry
<a name="opt-out"></a>

You can disable telemetry using any of the following methods. If any method indicates telemetry is disabled, no data is collected.

An enable setting never overrides a disable from another method. For example, if you disabled telemetry globally, `npx blocks-telemetry --enable` in one project leaves telemetry off. To turn it back on, run `npx blocks-telemetry --enable --global`.

### Opt out using the CLI
<a name="opt-out-cli"></a>

You can use the CDK Blocks CLI to check and modify your telemetry settings.

To check whether telemetry is currently enabled or disabled, enter the following command:

```bash
npx blocks-telemetry --status
```

To disable telemetry for the current project, enter the following command:

```bash
npx blocks-telemetry --disable
```

To disable telemetry globally, enter the following command:

```bash
npx blocks-telemetry --disable --global
```

To re-enable telemetry for the current project, enter the following command. Add `--global` to re-enable it globally.

```bash
npx blocks-telemetry --enable
```

### Opt out using an environment variable
<a name="opt-out-env"></a>

To disable telemetry using an environment variable, set `AWS_BLOCKS_DISABLE_TELEMETRY` to `1`, `true`, or `yes` (not case-sensitive). The following example sets it to `1`:

```bash
export AWS_BLOCKS_DISABLE_TELEMETRY=1
```

**Tip**  
Add this environment variable to your shell startup file, such as `.bashrc` or `.zshrc`, to persist the setting across sessions.

This method works well for CI/CD pipelines. Use it to disable telemetry without modifying project files.

### Opt out using a configuration file
<a name="opt-out-config"></a>

To disable telemetry for a specific project, set `telemetry.enabled` to `false` in the project’s `.blocks/config.json` file:

```json
{
  "telemetry": {
    "enabled": false
  }
}
```

This disables telemetry for the current project only.

To disable telemetry globally, set the same value in `~/.blocks/config.json`:

```json
{
  "telemetry": {
    "enabled": false
  }
}
```

This disables telemetry for all projects on this machine.

## Send telemetry data to a local file
<a name="telemetry-file"></a>

If you stay opted in to CDK Blocks CLI telemetry, you can send your telemetry data to a local file. You can then review the file to audit the telemetry data that we are collecting.

Use the `--telemetry-file` option on any CDK Blocks CLI command to send telemetry data to a local file:

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

As an example, this deploy command sends telemetry data to a local file:

```bash
npm run deploy -- --telemetry-file='/tmp/blocks-telemetry.json'
```

The file holds one JSON array, with one object for each telemetry event the command sends. Use a path that does not exist yet. If the file already exists, CDK Blocks does not write to it.

The option has no effect when telemetry is disabled. To capture events without sending them, leave telemetry on and point the endpoint at an unused local port:

```bash
BLOCKS_TELEMETRY_ENDPOINT=http://127.0.0.1:1 npm run deploy -- --telemetry-file='/tmp/blocks-telemetry.json'
```

## CloudFormation template metadata
<a name="template-metadata"></a>

When you synthesize or deploy an app, CDK Blocks adds an entry to the metadata of the app’s AWS CloudFormation template. The entry identifies the CDK Blocks version and the CDK Blocks the app uses. It looks like this:

```json
{
  "Metadata": {
    "AWSToolsMetrics": {
      "AWSBlocks": "1;core=0.8.0;mode=production;bb=KVStore,LambdaCompute;custom=0"
    }
  }
}
```

The value has these fields:


| Field | Description | 
| --- | --- | 
|  `1`  | Version of the value format | 
|  `core`  | Version of `@aws-cdk-blocks/core`  | 
|  `mode`  |  `sandbox` for a sandbox deployment, `production` otherwise | 
|  `bb`  | Names of the CDK Blocks in the app that ship with CDK Blocks, sorted and comma-separated. `LambdaCompute` is the default compute that every app gets. | 
|  `custom`  | Number of custom CDK Block instances. Their names are never written. | 

CDK Blocks writes the entry only to the top-level stack, not to nested stacks. It also adds a `blocks:deployment-type` tag with the value `sandbox` or `production` to the stack.

The CLI telemetry opt-out does not affect the template metadata. To turn off the template metadata, use any of the following:
+ Set the environment variable `AWS_BLOCKS_DISABLE_TEMPLATE_METADATA` to `1`, `true`, or `yes` before you synthesize or deploy.
+ Set the CDK context value `blocks:template-metadata` to `false`, for example in the `context` section of `cdk.json`.
+ Turn off CDK version reporting, for example with `"versionReporting": false` in `cdk.json` or the `--no-version-reporting` option of the CDK CLI.

The `blocks:deployment-type` tag is always added.

## Service request user agent
<a name="user-agent"></a>

Deployed CDK Blocks that call AWS services through the AWS SDK identify themselves in the user agent of those requests. The user agent includes `aws-blocks/<core version>` and a `bb/<Block>/<version>` entry for the CDK Block making the request. It also includes one entry for each CDK Block that the requesting CDK Block is nested in, counting only CDK Blocks that ship with CDK Blocks. For example, a `KVStore` request carries `aws-blocks/0.8.0 bb/KVStore/0.4.0`, and a request from the session `KVStore` inside an `Auth` Block carries `aws-blocks/0.8.0 bb/Auth/0.1.0 bb/KVStore/0.4.0`. Names of custom CDK Blocks are never included.

The native clients for Kotlin, Swift, and Dart send an `x-blocks-user-agent` header in the form `aws-blocks-<language>/<version>` with each API call. Dart apps running in a web browser do not send it. The backend checks the header and adds it to the AWS SDK user agent as `client/<language>/<version>`. The backend drops a malformed value.

There is no setting to turn off the user agent entries.