View a markdown version of this page

Telemetry and identification - AWS CDK Blocks

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 and Service request user agent.

CDK Blocks CLI telemetry overview

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

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

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 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

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

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

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:

npx blocks-telemetry --status

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

npx blocks-telemetry --disable

To disable telemetry globally, enter the following command:

npx blocks-telemetry --disable --global

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

npx blocks-telemetry --enable

Opt out using an environment variable

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:

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

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

{ "telemetry": { "enabled": false } }

This disables telemetry for the current project only.

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

{ "telemetry": { "enabled": false } }

This disables telemetry for all projects on this machine.

Send telemetry data to a local file

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:

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

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

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:

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

CloudFormation template metadata

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:

{ "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

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.