Merge pull request #244314 from hhunter-ms/hh-59624

[Profiler] Low engagement freshness passes

Author: Court72

articles/azure-monitor/profiler/profiler-bring-your-own-storage.md

@@ -1,76 +1,53 @@
 ---
 title: Configure BYOS for Profiler and Snapshot Debugger
-description: Configure Bring Your Own Storage (BYOS) for Profiler and Snapshot Debugger.
+description: Configure Bring Your Own Storage (BYOS) for Azure Application Insights Profiler and Snapshot Debugger.
 ms.author: hannahhunter
 author: hhunter-ms
 ms.reviewer: charles.weininger
 reviewer: cweining
 ms.topic: conceptual
-ms.date: 08/18/2022
-ms.custom: devdivchpfy22, devx-track-azurepowershell
+ms.date: 07/07/2023
+ms.custom: devdivchpfy22, devx-track-azurepowershell, engagement
 ---
 
 # Configure BYOS for Application Insights Profiler and Snapshot Debugger
 
-This article shows you how to configure Bring Your Own Storage (BYOS) for Application Insights Profiler and Snapshot Debugger.
+When you use [Application Insights Profiler](./profiler-overview.md) or [Snapshot Debugger](../snapshot-debugger/snapshot-debugger.md), artifacts generated by your application are uploaded by default into Azure Storage accounts over the public internet. For these artifacts and storage accounts, Microsoft controls and covers the cost for:
 
-## What is BYOS and why might I need it?
+- Processing and analysis.
+- Encryption-at-rest and lifetime management policies.
 
-When you use Application Insights Profiler or Snapshot Debugger, artifacts generated by your application are uploaded into Azure Storage accounts over the public internet. For these artifacts and storage accounts, Microsoft controls and covers the cost for:
+Meanwhile, when you configure your own storage account (BYOS), artifacts are uploaded into a storage account that only you control and cover the cost for:
 
-* Processing and analysis.
-* Encryption-at-rest and lifetime management policies.
-
-When you configure BYOS, artifacts are uploaded into a storage account that you control. That means you control and are responsible for the cost of:
-
-* The encryption-at-rest policy and the Lifetime management policy.
-* Network access.
+- The encryption-at-rest policy and the Lifetime management policy.
+- Network access.
 
 > [!NOTE]
 > BYOS is required if you're enabling Azure Private Link or customer-managed keys.
 >
-> * [Learn more about Private Link for Application Insights](../logs/private-link-security.md).
-> * [Learn more about customer-managed keys for Application Insights](../logs/customer-managed-keys.md).
-
-## How is my storage account accessed?
-
-1. Agents running in your virtual machines or Azure App Service upload artifacts (profiles, snapshots, and symbols) to blob containers in your account.
-
-    This process involves contacting Profiler or Snapshot Debugger to obtain a shared access signature token to a new blob in your storage account.
+> - [Learn more about Private Link for Application Insights](../logs/private-link-security.md).
+> - [Learn more about customer-managed keys for Application Insights](../logs/customer-managed-keys.md).
 
-1. Profiler or Snapshot Debugger will:
-
-    - Analyze the incoming blob.
-    - Write back the analysis results and log files into blob storage.
-  
-    Depending on available compute capacity, this process might occur anytime after upload.
-
-1. When you view Profiler traces or Snapshot Debugger analysis, the service fetches the analysis results from blob storage.
+In this guide, you learn how to:
+> [!div class="checklist"]
+> - Grant Diagnostic Services access to your storage account.
+> - Link your storage account with your Application Insights resource.
+> - Learn how your storage account is accessed.
 
 ## Prerequisites
 
-* Create your storage account in the same location as your Application Insights resource.
-
-    For example, if your Application Insights resource is in West US 2, your storage account must also be in West US 2.
+- Verify you've created your storage account in the same location as your Application Insights resource.
+- If you've enabled [Private Link](../logs/private-link-security.md), allow connection to our Trusted Microsoft Service from your virtual network.
 
-* Grant the `Storage Blob Data Contributor` role to the Azure Active Directory (Azure AD) application named `Diagnostic Services Trusted Storage Access` via the [Access Control (IAM)](../../role-based-access-control/role-assignments-portal.md) page in your storage account.
-* If Private Link is enabled, allow connection to our Trusted Microsoft Service from your virtual network.
+## Grant Diagnostic Services access to your storage account
 
-## Enable BYOS
-
-This section shows you how to enable BYOS.
-
-### Grant access to Diagnostic Services to your storage account
-
-A BYOS storage account is linked to an Application Insights resource. There might be only one storage account per Application Insights resource and both must be in the same location. You might use the same storage account with more than one Application Insights resource.
-
-First, Application Insights Profiler and Snapshot Debugger must be granted access to the storage account. To grant access, add the role `Storage Blob Data Contributor` to the Azure AD application named `Diagnostic Services Trusted Storage Access` via the **Access Control (IAM)** page in your storage account.
+A BYOS storage account is linked to an Application Insights resource. Start by granting the `Storage Blob Data Contributor` role to the Azure Active Directory (Azure AD) application named `Diagnostic Services Trusted Storage Access` via the [Access Control (IAM)](../../role-based-access-control/role-assignments-portal.md) page in your storage account.  
 
 1. Select **Access control (IAM)**.
 
 1. Select **Add** > **Add role assignment** to open the **Add role assignment** page.
 
-1. Assign the following role. For more information, see [Assign Azure roles by using the Azure portal](../../role-based-access-control/role-assignments-portal.md).
+1. Assign the following role. 
 
     | Setting | Value |
     | --- | --- |
@@ -80,24 +57,23 @@ First, Application Insights Profiler and Snapshot Debugger must be granted acces
 
     :::image type="content" source="media/profiler-bring-your-own-storage/add-role-assignment-page.png" alt-text="Screenshot that shows the Add role assignment page in the Azure portal.":::
 
-   After you add the role, it appears under the **Role assignments** section.
+   Once assigned, you can see the role under the **Role assignments** section.
        :::image type="content" source="media/profiler-bring-your-own-storage/figure-11.png" alt-text="Screenshot that shows the IAM screen after Role assignments.":::
-    
-If you're also using Private Link, one more configuration is required to allow connection to our Trusted Microsoft Service from your virtual network. For more information, see [Storage network security documentation](../../storage/common/storage-network-security.md#trusted-microsoft-services).
 
-### Link your storage account with your Application Insights resource
+> [!NOTE]    
+> If you're also using Private Link, one more configuration is required to allow connection to our Trusted Microsoft Service from your virtual network. For more information, see [Storage network security documentation](../../storage/common/storage-network-security.md#trusted-microsoft-services).
 
-To configure BYOS for code-level diagnostics (Profiler/Snapshot Debugger), there are three options:
+## Link your storage account with your Application Insights resource
 
-* Use Azure PowerShell cmdlets.
-* Use the Azure CLI.
-* Use Azure Resource Manager templates.
+You have three options for configuring BYOS for code-level diagnostics like Profiler and Snapshot Debugger:
 
-#### [PowerShell](#tab/azure-powershell)
+- Azure PowerShell cmdlets
+- The Azure CLI
+- Azure Resource Manager templates
 
-1. Make sure you've installed Az PowerShell 4.2.0 or greater.
+#### [PowerShell](#tab/azure-powershell)
 
-    To install Azure PowerShell, see the [Azure PowerShell documentation](/powershell/azure/install-azure-powershell).
+Before you begin, [install Azure PowerShell 4.2.0 or greater](/powershell/azure/install-azure-powershell).
 
 1. Install the Application Insights PowerShell extension.
 
@@ -145,9 +121,7 @@ To configure BYOS for code-level diagnostics (Profiler/Snapshot Debugger), there
 
 #### [Azure CLI](#tab/azure-cli)
 
-1. Make sure you've installed the Azure CLI.
-
-    To install the Azure CLI, see the [Azure CLI documentation](/cli/azure/install-azure-cli).
+Before you begin, [install the Azure CLI](/cli/azure/install-azure-cli).
 
 1. Install the Application Insights CLI extension.
 
@@ -234,7 +208,7 @@ To configure BYOS for code-level diagnostics (Profiler/Snapshot Debugger), there
     |           Parameter           |                                Description                               |
     |-------------------------------|--------------------------------------------------------------------------|
     | `application_insights_name`     | The name of the Application Insights resource to enable BYOS.            |
-    | `storage_account_name`          | The name of the storage account resource that you'll use as your BYOS. |
+    | `storage_account_name`          | The name of the storage account resource that you use as your BYOS. |
   
     Expected output:
 
@@ -260,95 +234,125 @@ To configure BYOS for code-level diagnostics (Profiler/Snapshot Debugger), there
     DeploymentDebugLogLevel :
     ```
 
-1. Enable code-level diagnostics (Profiler/Snapshot Debugger) on the workload of interest through the Azure portal. In this example, it's **App Service** > **Application Insights**.
+1. Enable Profiler or Snapshot Debugger on the workload of interest through the Azure portal. In this example, it's **App Service** > **Application Insights**.
 
     :::image type="content" source="media/profiler-bring-your-own-storage/figure-20.png" alt-text="Screenshot that shows the code-level diagnostics in the Azure portal.":::
 
+---
+
 ## Troubleshooting
 
-This section offers troubleshooting tips for common issues.
+This section offers troubleshooting tips for common issues in configuring BYOS. 
 
-### Template schema '{schema_uri}' isn't supported
+- For general Profiler troubleshooting, see the [Profiler troubleshooting documentation](profiler-troubleshooting.md).
+- For general Snapshot Debugger troubleshooting, see the [Snapshot Debugger troubleshooting documentation](/troubleshoot/azure/azure-monitor/app-insights/snapshot-debugger-troubleshoot).
 
-* Make sure that the `$schema` property of the template is valid. It must follow this pattern:
-`https://schema.management.azure.com/schemas/{schema_version}/deploymentTemplate.json#`.
-* Make sure that the `schema_version` of the template is within valid values: `2014-04-01-preview, 2015-01-01, 2018-05-01, 2019-04-01, 2019-08-01`.
-    
-    Error message:
+### Scenario: Template schema '{schema_uri}' isn't supported
 
-    ```powershell
-    New-AzResourceGroupDeployment : 11:53:49 AM - Error: Code=InvalidTemplate; Message=Deployment template validation failed: 'Template schema
-    'https://schema.management.azure.com/schemas/2020-01-01/deploymentTemplate.json#' is not supported. Supported versions are
-    '2014-04-01-preview,2015-01-01,2018-05-01,2019-04-01,2019-08-01'. Please see https://aka.ms/arm-template for usage details.'.
-    ```
+You've received an error similar to the following example:
 
-### No registered resource provider found for location '{location}'
+```powershell
+New-AzResourceGroupDeployment : 11:53:49 AM - Error: Code=InvalidTemplate; Message=Deployment template validation failed: 'Template schema
+'https://schema.management.azure.com/schemas/2020-01-01/deploymentTemplate.json#' is not supported. Supported versions are
+'2014-04-01-preview,2015-01-01,2018-05-01,2019-04-01,2019-08-01'. Please see https://aka.ms/arm-template for usage details.'.
+```
 
-* Make sure that the `apiVersion` of the resource `microsoft.insights/components` is `2015-05-01`.
-* Make sure that the `apiVersion` of the resource `linkedStorageAccount` is `2020-03-01-preview`.
-    
-    Error message:
-
-    ```powershell
-    New-AzResourceGroupDeployment : 6:18:03 PM - Resource microsoft.insights/components 'byos-test-westus2-ai' failed with message '{
-      "error": {
-        "code": "NoRegisteredProviderFound",
-        "message": "No registered resource provider found for location 'westus2' and API version '2020-03-01-preview' for type 'components'. The supported api-versions are '2014-04-01,
-    2014-08-01, 2014-12-01-preview, 2015-05-01, 2018-05-01-preview'. The supported locations are ', eastus, southcentralus, northeurope, westeurope, southeastasia, westus2, uksouth,
-    canadacentral, centralindia, japaneast, australiaeast, koreacentral, francecentral, centralus, eastus2, eastasia, westus, southafricanorth, northcentralus, brazilsouth, switzerlandnorth,
-    australiasoutheast'."
-      }
-    }'
-    ```
+#### Solutions
 
-### Storage account location should match AI component location
+- Make sure that the `$schema` property of the template is valid. It must follow this pattern:
+  ```
+  https://schema.management.azure.com/schemas/{schema_version}/deploymentTemplate.json#
+  ```
 
-* Make sure that the location of the Application Insights resource is the same as the storage account.
+- Make sure that the `schema_version` of the template is within valid values: `2014-04-01-preview, 2015-01-01, 2018-05-01, 2019-04-01, 2019-08-01`.
 
-    Error message:
-
-    ```powershell
-    New-AzResourceGroupDeployment : 1:01:12 PM - Resource microsoft.insights/components/linkedStorageAccounts 'byos-test-centralus-ai/serviceprofiler' failed with message '{
-      "error": {
-        "code": "BadRequest",
-        "message": "Storage account location should match AI component location",
-        "innererror": {
-          "trace": [
-            "System.ArgumentException"
-          ]
-        }
-      }
-    }'
-    ```
-
-For general Profiler troubleshooting, see the [Profiler troubleshooting documentation](profiler-troubleshooting.md).
+### Scenario: No registered resource provider found for location '{location}'
+
+You've received an error similar to the following example:
+
+```powershell
+New-AzResourceGroupDeployment : 6:18:03 PM - Resource microsoft.insights/components 'byos-test-westus2-ai' failed with message '{
+  "error": {
+    "code": "NoRegisteredProviderFound",
+    "message": "No registered resource provider found for location 'westus2' and API version '2020-03-01-preview' for type 'components'. The supported api-versions are '2014-04-01,
+2014-08-01, 2014-12-01-preview, 2015-05-01, 2018-05-01-preview'. The supported locations are ', eastus, southcentralus, northeurope, westeurope, southeastasia, westus2, uksouth,
+canadacentral, centralindia, japaneast, australiaeast, koreacentral, francecentral, centralus, eastus2, eastasia, westus, southafricanorth, northcentralus, brazilsouth, switzerlandnorth,
+australiasoutheast'."
+  }
+}'
+```
+
+#### Solutions
+
+- Make sure that the `apiVersion` of the resource `microsoft.insights/components` is `2015-05-01`.
+- Make sure that the `apiVersion` of the resource `linkedStorageAccount` is `2020-03-01-preview`.
+    
+### Scenario: Storage account location should match Application Insights component location
+
+You've received an error similar to the following example:
+
+```powershell
+New-AzResourceGroupDeployment : 1:01:12 PM - Resource microsoft.insights/components/linkedStorageAccounts 'byos-test-centralus-ai/serviceprofiler' failed with message '{
+  "error": {
+    "code": "BadRequest",
+    "message": "Storage account location should match AI component location",
+    "innererror": {
+      "trace": [
+        "System.ArgumentException"
+      ]
+    }
+  }
+}'
+```
 
-For general Snapshot Debugger troubleshooting, see the [Snapshot Debugger troubleshooting documentation](/troubleshoot/azure/azure-monitor/app-insights/snapshot-debugger-troubleshoot).
+#### Solution
 
+Make sure that the location of the Application Insights resource is the same as the storage account.
+    
 ## Frequently asked questions
 
-This section provides answers to common questions.
+This section provides answers to common questions about configuring BYOS for Profiler and Snapshot Debugger.
 
-### If I've enabled Profiler/Snapshot Debugger and BYOS, will my data be migrated into my storage account?
+### If I've enabled Profiler/Snapshot Debugger and BYOS, is my data migrated into my storage account?
 
   No, it won't.
 
-### Will BYOS work with encryption-at-rest and customer-managed keys?
+### Does BYOS work with encryption-at-rest and customer-managed keys?
 
   Yes. To be precise, BYOS is a requirement to have Profiler/Snapshot Debugger enabled with customer-manager keys.
 
-### Will BYOS work in an environment isolated from the internet?
+### Does BYOS work in an environment isolated from the internet?
 
   Yes. BYOS is a requirement for isolated network scenarios.
 
-### Will BYOS work with both customer-managed keys and Private Link enabled?
+### Does BYOS work with both customer-managed keys and Private Link enabled?
 
   Yes, it's possible.
 
 ### If I've enabled BYOS, can I go back to using Diagnostic Services storage accounts to store my collected data?
 
   Yes, you can, but we don't currently support data migration from your BYOS.
 
-### After I enable BYOS, will I take over all the related costs of storage and networking?
+### After I enable BYOS, do I take over all the related costs of storage and networking?
+
+  Yes. 
+
+### How is my storage account accessed?
+
+1. Agents running in your virtual machines or Azure App Service upload artifacts (profiles, snapshots, and symbols) to blob containers in your account.
+
+    This process involves contacting Profiler or Snapshot Debugger to obtain a shared access signature token to a new blob in your storage account.
+
+1. Profiler or Snapshot Debugger:
+
+    - Analyzes the incoming blob.
+    - Write back the analysis results and log files into blob storage.
+  
+    Depending on available compute capacity, this process might occur anytime after upload.
+
+1. When you view Profiler traces or Snapshot Debugger analysis, the service fetches the analysis results from blob storage.
+
+## Next steps
 
-  Yes.
+- [Learn more about Application Insights Profiler](./profiler-overview.md)
+- [Learn more about Snapshot Debugger](../snapshot-debugger/snapshot-debugger.md)