Configure AWS CDK CLI telemetry - AWS Cloud Development Kit (AWS CDK) v2
What is CDK CLI telemetry?How to opt out of CDK CLI telemetrySend telemetry data to a local file

This is the AWS CDK v2 Developer Guide. The older CDK v1 entered maintenance on June 1, 2022 and ended support on June 1, 2023.

Configure AWS CDK CLI telemetry

What is CDK CLI telemetry?

Important

AWS CDK CLI telemetry is only collected in AWS CDK CLI versions 2.1100.0 and up.

The AWS Cloud Development Kit (AWS CDK) collects telemetry data on CLI usage to provide aggregate usage patterns and error frequencies that will help us identify widespread issues affecting the CDK CLI user base.

Customers are opted in to CLI telemetry data collection by default. You can opt out of CDK CLI telemetry using the methods listed below.

AWS CDK collects telemetry data with strict data minimization in mind, preventing identification or attribution to specific users, accounts, or organizations. An exhaustive list of the metrics that are collected by default, with reasons why, is provided below. No further telemetry or metrics are collected.

Please be aware that we are not currently collecting error messages, stack trace, and logs, and that this data collection will be available in a future CDK CLI version under explicit opt-in. More information on these metrics can be found in the table.

The data being collected is as follows:

Metric Description Reason Example

CDK CLI Version

CLI version (x.y.z)

Collecting this will help us bisect our data by version, which can help us identify problematic versions.

 
"2.1100.0"

Installation ID

Random UUID stored on local machines executing CLI commands

This helps us estimate the distinct number of users who are affected by an error. Each unique machine will have their own Installation ID that is generated randomly via UUID V4.

 
"881d3281-2811-4c86-b7b6-4a8a621cf6f2"

Session ID

Random UUID generated on each CLI command invocation

This helps us identify all the events originating from the same command.

 
"c47e3d55-bc20-406b-a02a-e0285dd63230"

Event ID

The Session ID plus a counter

This creates a unique identifier for each event in a session.

 
"c47e3d55-bc20-406b-a02a-e0285dd63230:0"

Region

AWS Region

This will help us bisect our data for region-specific issues.

 
"us-east-1"

Timestamp

The time (generated by the client) the data is sent to our telemetry endpoint

This will help us generate time series graphs.

 
"2025-12-12T00:00:00.000Z"

Event State

The "result" of the event. Possible values are 'SUCCESS', 'FAILURE', 'ABORTED'

This will help us track error rates on each CLI command and alert us to potential regressions before they are reported by customers.

 
"SUCCESS"

Event Type

An identifier for the type of event that produces the data

This is an enum that identifies the kind of event that transpired since there can be multiple events in a command execution.

 
"SYNTH"

Command Path

The command and properties entered into the CLI, with any free text redacted

Along with command parameters, this information helps determine the behavior of the event that transpired, which helps us identify blast radius and cause of issues that arise.

 
["cdk", "deploy", "$STACK1"]

Command Parameters

The optional parameters entered into the CLI, with any free text redacted

Along with command path, this information helps determine the behavior of the event that transpired, which helps us identify blast radius and cause of issues that aries.

 
{
  all: true,
  concurrency: 4
}

Configuration

Additional parameters that may affect the CLI command (i.e. cdk.context.json or context values in cdk.json / ~/.cdk.json), with any free text redacted

This will help us facilitate debugging by providing a comprehensive view of all possible parameters that may affect the behavior of the CLI.

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

Operating System

The operating system that is being used

This will help us debug issues that only affect specific operating systems.

 
{
  platform: "linux",
  release: "5.15.0-1019-aws",
}

CI/CD

Whether or not the CLI command is being invoked from a CI/CD environment

This will help us identify issues specific to CI/CD environments.

 
false

Node Version

The node version used in the environment

This will help us debug any node-specific issues that arise.

 
"v22.0.0"

Duration

The length of the event in milliseconds

This helps us notice patterns in how long specific events take.

 
{ total: 300 }

Counters

Various counter metrics derived from your CDK app and CLI execution

We will monitor how counting stats like (but not limited to) CFN resource count affect the duration of deploy.

 
{
  resourceCount: 25,
  errorCount: 0,
  warningCount: 2,
}

Dependencies

Relevant AWS dependencies and their versions

We plan to track AWS dependencies that might affect the CLI result, like aws-cdk-lib, jsii, projen, etc. We will only collect dependencies on specific AWS-owned libraries.

 
[{ "aws-cdk-lib": "2.232.0"}]

Error Names

The name of the error, if an error occurs.

We only record error names that we control, which helps identify reoccuring error types.

 
"ToolkitError"

The following metrics require explicit opt-in and are NOT currently collected:

Error Messages

The error message returned, if an error occurs. Free form text redacted

[Requires opt-in] Capturing the error message will help us aggregate data on which errors are encountered at a greater rate, as well as help us debug what went wrong in individual use cases.

Not currently collected

Error Stack Trace

The stack trace of the error message, if an error occurs. Free form text redacted

[Requires opt-in] The stack trace will be helpful for individual debugging purposes and is necessary for us to be able to reproduce issues that may arise.

Not currently collected

Error Logs

The logs of a failed CLI command, if an error occurs. Free form text redacted

[Requires opt-in] Error logs will also help us debug and reproduce issues that we see in the CLI.

Not currently collected

How to opt out of CDK CLI telemetry

To view your current telemetry status based on context values and environment variables, run the following command:

cdk cli-telemetry --status

Opt out using context values

If there are conflicts in the context values from various sources, the CDK uses the following order of precedence.

  1. Context values specified using a CDK CLI command with the --context option

  2. Context values in cdk.json

  3. Context values in cdk.context.json

  4. Context values in ~/.cdk.json

To opt out using a CDK CLI command

Run the following CDK CLI command to disable telemetry:

cdk cli-telemetry --disable

Running this command records the action to your local cdk.context.json file and applies to the current CDK application only.

To opt out using the application configuration file

Set cli-telemetry: false in an application’s cdk.json file. This disables telemetry for the application.

To opt out using the global configuration file

Set cli-telemetry: false in the ~/.cdk.json file to disable telemetry for all CDK applications on the same computer. You must specify this setting inside a context element as follows:

{
  "context": {
    "cli-telemetry": false
  }
}

Opt out using an environment variable

Set the CDK_DISABLE_CLI_TELEMETRY environment variable to true to disable CLI telemetry in that environment.

CDK_DISABLE_CLI_TELEMETRY=true

The value of this environment variable takes precendence over any context values that have been set.

Tip

Add this environment variable to your shell startup file, such as .bashrc, to disable telemetry every time you open a terminal window.

Opt out using DNS filtering

The telemetry endpoint is cdk-cli-telemetry.us-east-1.api.aws/metrics. Blocking this domain name in your firewall disables CLI telemetry and does not affect CDK CLI functionality.

Opt out of all usage data reporting

To opt out of all usage data reporting for a single command, use the --no-version-reporting global CLI option. This option turns off both application usage data collection and CDK CLI telemetry.

If you are currently opting out of application usage data collection using the --no-version-reporting option, you are automatically opted out of CDK CLI telemetry for that specific command execution, regardless of context values.

Note

If you set analyticsReporting at the stack level, it takes precedence over the --no-version-reporting option for application usage data collection only.

Send telemetry data to a local file

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

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

Note

If you are using an AWS CDK CLI version below 2.1100.0, you must specify --unstable=telemetry along with --telemetry-file.

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

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

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