From 68f06c872d321efb55a35d133bf9288ab1f262c5 Mon Sep 17 00:00:00 2001 From: Mate Barabas Date: Fri, 16 Dec 2022 11:02:59 -0800 Subject: [PATCH 1/4] update telemetry article --- README.md | 5 ++++- SUPPORT.md | 1 - docs/wiki/The library - Module design.md | 28 ++++++++++++++++++++---- 3 files changed, 28 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index d069bef803..cfda36cec9 100644 --- a/README.md +++ b/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. + @@ -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 [Bicep]: diff --git a/SUPPORT.md b/SUPPORT.md index e7fec2f4f8..ce083c770d 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -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 diff --git a/docs/wiki/The library - Module design.md b/docs/wiki/The library - Module design.md index 5bc473fce7..2eed8e0796 100644 --- a/docs/wiki/The library - Module design.md +++ b/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,6 +659,16 @@ 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) representing the code is originated in 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--${uniqueString(deployment().name)}'`, resulting in deployments such as `'pid--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: @@ -662,6 +676,10 @@ Each module in CARML contains a `defaultTelemetry` deployment `'pid--${uni > - 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-'` (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 scenario 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-' (without the suffix).* From fff0d74a9f21ab15b245532e70185928c1c18341 Mon Sep 17 00:00:00 2001 From: Mate Barabas Date: Fri, 16 Dec 2022 11:09:36 -0800 Subject: [PATCH 2/4] fix broken link --- .../The CI environment - GitHub ReadMe module table update.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/wiki/The CI environment - GitHub ReadMe module table update.md b/docs/wiki/The CI environment - GitHub ReadMe module table update.md index 091fb6b713..6458fd0e43 100644 --- a/docs/wiki/The CI environment - GitHub ReadMe module table update.md +++ b/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 From 33abbaff21139222141e0b51e47de297a92d0c7c Mon Sep 17 00:00:00 2001 From: Mate Barabas Date: Fri, 16 Dec 2022 11:13:45 -0800 Subject: [PATCH 3/4] language edits --- SUPPORT.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/SUPPORT.md b/SUPPORT.md index ce083c770d..417e6cf191 100644 --- a/SUPPORT.md +++ b/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 From 07f2886b2644fa267a9d264c5ad3a9ebe103d5ca Mon Sep 17 00:00:00 2001 From: Mate Barabas Date: Fri, 16 Dec 2022 13:22:19 -0800 Subject: [PATCH 4/4] update phrasing --- docs/wiki/The library - Module design.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/wiki/The library - Module design.md b/docs/wiki/The library - Module design.md index 2eed8e0796..937b5c207e 100644 --- a/docs/wiki/The library - Module design.md +++ b/docs/wiki/The library - Module design.md @@ -661,7 +661,7 @@ In addition, they follow these file-type-specific guidelines: ## 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) representing the code is originated in 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). +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. @@ -691,6 +691,6 @@ When consuming the modules outside of CARML's pipelines you can either ## 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 scenario 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. +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-' (without the suffix).*