AWS Blocks CLI telemetry
The AWS 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. AWS Blocks CLI telemetry is enabled by default. You can opt out at any time using any of the methods described on this page.
AWS Blocks CLI telemetry overview
The AWS 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 AWS 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 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 AWS Blocks CLI collects. It includes the metric name, description, reason for collection, and example values.
| Metric | Description | Reason | Example |
|---|---|---|---|
|
AWS Blocks Version |
CLI version (x.y.z) |
Collecting this helps us bisect our data by version, which can help us identify problematic versions. |
|
|
Installation ID |
Random UUID stored on local machines executing CLI commands, at |
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. |
|
|
Project ID |
Random UUID generated per project, stored in |
This helps us understand usage patterns across different projects without identifying the project itself. |
|
|
Event ID |
Random UUID generated for each telemetry event |
This creates a unique identifier for each event, helping us deduplicate data. |
|
|
Timestamp |
The time (generated by the client) the data is sent to our telemetry endpoint |
This helps us generate time series graphs and identify when issues occur. |
|
|
Command Name |
The CLI command that was run |
Along with command state, this information helps us understand feature usage and prioritize improvements. |
|
|
Command State |
The result of the command. Possible values are |
This helps us track error rates on each CLI command and alert us to potential regressions before they are reported by customers. |
|
|
Duration |
The length of the command execution in milliseconds |
This helps us notice performance patterns and identify bottlenecks in specific commands. |
|
|
Error Code |
A categorized error code, if an error occurs |
We use this to identify recurring error types and prioritize fixes. |
|
|
Error Phase |
Which phase of execution the error occurred in |
This helps us narrow down where failures happen in the command lifecycle. |
|
|
Operating System |
The OS platform being used |
This helps us debug issues that only affect specific operating systems. |
|
|
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. |
|
|
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. |
|
|
Package Manager |
The package manager user agent string |
This helps us understand the developer toolchain and debug package-manager-specific issues. |
|
|
Agent |
Our best guess at whether an AI agent is executing the command, and which one |
This helps us debug issues that affect AI agent workflows. |
|
|
AWS CDK Version |
The version of the AWS CDK used under the hood |
This helps us ensure CDK compatibility and bisect CDK-specific issues. |
|
|
Framework |
The frontend framework in use |
This helps us prioritize framework-specific improvements. |
|
|
Template |
The project template name and version used with |
This helps us understand which starter templates are popular and maintain them accordingly. |
|
|
Blocks |
The names and versions of AWS Blocks-provided Blocks used in the project |
This helps us understand Block adoption and prioritize development of popular blocks. |
|
|
Block Count |
The total number of Blocks in the project |
This helps us understand project complexity and plan for scale. |
|
|
Custom Blocks |
The number of custom (user-authored) Blocks |
This helps us track custom Block adoption and improve the authoring experience. |
|
AWS CDK CLI telemetry
Some AWS 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 AWS Blocks CLI telemetry using any of the methods described on this page, telemetry for AWS Blocks-spawned CDK CLI invocations is also disabled automatically. You do not need to separately configure the CDK CLI opt-out.
Data NOT collected
AWS 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 AWS Blocks CLI telemetry
You can disable telemetry using any of the following methods. If any method indicates telemetry is disabled, no data is collected.
Opt out using the CLI
You can use the AWS 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, enter the following command:
npx blocks-telemetry --enable
Opt out using an environment variable
To disable telemetry using an environment variable, enter the following command to set AWS_BLOCKS_DISABLE_TELEMETRY to 1 as shown in the following example:
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 AWS 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 AWS 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'
Each line in the file is a complete JSON object representing one telemetry event.
