Skip to content

Commit b8eac4a

Browse files
KristinaPetersonKristinaPeterson
committed
Add documentation for opting out of CDK CLI telemetry.
1 parent 1e0ca31 commit b8eac4a

File tree

6 files changed

+145
-8
lines changed

6 files changed

+145
-8
lines changed

‎v2/guide/book.adoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,8 @@ include::configure-access.adoc[leveloffset=+1]
4545

4646
include::configure-env.adoc[leveloffset=+1]
4747

48+
include::chapter-cdk-telemetry.adoc[leveloffset=+1]
49+
4850
include::bootstrapping-env.adoc[leveloffset=+1]
4951

5052
include::chapter-develop.adoc[leveloffset=+1]

‎v2/guide/chapter-cdk-telemetry.adoc‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
include::attributes.txt[]
2+
3+
// Attributes
4+
[.topic]
5+
[#cdktelemetry]
6+
= {aws} CDK telemetry
7+
:keywords: {aws} CDK, IaC, Infrastructure as code, {aws}, telemetry, application usage data reporting, application usage data collection, CLI telemetry
8+
9+
[abstract]
10+
--
11+
Learn about the library metadata and CDK CLI usage data that the {aws} CDK collects and how to opt out of data reporting.
12+
--
13+
14+
// Content start
15+
{aws} Cloud Development Kit ({aws} CDK) applications are configured to collect and report on usage data to gain insight into how the {aws} CDK is being used. To understand the data that is collected, how it's used, and how to opt in or out of data reporting, see xref:usage-data[Configure {aws} CDK Library usage data reporting].
16+
17+
We are not currently collecting or reporting {aws} CDK CLI usage data. However, when {aws} CDK CLI telemetry is released, customers will be opted in to CDK CLI usage data collection and reporting by default. To learn how to opt out of CDK CLI telemetry in advance of its release, see xref:cli-telemetry[Configure {aws} CDK CLI telemetry].
18+
19+
20+
include::usage-data.adoc[leveloffset=+1]
21+
22+
include::cli-telemetry.adoc[leveloffset=+1]

‎v2/guide/chapter-develop.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ After you create a CDK project, import and use constructs from the {aws} CDK Lib
4545

4646
When ready to deploy your application, use the CDK CLI `cdk deploy` command. For instructions, see xref:deploy[Deploy {aws} CDK applications].
4747

48-
include::usage-data.adoc[leveloffset=+1]
48+
4949

5050
include::cfn-layer.adoc[leveloffset=+1]
5151

‎v2/guide/cli-telemetry.adoc‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
include::attributes.txt[]
2+
3+
// Attributes
4+
[.topic]
5+
[#cli-telemetry]
6+
= Configure {aws} CDK CLI telemetry
7+
:info_titleabbrev: Configure CDK CLI telemetry
8+
:keywords: {aws} CDK CLI, reporting, usage data, telemetry
9+
10+
[abstract]
11+
--
12+
The {aws} Cloud Development Kit ({aws} CDK) will begin collecting anonymous telemetry data on CLI usage to gain insight into how the {aws} CDK CLI is being used.
13+
--
14+
15+
// Content start
16+
17+
[#telemetry-intro]
18+
== What is CDK CLI telemetry?
19+
20+
[IMPORTANT]
21+
====
22+
{aws} CDK CLI telemetry has not been released. We are not collecting or reporting CDK CLI usage data. When the feature is released, this documentation will be updated with information about the data that is being collected.
23+
====
24+
25+
When {aws} CDK CLI telemetry is released, customers are opted in to CLI usage data collection and reporting by default. You can opt out of CDK CLI telemetry in advance of its release using the CDK CLI, context values, or an environment variable.
26+
27+
28+
[#telemetry-opt-out]
29+
== How to opt out of CDK CLI telemetry
30+
31+
To view your current telemetry status based on context values and environment variables, run the following command:
32+
33+
[source,none,subs="verbatim,attributes"]
34+
----
35+
cdk cli-telemetry --status
36+
----
37+
[#telemetry-context]
38+
=== Opt out using context values
39+
If there are conflicts in the context values from various sources, the CDK uses the following order of precedence.
40+
41+
. Context values specified using a CDK CLI command with the `--context` option
42+
. Context values in cdk.json
43+
. Context values in cdk.context.json
44+
. Context values in ~/.cdk.json
45+
46+
*To opt out using a CDK CLI command*
47+
48+
Run the following CDK CLI command to disable telemetry:
49+
50+
[source,none,subs="verbatim,attributes"]
51+
----
52+
cdk cli-telemetry --disable
53+
----
54+
55+
Running this command records the action to your local `cdk.context.json` file and applies to the current CDK application only.
56+
57+
*To opt out using the application configuration file*
58+
59+
Set `cli-telemetry: false` in an application's `cdk.json` file. This disables telemetry for the application.
60+
61+
*To opt out using the global configuration file*
62+
63+
Set `cli-telemetry: false` in the `~/.cdk.json` file to disable telemetry for all CDK applications on the same computer.
64+
65+
[#telemetry-environment-variable]
66+
=== Opt out using an environment variable
67+
68+
Set the `CDK_DISABLE_CLI_TELEMETRY` environment variable to `true` to disable CLI telemetry in the that environment.
69+
70+
[source,none,subs="verbatim,attributes"]
71+
----
72+
CDK_DISABLE_CLI_TELEMETRY=true
73+
----
74+
The value of this environment variable takes precendence over any context values that have been set.
75+
76+
[TIP]
77+
====
78+
Add this environment variable to your shell startup file, such as `.bashrc`, to disable telemetry every time you open a terminal window.
79+
====
80+
81+
[#telemetry-optout-all]
82+
=== Opt out of all usage data reporting
83+
84+
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.
85+
86+
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.
87+
88+
[NOTE]
89+
====
90+
If you set `analyticsReporting` at the stack level, it takes precedence over the `--no-version-reporting` option for application usage data collection only.
91+
====
92+
93+
[#telemetry-data-file]
94+
== Send telemetry data to a local file
95+
96+
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.
97+
98+
Use the following option to send telemetry data to a local file:
99+
[source,none,subs="verbatim,attributes"]
100+
----
101+
--telemetry-file='path/to/local/file'
102+
----
103+
104+
[NOTE]
105+
====
106+
The `--telemetry-file` option is being released prior to the launch of the telemetry feature. It is considered production-ready and safe to use. However, you must opt in by providing the `--unstable` option. The `--unstable` flag will be ignored after launch.
107+
====
108+
109+
The following command sends telemetry data to a local file:
110+
[source,none,subs="verbatim,attributes"]
111+
----
112+
cdk deploy --unstable=telemetry --telemetry-file='path/to/local/file'
113+
----

‎v2/guide/create-cdk-pipeline.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ include::attributes.txt[]
99
[#cdk-pipeline]
1010
= Continuous integration and delivery (CI/CD) using CDK Pipelines
1111
:info_titleabbrev: Create CDK Pipelines
12-
12+
:keywords: CDK pipelines, CI/CD, continuous deployment
1313
// Content start
1414

1515
Use the https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.pipelines-readme.html[CDK Pipelines] module from the {aws} Construct Library to configure continuous delivery of {aws} CDK applications. When you commit your CDK app's source code into {aws} CodeCommit, GitHub, or {aws} CodeStar, CDK Pipelines can automatically build, test, and deploy your new version.

‎v2/guide/usage-data.adoc‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,19 +3,19 @@ include::attributes.txt[]
33
// Attributes
44
[.topic]
55
[[usage-data,usage-data.title]]
6-
= Configure {aws} CDK usage data reporting
6+
= Configure {aws} CDK Library usage data reporting
77
:info_titleabbrev: Configure usage data reporting
8-
:keywords: {aws} CDK, Reporting, Usage data, Version reporting
8+
:keywords: {aws} CDK, Reporting, library usage data, Version reporting
99

1010
[abstract]
1111
--
12-
The {aws} Cloud Development Kit ({aws} CDK) collects usage data from your CDK applications to gain insight into how the {aws} CDK is being used. The CDK team uses this data to do the following:
12+
The {aws} Cloud Development Kit ({aws} CDK) collects library usage data from your CDK applications to gain insight into how the {aws} CDK is being used.
1313
--
1414

1515
// Content start
1616

1717
[#usage-data-intro]
18-
== What is CDK usage data reporting?
18+
== What is CDK library usage data reporting?
1919

2020
{aws} Cloud Development Kit ({aws} CDK) applications are configured to collect and report on usage data to gain insight into how the {aws} CDK is being used. The CDK team uses this data to do the following:
2121

@@ -26,7 +26,7 @@ The {aws} Cloud Development Kit ({aws} CDK) collects usage data from your CDK ap
2626
[#usage-data-categories]
2727
== What usage data is collected?
2828

29-
There are two categories of usage data collected by the CDK:
29+
There are two categories of application usage data collected by the CDK:
3030

3131
* General usage data
3232
* Additional usage data
@@ -67,7 +67,7 @@ For property keys and values that you uniquely create, the entire object will be
6767
For more information on additional usage data collection, including its benefits and potential concerns, see the https://github.com/aws/aws-cdk/discussions/33198[CDK Collecting Additional Metadata (under feature flag) #33198] discussion in the _aws-cdk repository_.
6868

6969
[#usage-data-how]
70-
== How the CDK collects usage data
70+
== How the CDK collects application usage data
7171

7272
At synthesis, the CDK collects usage data from your application and stores it within the `{aws}::CDK::Metadata` resource. The following is an example of this on a synthesized {aws} CloudFormation template:
7373

0 commit comments

Comments
 (0)