[Wiki] Update telemetry article

README.md

@@ -167,6 +167,10 @@ Any use of third-party trademarks or logos are subject to those third-party's po
 * [Azure Resource Manager][AzureResourceManager]
 * [Bicep][Bicep]
 
+## Telemetry
+
+Modules provided in this library have telemetry enabled by default. To learn more about this feature, please refer to the [Telemetry article](https://github.com/Azure/ResourceModules/wiki/The%20library%20-%20Module%20design#telemetry) in the wiki.
+
 <!-- References -->
 
 <!-- Local -->
@@ -178,7 +182,6 @@ Any use of third-party trademarks or logos are subject to those third-party's po
 [Contributing]: CONTRIBUTING.md
 [AzureIcon]: docs/media/MicrosoftAzure-32px.png
 [PowershellIcon]: docs/media/MicrosoftPowerShellCore-32px.png
-[BashIcon]: docs/media/Bash_Logo_black_and_white_icon_only-32px.svg.png
 
 <!-- External -->
 [Bicep]: <https://github.com/Azure/bicep>

SUPPORT.md

@@ -10,9 +10,9 @@ Following list of issues are within the scope of Microsoft support:
 - Module specific issues (e.g., template errors, internal server errors, etc.)
 - Template specific issues (e.g., template publishing, resource removal, etc.)
 
-Any issues that are deemed outside of the above list by Microsoft support and/or requires bugfix in the module or code in the repo, Microsoft support will redirect user to file the issue on GitHub.
+Any issues that are deemed outside of the above list by Microsoft support and/or requires bugfix in the module or code in the repository, Microsoft support will redirect user to file the issue on GitHub.
 
-Project maintainers and community aim to get issues resolved in timely fashion as per community support policy of this repo.
+Project maintainers and community aim to get issues resolved in timely fashion as per community support policy of this repository.
 
 ## Community Support Policy
 
@@ -33,4 +33,3 @@ For help and questions about using this project, please submit a GitHub issue wi
 [Contributing]: CONTRIBUTING.md
 [AzureIcon]: docs/media/MicrosoftAzure-32px.png
 [PowerShellIcon]: docs/media/MicrosoftPowerShellCore-32px.png
-[BashIcon]: docs/media/Bash_Logo_black_and_white_icon_only-32px.svg.png

docs/wiki/The CI environment - GitHub ReadMe module table update.md

@@ -12,7 +12,7 @@ In the platform's pipeline `platform.updateReadMe.yml`, this script is invoked e
 ---
 # Location
 
-You can find the script under [`/utilities/tools/Set-ReadMeModuleTable.ps1`](https://github.com/Azure/ResourceModules/blob/main/utilities/tools/Set-ReadMeModuleTable.ps1)
+You can find the script under [`/utilities/tools/platform/Set-ReadMeModuleTable.ps1`](https://github.com/Azure/ResourceModules/blob/main/utilities/tools/platform/Set-ReadMeModuleTable.ps1)
 
 # How it works
 

docs/wiki/The library - Module design.md

@@ -5,7 +5,7 @@ This section details the design principles followed by the CARML Bicep modules.
 ### _Navigation_
 
 - [General guidelines](#general-guidelines)
-- [File & folder structure](#file--folder-structure)
+- [File \& folder structure](#file--folder-structure)
   - [Structure](#structure)
     - [**Child resources**](#child-resources)
   - [Naming](#naming)
@@ -27,6 +27,10 @@ This section details the design principles followed by the CARML Bicep modules.
 - [ReadMe](#readme)
 - [Module test files](#module-test-files)
 - [Telemetry](#telemetry)
+  - [Overview](#overview)
+  - [Technical Details](#technical-details)
+  - [Opting Out](#opting-out)
+  - [Telemetry vs Customer Usage Attribution](#telemetry-vs-customer-usage-attribution)
 
 ---
 
@@ -655,13 +659,27 @@ In addition, they follow these file-type-specific guidelines:
 
 # Telemetry
 
+## Overview 
+
+Microsoft uses the approach detailed in this section to identify the deployments of the Bicep and ARM JSON templates of the CARML library. Microsoft collects this information to provide the best experiences with their products and to operate their business. Telemetry data is captured through the built-in mechanisms of the Azure platform; therefore, it never leaves the platform, providing only Microsoft with access. Deployments are identified through a specific GUID (Globally Unique ID), indicating that the code originated from the CARML library. The data is collected and governed by Microsoft's privacy policies, located at the [Trust Center](https://www.microsoft.com/en-us/trust-center).
+
+Telemetry collected as described here does not provide Microsoft with insights into the resources deployed, their configuration or any customer data stored in or processed by Azure resources deployed by using code from the CARML library. Microsoft does not track the usage/consumption of individual resources using telemetry described here.
+
+> **Note:** While telemetry gathered as described here is only accessible by Microsoft, Customers have access to the exact same deployment information on the Azure portal, under the Deployments section of the corresponding scope (Resource Group, Subscription, etc.).
+
+## Technical Details
+
 Each module in CARML contains a `defaultTelemetry` deployment `'pid-<GUID>-${uniqueString(deployment().name)}'`, resulting in deployments such as `'pid-<GUID>-nx2c3rnlt2wru'`.
 
 > **Note:** Though implemented at each level in a module hierarchy (e.g., storage account & blobServices), the deployment will only happen for the top-level module in a deployment, but not for its children. To illustrate this better, see the following examples:
 >
 > - Deployment of the KeyVault module and 2 Secrets: Results in 1 `PID` deployment for the KeyVault (and none for the secrets)
 > - Deployment of the Secret module: Results in 1 `PID` deployment for the Secret
 
+## Opting Out
+
+Albeit telemetry described in this section is optional, the implementation follows an opt-out logic, as most commercial software solutions, this project also requires continuously demonstrating evidence of usage, hence the CARML product team recommends leaving the telemetry setting on its default, enabled configuration.
+
 This resource enables the CARML product team to query the number of deployments of a given template from Azure - and as such, get insights into its adoption.
 
 When using CARML's CI environment you can enable/disable this deployment by switching the `enableDefaultTelemetry` setting in the `settings.yml` file in the repository's root. This value is automatically injected into each individual deployment that is performed as part of the environment's pipeline.
@@ -671,6 +689,8 @@ When consuming the modules outside of CARML's pipelines you can either
 - Set the parameter to a default value of `'false'`
 - Set the parameter to false when deploying a module
 
-> **Note:** _The deployment and its GUID can NOT be used to track [Azure Consumed Revenue (ACR)](https://docs.microsoft.com/en-us/azure/marketplace/azure-partner-customer-usage-attribution)._
->
-> _If you want to track consumption, we recommend to implement it on the consuming template's level (i.e., the multi-module solution, such as workload/application) and apply the required naming format `'pid-<GUID>'` (without the suffix)._
+## Telemetry vs Customer Usage Attribution
+
+Though similar in principles, this approach is not to be confused and does not conflict with the usage of CUA IDs that are used to track Customer Usage Attribution of Azure marketplace solutions (partner solutions). The GUID-based telemetry approach described here can coexist and can be used side-by-side with CUA IDs. If you have any partner or customer scenarios that require the addition of CUA IDs, you can customize the modules of this library by adding the required CUA ID deployment while keeping the built-in telemetry solution.
+
+> **Note:** *If you’re a partner and want to build a solution that tracks customer usage attribution (using a [CUA ID](https://learn.microsoft.com/en-us/azure/marketplace/azure-partner-customer-usage-attribution)), we recommend implementing it on the consuming template's level (i.e., the multi-module solution, such as workload/application) and apply the required naming format 'pid-<GUID>' (without the suffix).*