+| (retired) | Detect potentially offensive or unwanted content. |

+| | Help users read and comprehend text. |

+| (retired) | Understand natural language in your apps. |

+| (retired) | Distill information into easy-to-navigate questions and answers. |

+|</br>[Video Indexer](/azure/azure-video-indexer/language-identification-model#guidelines-and-limitations) | Extract actionable insights from your videos. |

+|</br>[Anomaly Detector](./Anomaly-Detector/index.yml) | Identify potential problems early on. |

+|</br>[Custom Vision](./custom-vision-service/index.yml) |Customize image recognition for your business. |

+|</br>[Personalizer](./personalizer/index.yml) | Create rich, personalized experiences for users. |

+|  [Content Moderator](./content-moderator/index.yml) (retired) | Detect potentially offensive or unwanted content. |

+|  [Custom Vision](./custom-vision-service/index.yml) | Customize image recognition for your business. |

+|  [Translator](./translator/index.yml) | Use AI-powered translation technology to translate more than 100 in-use, at-risk, and endangered languages and dialects. |

+After you connect Azure OpenAI to your data, you can deploy it using the **Deploy to** button in Azure OpenAI Studio.

+You can deploy to a copilot in [Copilot Studio](/microsoft-copilot-studio/fundamentals-what-is-copilot-studio) (preview) directly from Azure OpenAI Studio, enabling you to bring conversational experiences to various channels such as: Microsoft Teams, websites, Dynamics 365, and other [Azure Bot Service channels](/microsoft-copilot-studio/publication-connect-bot-to-azure-bot-service-channels). The tenant used in the Azure OpenAI service and Copilot Studio (preview) should be the same. For more information, see [Use a connection to Azure OpenAI On Your Data](/microsoft-copilot-studio/nlu-generative-answers-azure-openai).

+- The latest version of [Teams Toolkit](https://marketplace.visualstudio.com/items?itemName=TeamsDevApp.ms-teams-vscode-extension) installed. This is a VS Code extension that creates a project scaffolding for your app.

+- [Node.js](https://nodejs.org/en/download/) (version 16 or 18) installed. For more information, see [Node.js version compatibility table for project type](/microsoftteams/platform/toolkit/build-environments#nodejs-version-compatibility-table-for-project-type).

+To troubleshoot failed operations, always look out for errors or warnings specified either in the API response or Azure OpenAI Studio. Here are some of the common errors and warnings:

+| **What you don’t get** |❌Data processing guarantee<br> <br> Data might be processed outside of the resource's Azure geography, but data storage remains in its Azure geography. [Learn more about data residency](https://azure.microsoft.com/explore/global-infrastructure/data-residency/) | ❌High volume w/consistent low latency | ❌Pay-per-call flexibility |

+> [!IMPORTANT]

+> Data might be processed outside of the resource's Azure geography, but data storage remains in its Azure geography. [Learn more about data residency](https://azure.microsoft.com/explore/global-infrastructure/data-residency/).

+|Enterprise agreement | 30 M | 60 K |

+|  [Azure AI Search](../../search/index.yml) | Bring AI-powered cloud search to your mobile and web apps | [Azure AI Search API](/rest/api/searchservice) |

+| </br>&bullet; [fine-tuning](/rest/api/azureopenai/fine-tuning) |

+|  [Bot Service](/composer/) | Create bots and connect them across channels | [Bot Service API](/azure/bot-service/rest-api/bot-framework-rest-connector-api-reference?view=azure-bot-service-4.0&preserve-view=true) |

+|  [Custom Vision](../custom-vision-service/index.yml) | Customize image recognition for your business applications. |**Custom Vision APIs**<br>&bullet; [prediction](https://westus2.dev.cognitive.microsoft.com/docs/services/Custom_Vision_Prediction_3.1/operations/5eb37d24548b571998fde5f3)<br>&bullet; [training](https://westus2.dev.cognitive.microsoft.com/docs/services/Custom_Vision_Training_3.3/operations/5eb0bcc6548b571998fddebd)|

+|  [Video Indexer](/azure/azure-video-indexer) | Extract actionable insights from your videos | [Video Indexer API](/rest/api/videoindexer/accounts?view=rest-videoindexer-2024-01-01&preserve-view=true) |

+|  [Anomaly Detector](../Anomaly-Detector/index.yml) <br>(deprecated 2023) | Identify potential problems early on | [Anomaly Detector API](https://westus2.dev.cognitive.microsoft.com/docs/services/AnomalyDetector-v1-1/operations/CreateMultivariateModel) |

+|  |

+|  [Language understanding (LUIS)](../luis/index.yml) <br>(deprecated 2023) | Understand natural language in your apps | [LUIS API](https://westus.dev.cognitive.microsoft.com/docs/services/luis-endpoint-api-v3-0/operations/5cb0a9459a1fe8fa44c28dd8) |

+|  [Metrics Advisor](../metrics-advisor/index.yml) <br>(deprecated 2023) | An AI service that detects unwanted contents | [Metrics Advisor API](https://westus.dev.cognitive.microsoft.com/docs/services/MetricsAdvisor/operations/createDataFeed) |

+|  [Personalizer](../personalizer/index.yml) <br>(deprecated 2023) | Create rich, personalized experiences for each user | [Personalizer API](https://westus2.dev.cognitive.microsoft.com/docs/services/personalizer-api/operations/Rank) |

+|  [QnA maker](../qnamaker/index.yml) <br>(deprecated 2022) | Distill information into easy-to-navigate questions and answers | [QnA Maker API](https://westus.dev.cognitive.microsoft.com/docs/services/5a93fcf85b4ccd136866eb37/operations/5ac266295b4ccd1554da75ff) |

+Azure AI Speech service offers advanced speech to text capabilities. This feature supports both real-time and batch transcription, providing versatile solutions for converting audio streams into text.

+## Core Features

+The speech to text service offers the following core features:

+- [Real-time](#real-time-speech-to-text) transcription: Instant transcription with intermediate results for live audio inputs.

+- [Fast transcription](#fast-transcription-preview): Fastest synchronous output for situations with predictable latency.

+- [Batch transcription](#batch-transcription-api): Efficient processing for large volumes of prerecorded audio.

+- [Custom speech](#custom-speech): Models with enhanced accuracy for specific domains and conditions.

+Real-time speech to text transcribes audio as it's recognized from a microphone or file. It's ideal for applications requiring immediate transcription, such as:

+- **Transcriptions, captions, or subtitles for live meetings**: Real-time audio transcription for accessibility and record-keeping.

+- **Diarization**: Identifying and distinguishing between different speakers in the audio.

+- **Pronunciation assessment**: Evaluating and providing feedback on pronunciation accuracy.

+- **Call center agents assist**: Providing real-time transcription to assist customer service representatives.

+- **Dictation**: Transcribing spoken words into written text for documentation purposes.

+- **Voice agents**: Enabling interactive voice response systems to transcribe user queries and commands.

+Real-time speech to text can be accessed via the Speech SDK, Speech CLI, and REST API, allowing integration into various applications and workflows.

+Real-time speech to text is available via the [Speech SDK](speech-sdk.md), the [Speech CLI](spx-overview.md), and REST APIs such as the [Fast transcription API](fast-transcription-create.md).

+Fast transcription API is used to transcribe audio files with returning results synchronously and faster than real-time audio. Use fast transcription in the scenarios that you need the transcript of an audio recording as quickly as possible with predictable latency, such as:

+- **Quick audio or video transcription and subtitles**: Quickly get a transcription of an entire video or audio file in one go.

+- **Video translation**: Immediately get new subtitles for a video if you have audio in different languages.

+[Batch transcription](batch-transcription.md) is designed for transcribing large amounts of audio stored in files. This method processes audio asynchronously and is suited for:

+- **Transcriptions, captions, or subtitles for prerecorded audio**: Converting stored audio content into text.

+- **Contact center post-call analytics**: Analyzing recorded calls to extract valuable insights.

+- **Diarization**: Differentiating between speakers in recorded audio.

+- [Speech to text REST API](rest-speech-to-text.md): Facilitates batch processing with the flexibility of RESTful calls. To get started, see [How to use batch transcription](batch-transcription.md) and [Batch transcription samples](https://github.com/Azure-Samples/cognitive-services-speech-sdk/tree/master/samples/batch).

+- [Speech CLI](spx-overview.md): Supports both real-time and batch transcription, making it easy to manage transcription tasks. For Speech CLI help with batch transcriptions, run the following command:

+Custom speech allows you to tailor the speech recognition model to better suit your application's specific needs. This can be particularly useful for:

+- **Improving recognition of domain-specific vocabulary**: Train the model with text data relevant to your field.

+- **Enhancing accuracy for specific audio conditions**: Use audio data with reference transcriptions to refine the model.

+For more information about custom speech, see the [custom speech overview](./custom-speech-overview.md) and the [speech to text REST API](rest-speech-to-text.md) documentation.

+For details about customization options per language and locale, see the [language and voice support for the Speech service](./language-support.md?tabs=stt) documentation.

+## Usage Examples

+Here are some practical examples of how you can utilize Azure AI speech to text:

+| Use case | Scenario | Solution |

+| | | |

+| **Live meeting transcriptions and captions** | A virtual event platform needs to provide real-time captions for webinars. | Integrate real-time speech to text using the Speech SDK to transcribe spoken content into captions displayed live during the event. |

+| **Customer service enhancement** | A call center wants to assist agents by providing real-time transcriptions of customer calls. | Use real-time speech to text via the Speech CLI to transcribe calls, enabling agents to better understand and respond to customer queries. |

+| **Video subtitling** | A video-hosting platform wants to quickly generate a set of subtitles for a video. | Use fast transcription to quickly get a set of subtitles for the entire video. |

+| **Educational tools** | An e-learning platform aims to provide transcriptions for video lectures. | Apply batch transcription through the speech to text REST API to process prerecorded lecture videos, generating text transcripts for students. |

+| **Healthcare documentation** | A healthcare provider needs to document patient consultations. | Use real-time speech to text for dictation, allowing healthcare professionals to speak their notes and have them transcribed instantly. Use a custom model to enhance recognition of specific medical terms. |

+| **Media and entertainment** | A media company wants to create subtitles for a large archive of videos. | Use batch transcription to process the video files in bulk, generating accurate subtitles for each video. |

+| **Market research** | A market research firm needs to analyze customer feedback from audio recordings. | Employ batch transcription to convert audio feedback into text, enabling easier analysis and insights extraction. |

+## Related content

+- For detailed pricing information, visit the [Speech service pricing](https://azure.microsoft.com/pricing/details/cognitive-services/speech-services/) page.

+|  [Anomaly Detector](./Anomaly-Detector/index.yml) (retired) | Identify potential problems early on. |

+|  [Azure AI Search](../search/index.yml) | Bring AI-powered cloud search to your mobile and web apps. |

+|  [Bot Service](/composer/) | Create bots and connect them across channels. |

+|  [Content Moderator](./content-moderator/index.yml) (retired) | Detect potentially offensive or unwanted content. |

+|  [Custom Vision](./custom-vision-service/index.yml) | Customize image recognition for your business. |

+|  [Immersive Reader](./immersive-reader/index.yml) | Help users read and comprehend text. |

+|  [Language understanding](./luis/index.yml) (retired) | Understand natural language in your apps. |

+|  [Metrics Advisor](./metrics-advisor/index.yml) (retired) | An AI service that detects unwanted contents. |

+|  [Personalizer](./personalizer/index.yml) (retired) | Create rich, personalized experiences for each user. |

+|  [QnA maker](./qnamaker/index.yml) (retired) | Distill information into easy-to-navigate questions and answers. |

+|  [Video Indexer](/azure/azure-video-indexer/) | Extract actionable insights from your videos. |

+description: Learn how to deploy Mistral family of models with Azure AI Studio.

+* __Premium models__: Mistral Large (2402), Mistral Large (2407), and Mistral Small.

+* __Open models__: Mistral Nemo, Mixtral-8x7B-Instruct-v01, Mixtral-8x7B-v01, Mistral-7B-Instruct-v01, and Mistral-7B-v01.

+All the premium models and Mistral Nemo (an open model) can be deployed as serverless APIs with pay-as-you-go token-based billing. The other open models can be deployed to managed computes in your own Azure subscription.

+Mistral Large is Mistral AI's most advanced Large Language Model (LLM). It can be used on any language-based task, thanks to its state-of-the-art reasoning and knowledge capabilities. There are two variants available for the Mistral Large model version:

+- Mistral Large (2402)

+- Mistral Large (2407)

+Additionally, some attributes of _Mistral Large (2402)_ include:

+And attributes of _Mistral Large (2407)_ include:

+- **Multi-lingual by design.** Supports dozens of languages, including English, French, German, Spanish, and Italian.

+- **Proficient in coding.** Trained on more than 80 coding languages, including Python, Java, C, C++, JavaScript, and Bash. Also trained on more specific languages such as Swift and Fortran.

+- **Agent-centric.** Possesses agentic capabilities with native function calling and JSON outputting.

+- **Advanced in reasoning.** Demonstrates state-of-the-art mathematical and reasoning capabilities.

+- **A small model optimized for low latency.** Efficient for high volume and low latency workloads. Mistral Small is Mistral's smallest proprietary model, it outperforms Mixtral-8x7B and has lower latency.

+# [Mistral Nemo](#tab/mistral-nemo)

+Mistral Nemo is a cutting-edge Language Model (LLM) boasting state-of-the-art reasoning, world knowledge, and coding capabilities within its size category.

+Mistral Nemo is a 12B model, making it a powerful drop-in replacement for any system using Mistral 7B, which it supersedes. It supports a context length of 128K, and it accepts only text inputs and generates text outputs.

+Additionally, Mistral Nemo is:

+- **Jointly developed with Nvidia.** This collaboration has resulted in a powerful 12B model that pushes the boundaries of language understanding and generation.

+- **Multilingual proficient.** Mistral Nemo is equipped with a tokenizer called Tekken, which is designed for multilingual applications. It supports over 100 languages, such as English, French, German, and Spanish. Tekken is more efficient than the Llama 3 tokenizer in compressing text for approximately 85% of all languages, with significant improvements in Malayalam, Hindi, Arabic, and prevalent European languages.

+- **Agent-centric.** Mistral Nemo possesses top-tier agentic capabilities, including native function calling and JSON outputting.

+- **Advanced in reasoning.** Mistral Nemo demonstrates state-of-the-art mathematical and reasoning capabilities within its size category.

+**Mistral Large (2402)**, **Mistral Large (2407)**, **Mistral Small**, and **Mistral Nemo** can be deployed as a serverless API with pay-as-you-go billing and are offered by Mistral AI through the Microsoft Azure Marketplace. Mistral AI can change or update the terms of use and pricing of these models.

+The following steps demonstrate the deployment of Mistral Large (2402), but you can use the same steps to deploy Mistral Nemo or any of the premium Mistral models by replacing the model name.

+1. Search for and select the Mistral Large (2402) model to open its Details page.

+ 1. Search for and select the Mistral Large (2402) model to open the Model's Details page.

+You can consume Mistral models by using the chat API.

+Mistral family models | mistralai-Mixtral-8x22B-v0-1 <br> mistralai-Mixtral-8x22B-Instruct-v0-1 <br> mistral-community-Mixtral-8x22B-v0-1 <br> mistralai-Mixtral-8x7B-v01 <br> mistralai-Mistral-7B-Instruct-v0-2 <br> mistralai-Mistral-7B-v01 <br> mistralai-Mixtral-8x7B-Instruct-v01 <br> mistralai-Mistral-7B-Instruct-v01 | Mistral-large (2402) <br> Mistral-large (2407) <br> Mistral-small <br> Mistral-Nemo

+Phi3 family models | Phi-3-mini-4k-Instruct <br> Phi-3-mini-128k-Instruct <br> Phi-3-small-8k-Instruct <br> Phi-3-small-128k-Instruct <br> Phi-3-medium-4k-instruct <br> Phi-3-medium-128k-instruct | Phi-3-mini-4k-Instruct <br> Phi-3-mini-128k-Instruct <br> Phi-3-small-8k-Instruct <br> Phi-3-small-128k-Instruct <br> Phi-3-medium-4k-instruct <br> Phi-3-medium-128k-instruct

+Mistral Large (2402) <br> Mistral-Large (2407) | [Microsoft Managed Countries](/partner-center/marketplace/tax-details-marketplace#microsoft-managed-countriesregions) <br> Brazil <br> Hong Kong <br> Israel| East US, East US 2, North Central US, South Central US, Sweden Central, West US, West US 3 | Not available

+Mistral Nemo | [Microsoft Managed Countries](/partner-center/marketplace/tax-details-marketplace#microsoft-managed-countriesregions) <br> Brazil <br> Hong Kong <br> Israel| East US, East US 2, North Central US, South Central US, Sweden Central, West US, West US 3 | Not available

+Phi-3-mini-4k-instruct <br> Phi-3-mini-128k-instruct | [Microsoft Managed Countries](/partner-center/marketplace/tax-details-marketplace#microsoft-managed-countriesregions) | East US 2, Sweden Central | Not available

+Phi-3-small-8k-instruct <br> Phi-3-small-128k-Instruct | [Microsoft Managed Countries](/partner-center/marketplace/tax-details-marketplace#microsoft-managed-countriesregions) | East US 2, Sweden Central | Not available

+Phi-3-medium-4k-instruct <br> Phi-3-medium-128k-instruct | [Microsoft Managed Countries](/partner-center/marketplace/tax-details-marketplace#microsoft-managed-countriesregions) | East US 2, Sweden Central | Not available

+ Title: View Azure Kubernetes Service (AKS) container logs, events, and pod metrics in real time

+description: Learn how to view Azure Kubernetes Service (AKS) container logs, events, and pod metrics in real time using Container Insights.

+# View Azure Kubernetes Service (AKS) container logs, events, and pod metrics in real time

+In this article, you learn how to use the *live data* feature in Container Insights to view Azure Kubernetes Service (AKS) container logs, events, and pod metrics in real time. This feature provides direct access to `kubectl logs -c`, `kubectl get` events, and `kubectl top pods` to help you troubleshoot issues in real time.

+> [!NOTE]

+> AKS uses [Kubernetes cluster-level logging architectures][kubernetes-cluster-architecture]. The container logs are located inside `/var/log/containers` on the node. To access a node, see [Connect to Azure Kubernetes Service (AKS) cluster nodes][node-access].

+## Before you begin

+For help with setting up the *live data* feature, see [Configure live data in Container Insights][configure-live-data]. This feature directly accesses the Kubernetes API. For more information about the authentication model, see [Kubernetes API][kubernetes-api].

+## View AKS resource live logs

+> [!NOTE]

+> To access logs from a private cluster, you need to be on a machine on the same private network as the cluster.

+1. In the [Azure portal][azure-portal], navigate to your AKS cluster.

+2. Under **Kubernetes resources**, select **Workloads**.

+3. Select the *Deployment*, *Pod*, *Replica Set*, *Stateful Set*, *Job* or *Cron Job* that you want to view logs for, and then select **Live Logs**.

+4. Select the resource you want to view logs for.

+ The following example shows the logs for a *Pod* resource:

+ :::image type="content" source="./media/container-insights-live-data/live-data-deployment.png" alt-text="Screenshot that shows the deployment of live logs." lightbox="./media/container-insights-live-data/live-data-deployment.png":::

+## View live logs

+You can view real time log data as it's generated by the container engine on the *Cluster*, *Nodes*, *Controllers*, or *Containers*.

+1. In the [Azure portal][azure-portal], navigate to your AKS cluster.

+2. Under **Monitoring**, select **Insights**.

+3. Select the *Cluster*, *Nodes*, *Controllers*, or *Containers* tab, and then select the object you want to view logs for.

+4. On the resource **Overview**, select **Live Logs**.

+ > [!NOTE]

+ > To view the data from your Log Analytics workspace, select **View Logs in Log Analytics**. To learn more about viewing historical logs, events, and metrics, see [How to query logs from Container Insights][log-query].

+ After successful authentication, if data can be retrieved, it begins streaming to the Live Logs tab. You can view log data here in a continuous stream. The following image shows the logs for a *Container* resource:

+ :::image type="content" source="./media/container-insights-live-data/container-live-logs.png" alt-text="Screenshot that shows the container Live Logs view data option." lightbox="./media/container-insights-live-data/container-live-logs.png":::

+## View live events

+You can view real-time event data as it's generated by the container engine on the *Cluster*, *Nodes*, *Controllers*, or *Containers*.

+1. In the [Azure portal][azure-portal], navigate to your AKS cluster.

+2. Under **Monitoring**, select **Insights**.

+3. Select the *Cluster*, *Nodes*, *Controllers*, or *Containers* tab, and then select the object you want to view events for.

+4. On the resource **Overview** page, select **Live Events**.

+ > [!NOTE]

+ > To view the data from your Log Analytics workspace, select **View Events in Log Analytics**. To learn more about viewing historical logs, events, and metrics, see [How to query logs from Container Insights][log-query].

+ After successful authentication, if data can be retrieved, it begins streaming to the Live Events tab. The following image shows the events for a *Container* resource:

+ :::image type="content" source="./media/container-insights-live-data/container-live-events.png" alt-text="Screenshot that shows the container Live Events view data option." lightbox="./media/container-insights-live-data/container-live-events.png":::

+## View metrics

+You can view real-time metrics data as it's generated by the container engine on the *Nodes* or *Controllers* by selecting a *Pod* resource.

+1. In the [Azure portal][azure-portal], navigate to your AKS cluster.

+2. Under **Monitoring**, select **Insights**.

+3. Select the *Nodes* or *Controllers* tab, and then select the *Pod* object you want to view metrics for.

+4. On the resource **Overview** page, select **Live Metrics**.

+ > [!NOTE]

+ > To view the data from your Log Analytics workspace, select **View Events in Log Analytics**. To learn more about viewing historical logs, events, and metrics, see [How to query logs from Container Insights][log-query].

+ After successful authentication, if data can be retrieved, it begins streaming to the Live Metrics tab. The following image shows the metrics for a *Pod* resource:

+ :::image type="content" source="./media/container-insights-live-data/pod-live-metrics.png" alt-text="Screenshot that shows the pod Live Metrics view data option." lightbox="./media/container-insights-live-data/pod-live-metrics.png":::

+## Next steps

+For more information about monitoring on AKS, see the following articles:

+* [Azure Kubernetes Service (AKS) diagnose and solve problems][aks-diagnose-solve-problems]

+* [Monitor Kubernetes events for troubleshooting][aks-monitor-events]

+<!-- LINKS -->

+[kubernetes-cluster-architecture]: https://kubernetes.io/docs/concepts/cluster-administration/logging/#cluster-level-logging-architectures

+[node-access]: ./node-access.md

+[configure-live-data]: ../azure-monitor/containers/container-insights-livedata-setup.md

+[kubernetes-api]: https://kubernetes.io/docs/concepts/overview/kubernetes-api/

+[azure-portal]: https://portal.azure.com/

+[log-query]: ../azure-monitor/containers/container-insights-log-query.md

+[aks-diagnose-solve-problems]: ./aks-diagnostics.md

+[aks-monitor-events]: ./events.md

+ Title: Monitor Azure Kubernetes Service (AKS) control plane metrics (preview)

+#CustomerIntent: As a platform engineer, I want to collect metrics from the control plane and monitor them for any potential issues.

+This article shows you how to use the control plane metrics (preview) feature in Azure Kubernetes Service (AKS) to collect metrics from the control plane and view the telemetry in Azure Monitor. The control plane metrics feature is fully compatible with Prometheus and Grafana and provides more visibility into the availability and performance of the control plane components, such as the API server, ETCD, Scheduler, Autoscaler, and controller manager. You can use these metrics to maximize overall observability and maintain operational excellence for your AKS cluster.

+- Control plane metrics (preview) only supports [Azure Monitor managed service for Prometheus][managed-prometheus-overview].

+- You can only customize the default [ama-metrics-settings-config-map](../azure-monitor/containers/prometheus-metrics-scrape-configuration.md#configmaps). All other customizations aren't supported.

+- The AKS cluster must use [managed identity authentication](use-managed-identity.md).

+- Install or update the `aks-preview` Azure CLI extension using the [`az extension add`][az-extension-add] or [`az extension update`][az-extension-update] command.

+ ```azurecli-interactive

+ # Install the aks-preview extension

+ az extension add --name aks-preview

+

+ # Update the aks-preview extension

+ az extension update --name aks-preview

+ ```

+### Register the `AzureMonitorMetricsControlPlanePreview` feature flag

+1. Register the `AzureMonitorMetricsControlPlanePreview` feature flag using the [`az feature register`][az-feature-register] command.

+ ```azurecli-interactive

+ az feature register --namespace "Microsoft.ContainerService" --name "AzureMonitorMetricsControlPlanePreview"

+ ```

+ It takes a few minutes for the status to show *Registered*.

+2. Verify the registration status using the [`az feature show`][az-feature-show] command.

+ ```azurecli-interactive

+ az feature show --namespace "Microsoft.ContainerService" --name "AzureMonitorMetricsControlPlanePreview"

+ ```

+3. When the status reflects *Registered*, refresh the registration of the *Microsoft.ContainerService* resource provider using the [`az provider register`][az-provider-register] command.

+ ```azurecli-interactive

+ az provider register --namespace "Microsoft.ContainerService"

+ ```

+You can enable control plane metrics with the Azure Monitor managed service for Prometheus add-on when creating a new cluster or updating an existing cluster.

+## Enable control plane metrics on a new AKS cluster

+To collect Prometheus metrics from your Kubernetes cluster, see [Enable Prometheus and Grafana for AKS clusters][enable-monitoring-kubernetes-cluster] and follow the steps on the **CLI** tab for an AKS cluster.

+## Enable control plane metrics on an existing AKS cluster

+- If your cluster already has the Prometheus add-on, update the cluster to ensure it starts collecting control plane metrics using the [`az aks update`][az-aks-update] command.

+ ```azurecli-interactive

+ az aks update --name $CLUSTER_NAME --resource-group $RESOURCE_GROUP

+ ```

+> Unlike the metrics collected from cluster nodes, control plane metrics are collected by a component which isn't part of the **ama-metrics** add-on. Enabling the `AzureMonitorMetricsControlPlanePreview` feature flag and the managed Prometheus add-on ensures control plane metrics are collected. After enabling metric collection, it can take several minutes for the data to appear in the workspace.

+## Query control plane metrics

+Control plane metrics are stored in an Azure Monitor workspace in the cluster's region. You can query the metrics directly from the workspace or through the Azure managed Grafana instance connected to the workspace.

+View the control plane metrics in the Azure Monitor workspace using the following steps:

+1. In the [Azure portal][azure-portal], navigate to your AKS cluster.

+2. Under **Monitoring**, select **Insights**.

+ :::image type="content" source="media/monitor-control-plane-metrics/insights-azmon.png" alt-text="Screenshot of Azure Monitor workspace." lightbox="media/monitor-control-plane-metrics/insights-azmon.png":::

+> [!NOTE]

+> AKS provides dashboard templates to help you view and analyze your control plane telemetry data in real-time. If you're using Azure managed Grafana to visualize the data, you can import the following dashboards:

+>

+> - [API server][grafana-dashboard-template-api-server]

+> - [ETCD][grafana-dashboard-template-etcd]

+AKS includes a preconfigured set of metrics to collect and store for each component. `API server` and `etcd` are enabled by default. You can customize this list through the [`ama-settings-configmap`][ama-metrics-settings-configmap].

+The default targets include the following:

+All ConfigMaps should be applied to the `kube-system` namespace for any cluster.

+For more information about `minimal-ingestion` profile metrics, see [Minimal ingestion profile for control plane metrics in managed Prometheus][list-of-default-metrics-aks-control-plane].

+### Ingest only minimal metrics from default targets

+When setting `default-targets-metrics-keep-list.minimalIngestionProfile="true"`, only the minimal set of metrics are ingested for each of the default targets: `controlplane-apiserver` and `controlplane-etcd`.

+Collect all metrics from all targets on the cluster using the following steps:

+2. Set `minimalingestionprofile = false`.

+3. Under `default-scrape-settings-enabled`, verify that the targets you want to scrape are set to `true`. The only targets you can specify are: `controlplane-apiserver`, `controlplane-cluster-autoscaler`, `controlplane-kube-scheduler`, `controlplane-kube-controller-manager`, and `controlplane-etcd`.

+4. Apply the ConfigMap using the [`kubectl apply`][kubectl-apply] command.

+The `minimal ingestion profile` setting helps reduce the ingestion volume of metrics, as it only collects metrics used by default dashboards, default recording rules, and default alerts are collected. To customize this setting, use the following steps:

+2. Set `minimalingestionprofile = true`.

+3. Under `default-scrape-settings-enabled`, verify that the targets you want to scrape are set to `true`. The only targets you can specify are: `controlplane-apiserver`, `controlplane-cluster-autoscaler`, `controlplane-kube-scheduler`, `controlplane-kube-controller-manager`, and `controlplane-etcd`.

+4. Under `default-targets-metrics-keep-list`, specify the list of metrics for the `true` targets. For example:

+5. Apply the ConfigMap using the [`kubectl apply`][kubectl-apply] command.

+2. Set `minimalingestionprofile = false`.

+3. Under `default-scrape-settings-enabled`, verify that the targets you want to scrape are set to `true`. The only targets you can specify here are `controlplane-apiserver`, `controlplane-cluster-autoscaler`, `controlplane-kube-scheduler`,`controlplane-kube-controller-manager`, and `controlplane-etcd`.

+4. Under `default-targets-metrics-keep-list`, specify the list of metrics for the `true` targets. For example:

+5. Apply the ConfigMap using the [`kubectl apply`][kubectl-apply] command.

+Make sure the feature flag `AzureMonitorMetricsControlPlanePreview` is enabled and the `ama-metrics` pods are running.

+> The [troubleshooting methods][prometheus-troubleshooting] for Azure managed service Prometheus don't directly translate here, as the components scraping the control plane aren't present in the managed Prometheus add-on.

+### ConfigMap formatting

+Make sure you're using proper formatting in the ConfigMap and that the fields, specifically `default-targets-metrics-keep-list`, `minimal-ingestion-profile`, and `default-scrape-settings-enabled`, are correctly populated with their intended values.

+### Isolate control plane from data plane

+Once you applied the changes, you can open metrics explorer from the **Azure Monitor overview** page or from the **Monitoring** section the selected cluster and check for an increase or decrease in the number of events ingested per minute. It should help you determine if a specific metric is missing or if all metrics are missing.

+### Specific metric isn't exposed

+There have been cases where metrics are documented, but aren't exposed from the target and aren't forwarded to the Azure Monitor workspace. In this case, it's necessary to verify other metrics are being forwarded to the workspace.

+When you enable the add-on, you might have specified an existing workspace that you don't have access to. In that case, it might look like the metrics aren't being collected and forwarded. Make sure that you create a new workspace while enabling the add-on or while creating the cluster.

+You can disable control plane metrics at any time by disabling the managed Prometheus add-on and unregistering the `AzureMonitorMetricsControlPlanePreview` feature flag.

+1. Remove the metrics add-on that scrapes Prometheus metrics using the [`az aks update`][az-aks-update] command.

+ ```azurecli-interactive

+ az aks update --disable-azure-monitor-metrics --name $CLUSTER_NAME --resource-group $RESOURCE_GROUP

+ ```

+2. Disable scraping of control plane metrics on the AKS cluster by unregistering the `AzureMonitorMetricsControlPlanePreview` feature flag using the [`az feature unregister`][az-feature-unregister] command.

+ ```azurecli-interactive

+ az feature unregister "Microsoft.ContainerService" --name "AzureMonitorMetricsControlPlanePreview"

+ ```

+## FAQ

+### Can I scrape control plane metrics with self hosted Prometheus?

+No, you currently can't scrape control plane metrics with self hosted Prometheus. Self hosted Prometheus can only scrape the single instance depending on the load balancer. The metrics aren't reliable, as there are often multiple replicas of the control plane metrics are only visible through managed Prometheus

+### Why is the user agent not available through the control plane metrics?

+[Control plane metrics in Kubernetes](https://kubernetes.io/docs/reference/instrumentation/metrics/) don't have the user agent. The user agent is only available through the control plane logs available in the [diagnostic settings](../azure-monitor/essentials/diagnostic-settings.md).

+To learn more about AKS control plane metrics, see the [list of default metrics for AKS control plane][list-of-default-metrics-aks-control-plane].

+[azure-portal]: https://portal.azure.com

+[az-aks-update]: /cli/azure/aks#az-aks-update

+ Title: Use the Vertical Pod Autoscaler in Azure Kubernetes Service (AKS)

+description: Learn how to deploy, upgrade, or disable the Vertical Pod Autoscaler on your Azure Kubernetes Service (AKS) cluster.

+# Use the Vertical Pod Autoscaler in Azure Kubernetes Service (AKS)

+This article shows you how to use the Vertical Pod Autoscaler (VPA) on your Azure Kubernetes Service (AKS) cluster. The VPA automatically adjusts the CPU and memory requests for your pods to match the usage patterns of your workloads. This feature helps to optimize the performance of your applications and reduce the cost of running your workloads in AKS.

+For more information, see the [Vertical Pod Autoscaler overview](./vertical-pod-autoscaler.md).

+## Before you begin

+* If you have an existing AKS cluster, make sure it's running Kubernetes version 1.24 or higher.

+* You need the Azure CLI version 2.52.0 or later installed and configured. Run `az --version` to find the version. If you need to install or upgrade, see [Install Azure CLI][install-azure-cli].

+* If enabling VPA on an existing cluster, make sure `kubectl` is installed and configured to connect to your AKS cluster using the [`az aks get-credentials`][az-aks-get-credentials] command.

+ ```azurecli-interactive

+ az aks get-credentials --name <cluster-name> --resource-group <resource-group-name>

+ ```

+## Deploy the Vertical Pod Autoscaler on a new cluster

+* Create a new AKS cluster with the VPA enabled using the [`az aks create`][az-aks-create] command with the `--enable-vpa` flag.

+ ```azurecli-interactive

+ az aks create --name <cluster-name> --resource-group <resource-group-name> --enable-vpa --generate-ssh-keys

+ ```

+ After a few minutes, the command completes and returns JSON-formatted information about the cluster.

+## Update an existing cluster to use the Vertical Pod Autoscaler

+* Update an existing cluster to use the VPA using the [`az aks update`][az-aks-update] command with the `--enable-vpa` flag.

+ ```azurecli-interactive

+ az aks update --name <cluster-name> --resource-group <resource-group-name> --enable-vpa

+ ```

+ After a few minutes, the command completes and returns JSON-formatted information about the cluster.

+## Disable the Vertical Pod Autoscaler on an existing cluster

+* Disable the VPA on an existing cluster using the [`az aks update`][az-aks-update] command with the `--disable-vpa` flag.

+ ```azurecli-interactive

+ az aks update --name <cluster-name> --resource-group <resource-group-name> --disable-vpa

+ ```

+ After a few minutes, the command completes and returns JSON-formatted information about the cluster.

+## Test Vertical Pod Autoscaler installation

+In the following example, we create a deployment with two pods, each running a single container that requests 100 millicore and tries to utilize slightly above 500 millicores. We also create a VPA config pointing at the deployment. The VPA observes the behavior of the pods, and after about five minutes, updates the pods to request 500 millicores.

+1. Create a file named `hamster.yaml` and copy in the following manifest of the Vertical Pod Autoscaler example from the [kubernetes/autoscaler][kubernetes-autoscaler-github-repo] GitHub repository:

+ ```yml

+ apiVersion: "autoscaling.k8s.io/v1"

+ kind: VerticalPodAutoscaler

+ metadata:

+ name: hamster-vpa

+ spec:

+ targetRef:

+ apiVersion: "apps/v1"

+ kind: Deployment

+ name: hamster

+ resourcePolicy:

+ containerPolicies:

+ - containerName: '*'

+ minAllowed:

+ cpu: 100m

+ memory: 50Mi

+ maxAllowed:

+ cpu: 1

+ memory: 500Mi

+ controlledResources: ["cpu", "memory"]

+

+ apiVersion: apps/v1

+ kind: Deployment

+ metadata:

+ name: hamster

+ spec:

+ selector:

+ matchLabels:

+ app: hamster

+ replicas: 2

+ template:

+ metadata:

+ labels:

+ app: hamster

+ spec:

+ securityContext:

+ runAsNonRoot: true

+ runAsUser: 65534

+ containers:

+ - name: hamster

+ image: registry.k8s.io/ubuntu-slim:0.1

+ resources:

+ requests:

+ cpu: 100m

+ memory: 50Mi

+ command: ["/bin/sh"]

+ args:

+ - "-c"

+ - "while true; do timeout 0.5s yes >; sleep 0.5s; done"

+ ```

+2. Deploy the `hamster.yaml` Vertical Pod Autoscaler example using the [`kubectl apply`][kubectl-apply] command.

+ ```bash

+ kubectl apply -f hamster.yaml

+ ```

+ After a few minutes, the command completes and returns JSON-formatted information about the cluster.

+3. View the running pods using the [`kubectl get`][kubectl-get] command.

+ ```bash

+ kubectl get pods -l app=hamster

+ ```

+ Your output should look similar to the following example output:

+ ```output

+ hamster-78f9dcdd4c-hf7gk 1/1 Running 0 24s

+ hamster-78f9dcdd4c-j9mc7 1/1 Running 0 24s

+ ```

+4. View the CPU and Memory reservations on one of the pods using the [`kubectl describe`][kubectl-describe] command. Make sure you replace `<example-pod>` with one of the pod IDs returned in your output from the previous step.

+ ```bash

+ kubectl describe pod hamster-<example-pod>

+ ```

+ Your output should look similar to the following example output:

+ ```output

+ hamster:

+ Container ID: containerd://

+ Image: k8s.gcr.io/ubuntu-slim:0.1

+ Image ID: sha256:

+ Port: <none>

+ Host Port: <none>

+ Command:

+ /bin/sh

+ Args:

+ -c

+ while true; do timeout 0.5s yes >; sleep 0.5s; done

+ State: Running

+ Started: Wed, 28 Sep 2022 15:06:14 -0400

+ Ready: True

+ Restart Count: 0

+ Requests:

+ cpu: 100m

+ memory: 50Mi

+ Environment: <none>

+ ```

+ The pod has 100 millicpu and 50 Mibibytes of Memory reserved in this example. For this sample application, the pod needs less than 100 millicpu to run, so there's no CPU capacity available. The pods also reserves less memory than needed. The Vertical Pod Autoscaler *vpa-recommender* deployment analyzes the pods hosting the hamster application to see if the CPU and Memory requirements are appropriate. If adjustments are needed, the vpa-updater relaunches the pods with updated values.

+5. Monitor the pods using the [`kubectl get`][kubectl-get] command.

+ ```bash

+ kubectl get --watch pods -l app=hamster

+ ```

+6. When the new hamster pod starts, you can view the updated CPU and Memory reservations using the [`kubectl describe`][kubectl-describe] command. Make sure you replace `<example-pod>` with one of the pod IDs returned in your output from the previous step.

+ ```bash

+ kubectl describe pod hamster-<example-pod>

+ ```

+ Your output should look similar to the following example output:

+ ```output

+ State: Running

+ Started: Wed, 28 Sep 2022 15:09:51 -0400

+ Ready: True

+ Restart Count: 0

+ Requests:

+ cpu: 587m

+ memory: 262144k

+ Environment: <none>

+ ```

+ In the previous output, you can see that the CPU reservation increased to 587 millicpu, which is over five times the original value. The Memory increased to 262,144 Kilobytes, which is around 250 Mibibytes, or five times the original value. This pod was under-resourced, and the Vertical Pod Autoscaler corrected the estimate with a much more appropriate value.

+7. View updated recommendations from VPA using the [`kubectl describe`][kubectl-describe] command to describe the hamster-vpa resource information.

+ ```bash

+ kubectl describe vpa/hamster-vpa

+ ```

+ Your output should look similar to the following example output:

+ ```output

+ State: Running

+ Started: Wed, 28 Sep 2022 15:09:51 -0400

+ Ready: True

+ Restart Count: 0

+ Requests:

+ cpu: 587m

+ memory: 262144k

+ Environment: <none>

+ ```

+## Set Vertical Pod Autoscaler requests

+The `VerticalPodAutoscaler` object automatically sets resource requests on pods with an `updateMode` of `Auto`. You can set a different value depending on your requirements and testing. In this example, we create and test a deployment manifest with two pods, each running a container that requests 100 milliCPU and 50 MiB of Memory, and sets the `updateMode` to `Recreate`.

+1. Create a file named `azure-autodeploy.yaml` and copy in the following manifest:

+ ```yml

+ apiVersion: apps/v1

+ kind: Deployment

+ metadata:

+ name: vpa-auto-deployment

+ spec:

+ replicas: 2

+ selector:

+ matchLabels:

+ app: vpa-auto-deployment

+ template:

+ metadata:

+ labels:

+ app: vpa-auto-deployment

+ spec:

+ containers:

+ - name: mycontainer

+ image: mcr.microsoft.com/oss/nginx/nginx:1.15.5-alpine

+ resources:

+ requests:

+ cpu: 100m

+ memory: 50Mi

+ command: ["/bin/sh"]

+ args: ["-c", "while true; do timeout 0.5s yes >; sleep 0.5s; done"]

+ ```

+2. Create the pod using the [`kubectl create`][kubectl-create] command.

+ ```bash

+ kubectl create -f azure-autodeploy.yaml

+ ```

+ After a few minutes, the command completes and returns JSON-formatted information about the cluster.

+3. View the running pods using the [`kubectl get`][kubectl-get] command.

+ ```bash

+ kubectl get pods

+ ```

+ Your output should look similar to the following example output:

+ ```output

+ NAME READY STATUS RESTARTS AGE

+ vpa-auto-deployment-54465fb978-kchc5 1/1 Running 0 52s

+ vpa-auto-deployment-54465fb978-nhtmj 1/1 Running 0 52s

+ ```

+4. Create a file named `azure-vpa-auto.yaml` and copy in the following manifest:

+ ```yml

+ apiVersion: autoscaling.k8s.io/v1

+ kind: VerticalPodAutoscaler

+ metadata:

+ name: vpa-auto

+ spec:

+ targetRef:

+ apiVersion: "apps/v1"

+ kind: Deployment

+ name: vpa-auto-deployment

+ updatePolicy:

+ updateMode: "Recreate"

+ ```

+ The `targetRef.name` value specifies that any pod controlled by a deployment named `vpa-auto-deployment` belongs to `VerticalPodAutoscaler`. The `updateMode` value of `Recreate` means that the Vertical Pod Autoscaler controller can delete a pod, adjust the CPU and Memory requests, and then create a new pod.

+5. Apply the manifest to the cluster using the [`kubectl apply`][kubectl-apply] command.

+ ```bash

+ kubectl create -f azure-vpa-auto.yaml

+ ```

+6. Wait a few minutes and then view the running pods using the [`kubectl get`][kubectl-get] command.

+ ```bash

+ kubectl get pods

+ ```

+ Your output should look similar to the following example output:

+ ```output

+ NAME READY STATUS RESTARTS AGE

+ vpa-auto-deployment-54465fb978-qbhc4 1/1 Running 0 2m49s

+ vpa-auto-deployment-54465fb978-vbj68 1/1 Running 0 109s

+ ```

+7. Get detailed information about one of your running pods using the [`kubectl get`][kubectl-get] command. Make sure you replace `<pod-name>` with the name of one of your pods from your previous output.

+ ```bash

+ kubectl get pod <pod-name> --output yaml

+ ```

+ Your output should look similar to the following example output, which shows that VPA controller increased the Memory request to 262144k and the CPU request to 25 milliCPU:

+ ```output

+ apiVersion: v1

+ kind: Pod

+ metadata:

+ annotations:

+ vpaObservedContainers: mycontainer

+ vpaUpdates: 'Pod resources updated by vpa-auto: container 0: cpu request, memory

+ request'

+ creationTimestamp: "2022-09-29T16:44:37Z"

+ generateName: vpa-auto-deployment-54465fb978-

+ labels:

+ app: vpa-auto-deployment

+ spec:

+ containers:

+ - args:

+ - -c

+ - while true; do timeout 0.5s yes >; sleep 0.5s; done

+ command:

+ - /bin/sh

+ image: mcr.microsoft.com/oss/nginx/nginx:1.15.5-alpine

+ imagePullPolicy: IfNotPresent

+ name: mycontainer

+ resources:

+ requests:

+ cpu: 25m

+ memory: 262144k

+ ```

+8. Get detailed information about the Vertical Pod Autoscaler and its recommendations for CPU and Memory using the [`kubectl get`][kubectl-get] command.

+ ```bash

+ kubectl get vpa vpa-auto --output yaml

+ ```

+ Your output should look similar to the following example output:

+ ```output

+ recommendation:

+ containerRecommendations:

+ - containerName: mycontainer

+ lowerBound:

+ cpu: 25m

+ memory: 262144k

+ target:

+ cpu: 25m

+ memory: 262144k

+ uncappedTarget:

+ cpu: 25m

+ memory: 262144k

+ upperBound:

+ cpu: 230m

+ memory: 262144k

+ ```

+ In this example, the results in the `target` attribute specify that it doesn't need to change the CPU or the Memory target for the container to run optimally. However, results can vary depending on the application and its resource utilization.

+ The Vertical Pod Autoscaler uses the `lowerBound` and `upperBound` attributes to decide whether to delete a pod and replace it with a new pod. If a pod has requests less than the lower bound or greater than the upper bound, the Vertical Pod Autoscaler deletes the pod and replaces it with a pod that meets the target attribute.

+## Extra Recommender for Vertical Pod Autoscaler

+The Recommender provides recommendations for resource usage based on real-time resource consumption. AKS deploys a Recommender when a cluster enables VPA. You can deploy a customized Recommender or an extra Recommender with the same image as the default one. The benefit of having a customized Recommender is that you can customize your recommendation logic. With an extra Recommender, you can partition VPAs to use different Recommenders.

+In the following example, we create an extra Recommender, apply to an existing AKS clust, and configure the VPA object to use the extra Recommender.

+1. Create a file named `extra_recommender.yaml` and copy in the following manifest:

+ ```yml

+ apiVersion: apps/v1

+ kind: Deployment

+ metadata:

+ name: extra-recommender

+ namespace: kube-system

+ spec:

+ replicas: 1

+ selector:

+ matchLabels:

+ app: extra-recommender

+ template:

+ metadata:

+ labels:

+ app: extra-recommender

+ spec:

+ serviceAccountName: vpa-recommender

+ securityContext:

+ runAsNonRoot: true

+ runAsUser: 65534

+ containers:

+ - name: recommender

+ image: registry.k8s.io/autoscaling/vpa-recommender:0.13.0

+ imagePullPolicy: Always

+ args:

+ - --recommender-name=extra-recommender

+ resources:

+ limits:

+ cpu: 200m

+ memory: 1000Mi

+ requests:

+ cpu: 50m

+ memory: 500Mi

+ ports:

+ - name: prometheus

+ containerPort: 8942

+ ```

+2. Deploy the `extra-recomender.yaml` Vertical Pod Autoscaler example using the [`kubectl apply`][kubectl-apply] command.

+ ```bash

+ kubectl apply -f extra-recommender.yaml

+ ```

+ After a few minutes, the command completes and returns JSON-formatted information about the cluster.

+3. Create a file named `hamster-extra-recommender.yaml` and copy in the following manifest:

+ ```yml

+ apiVersion: "autoscaling.k8s.io/v1"

+ kind: VerticalPodAutoscaler

+ metadata:

+ name: hamster-vpa

+ spec:

+ recommenders:

+ - name: 'extra-recommender'

+ targetRef:

+ apiVersion: "apps/v1"

+ kind: Deployment

+ name: hamster

+ updatePolicy:

+ updateMode: "Auto"

+ resourcePolicy:

+ containerPolicies:

+ - containerName: '*'

+ minAllowed:

+ cpu: 100m

+ memory: 50Mi

+ maxAllowed:

+ cpu: 1

+ memory: 500Mi

+ controlledResources: ["cpu", "memory"]

+

+ apiVersion: apps/v1

+ kind: Deployment

+ metadata:

+ name: hamster

+ spec:

+ selector:

+ matchLabels:

+ app: hamster

+ replicas: 2

+ template:

+ metadata:

+ labels:

+ app: hamster

+ spec:

+ securityContext:

+ runAsNonRoot: true

+ runAsUser: 65534 # nobody

+ containers:

+ - name: hamster

+ image: k8s.gcr.io/ubuntu-slim:0.1

+ resources:

+ requests:

+ cpu: 100m

+ memory: 50Mi

+ command: ["/bin/sh"]

+ args:

+ - "-c"

+ - "while true; do timeout 0.5s yes >; sleep 0.5s; done"

+ ```

+ If `memory` isn't specified in `controlledResources`, the Recommender doesn't respond to OOM events. In this example, we only set CPU in `controlledValues`. `controlledValues` allows you to choose whether to update the container's resource requests using the`RequestsOnly` option, or by both resource requests and limits using the `RequestsAndLimits` option. The default value is `RequestsAndLimits`. If you use the `RequestsAndLimits` option, requests are computed based on actual usage, and limits are calculated based on the current pod's request and limit ratio.

+ For example, if you start with a pod that requests 2 CPUs and limits to 4 CPUs, VPA always sets the limit to be twice as much as requests. The same principle applies to Memory. When you use the `RequestsAndLimits` mode, it can serve as a blueprint for your initial application resource requests and limits.

+ You can simplify the VPA object using `Auto` mode and computing recommendations for both CPU and Memory.

+4. Deploy the `hamster-extra-recomender.yaml` example using the [`kubectl apply`][kubectl-apply] command.

+ ```bash

+ kubectl apply -f hamster-extra-recommender.yaml

+ ```

+5. Monitor your pods using the `[kubectl get`][kubectl-get] command.

+ ```bash

+ kubectl get --watch pods -l app=hamster

+ ````

+6. When the new hamster pod starts, view the updated CPU and Memory reservations using the [`kubectl describe`][kubectl-describe] command. Make sure you replace `<example-pod>` with one of your pod IDs.

+ ```bash

+ kubectl describe pod hamster-<example-pod>

+ ```

+ Your output should look similar to the following example output:

+ ```output

+ State: Running

+ Started: Wed, 28 Sep 2022 15:09:51 -0400

+ Ready: True

+ Restart Count: 0

+ Requests:

+ cpu: 587m

+ memory: 262144k

+ Environment: <none>

+ ```

+7. View updated recommendations from VPA using the [`kubectl describe`][kubectl-describe] command.

+ ```bash

+ kubectl describe vpa/hamster-vpa

+ ```

+ Your output should look similar to the following example output:

+ ```output

+ State: Running

+ Started: Wed, 28 Sep 2022 15:09:51 -0400

+ Ready: True

+ Restart Count: 0

+ Requests:

+ cpu: 587m

+ memory: 262144k

+ Environment: <none>

+ Spec:

+ recommenders:

+ Name: customized-recommender

+ ```

+## Troubleshoot the Vertical Pod Autoscaler

+If you encounter issues with the Vertical Pod Autoscaler, you can troubleshoot the system components and custom resource definition to identify the problem.

+1. Verify that all system components are running using the following command:

+ ```bash

+ kubectl --namespace=kube-system get pods|grep vpa

+ ```

+ Your output should list *three pods*: recommender, updater, and admission-controller, all with a status of `Running`.

+2. For each of the pods returned in your previous output, verify that the system components are logging any errors using the following command:

+ ```bash

+ kubectl --namespace=kube-system logs [pod name] | grep -e '^E[0-9]\{4\}'

+ ```

+3. Verify that the custom resource definition was created using the following command:

+ ```bash

+ kubectl get customresourcedefinition | grep verticalpodautoscalers

+ ```

+## Next steps

+To learn more about the VPA object, see the [Vertical Pod Autoscaler API reference](./vertical-pod-autoscaler-api-reference.md).

+<!-- EXTERNAL LINKS -->

+[kubernetes-autoscaler-github-repo]: https://github.com/kubernetes/autoscaler/blob/master/vertical-pod-autoscaler/examples/hamster.yaml

+[kubectl-apply]: https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#apply

+[kubectl-create]: https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#create

+[kubectl-get]: https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#get

+[kubectl-describe]: https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#describe

+<!-- INTERNAL LINKS -->

+[install-azure-cli]: /cli/azure/install-azure-cli

+[az-aks-create]: /cli/azure/aks#az-aks-create

+[az-aks-update]: /cli/azure/aks#az-aks-update

+[az-aks-get-credentials]: /cli/azure/aks#az-aks-get-credentials

+ Title: Vertical pod autoscaling in Azure Kubernetes Service (AKS)

+description: Learn about vertical pod autoscaling in Azure Kubernetes Service (AKS) using the Vertical Pod Autoscaler (VPA).

+# Vertical pod autoscaling in Azure Kubernetes Service (AKS)

+This article provides an overview of using the Vertical Pod Autoscaler (VPA) in Azure Kubernetes Service (AKS), which is based on the open source [Kubernetes](https://github.com/kubernetes/autoscaler/tree/master/vertical-pod-autoscaler) version.

+When configured, the VPA automatically sets resource requests and limits on containers per workload based on past usage. The VPA frees up CPU and Memory for other pods and helps ensure effective utilization of your AKS clusters. The Vertical Pod Autoscaler provides recommendations for resource usage over time. To manage sudden increases in resource usage, use the [Horizontal Pod Autoscaler][horizontal-pod-autoscaling], which scales the number of pod replicas as needed.

+The Vertical Pod Autoscaler offers the following benefits:

+* Analyzes and adjusts processor and memory resources to *right size* your applications. VPA isn't only responsible for scaling up, but also for scaling down based on their resource use over time.

+* A pod with a scaling mode set to *auto* or *recreate* is evicted if it needs to change its resource requests.

+* You can set CPU and memory constraints for individual containers by specifying a resource policy.

+* Ensures nodes have correct resources for pod scheduling.

+* Offers configurable logging of any adjustments made to processor or memory resources made.

+* Improves cluster resource utilization and frees up CPU and memory for other pods.

+## Limitations and considerations

+Consider the following limitations and considerations when using the Vertical Pod Autoscaler:

+* VPA supports a maximum of 1,000 pods associated with `VerticalPodAutoscaler` objects per cluster.

+* VPA might recommend more resources than available in the cluster, which prevents the pod from being assigned to a node and run due to insufficient resources. You can overcome this limitation by setting the *LimitRange* to the maximum available resources per namespace, which ensures pods don't ask for more resources than specified. You can also set maximum allowed resource recommendations per pod in a `VerticalPodAutoscaler` object. The VPA can't completely overcome an insufficient node resource issue. The limit range is fixed, but the node resource usage is changed dynamically.

+* We don't recommend using VPA with the [Horizontal Pod Autoscaler (HPA)][horizontal-pod-autoscaler-overview], which scales based on the same CPU and memory usage metrics.

+* The VPA Recommender only stores up to *eight days* of historical data.

+* VPA doesn't support JVM-based workloads due to limited visibility into actual memory usage of the workload.

+* VPA doesn't support running your own implementation of VPA alongside it. Having an extra or customized recommender is supported.

+* AKS Windows containers aren't supported.

+* **Recommender**: The Recommender monitors current and past resource consumption, including metric history, Out of Memory (OOM) events, and VPA deployment specs, and uses the information it gathers to provide recommended values for container CPU and Memory requests/limits.

+* **Updater**: The Updater monitors managed pods to ensure that their resource requests are set correctly. If not, it removes those pods so that their controllers can recreate them with the updated requests.

+* **VPA Admission Controller**: The VPA Admission Controller sets the correct resource requests on new pods either created or recreated by their controller based on the Updater's activity.

+The VPA Admission Controller is a binary that registers itself as a *Mutating Admission Webhook*. When a new pod is created, the VPA Admission Controller gets a request from the API server and evaluates if there's a matching VPA configuration or finds a corresponding one and uses the current recommendation to set resource requests in the pod.

+A standalone job, `overlay-vpa-cert-webhook-check`, runs outside of the VPA Admission Controller. The `overlay-vpa-cert-webhook-check` job creates and renews the certificates and registers the VPA Admission Controller as a `MutatingWebhookConfiguration`.

+A Vertical Pod Autoscaler resource, most commonly a *deployment*, is inserted for each controller that you want to have automatically computed resource requirements.

+There are four modes in which the VPA operates:

+* `Auto`: VPA assigns resource requests during pod creation and updates existing pods using the preferred update mechanism. `Auto`, which is equivalent to `Recreate`, is the default mode. Once restart-free, or *in-place*, updates of pod requests are available, it can be used as the preferred update mechanism by the `Auto` mode. With the `Auto` mode, VPA evicts a pod if it needs to change its resource requests. It might cause the pods to be restarted all at once, which can cause application inconsistencies. You can limit restarts and maintain consistency in this situation using a [PodDisruptionBudget][pod-disruption-budget].

+* `Recreate`: VPA assigns resource requests during pod creation and updates existing pods by evicting them when the requested resources differ significantly from the new recommendations (respecting the PodDisruptionBudget, if defined). You should only use this mode if you need to ensure that the pods are restarted whenever the resource request changes. Otherwise, we recommend using `Auto` mode, which takes advantage of restart-free updates once available.

+* `Initial`: VPA only assigns resource requests during pod creation. It doesn't update existing pods. This mode is useful for testing and understanding the VPA behavior without affecting the running pods.

+* `Off`: VPA doesn't automatically change the resource requirements of the pods. The recommendations are calculated and can be inspected in the VPA object.

+## Deployment pattern for application development

+If you're unfamiliar with VPA, we recommend the following deployment pattern during application development to identify its unique resource utilization characteristics, test VPA to verify it's functioning properly, and test alongside other Kubernetes components to optimize resource utilization of the cluster:

+1. Set `UpdateMode = "Off"` in your production cluster and run VPA in recommendation mode so you can test and gain familiarity with VPA. `UpdateMode = "Off"` can avoid introducing a misconfiguration that can cause an outage.

+2. Establish observability first by collecting actual resource utilization telemetry over a given period of time, which helps you understand the behavior and any signs of issues from container and pod resources influenced by the workloads running on them.

+3. Get familiar with the monitoring data to understand the performance characteristics. Based on this insight, set the desired requests/limits accordingly and then in the next deployment or upgrade.

+To learn how to set up the Vertical Pod Autoscaler on your AKS cluster, see [Use the Vertical Pod Autoscaler in AKS](./use-vertical-pod-autoscaler.md).

+- App Service Environment with a name that doesn't meet the character limits. The entire name, including the domain suffix, must be 64 characters or fewer. For example: *my-ase-name.appserviceenvironment.net* for ILB and *my-ase-name.p.azurewebsites.net* for ELB must be 64 characters or fewer. If you don't meet the character limit, you must migrate manually. The character limits specifically for the App Service Environment name are as follows:

+ - ILB App Service Environment name character limit: 36 characters

+ - ELB App Service Environment name character limit: 42 characters

+- App Service Environment with a name that doesn't meet the character limits. The entire name, including the domain suffix, must be 64 characters or fewer. For example: *my-ase-name.appserviceenvironment.net* for ILB and *my-ase-name.p.azurewebsites.net* for ELB must be 64 characters or fewer. If you don't meet the character limit, you must migrate manually. The character limits specifically for the App Service Environment name are as follows:

+ - ILB App Service Environment name character limit: 36 characters

+ - ELB App Service Environment name character limit: 42 characters

+Azure Arc-enabled Kubernetes is updated on an ongoing basis. To stay up to date with the most recent developments, this article provides you with information about recent releases of the [Azure Arc-enabled Kubernetes agents](conceptual-agent-overview.md).

+## Version 1.18.x (July 2024)

+- Fixed `logCollector` pod restarts

+- Updated to Microsoft Go v1.22.5

+- Other bug fixes

+## Version 1.17.x (June 2024)

+- Upgraded to use [Microsoft Go 1.22 to be FIPS compliant](https://github.com/microsoft/go/blob/microsoft/main/eng/doc/fips/README.md#tls-with-fips-compliant-settings)

+## Version 1.16.x (May 2024)

+- Migrated to use Microsoft Go w/ OpenSSL and fixed some vulnerabilities

+- The appliance VM must be on a General Availability version (1.0.15 or higher). If not, the Arc resource bridge VM needs to be redeployed. If you are using Arc-enabled VMware/AVS, then you have the option to [perform disaster recovery](../vmware-vsphere/recover-from-resource-bridge-deletion.md). If you are using Arc-enabled SCVMM, then follow this [disaster recovery guide](../system-center-virtual-machine-manager/disaster-recovery.md).

+description: This article describes the different management tasks that you'll typically perform during the lifecycle of the Azure Connected Machine agent.

+Links to the current and previous releases of the Windows agents are available below the heading of each [release note](agent-release-notes.md). If you're looking for an agent version that's more than six months old, check out the [release notes archive](agent-release-notes-archive.md).

+The Azure Connected Machine agent is updated regularly to address bug fixes, stability enhancements, and new functionality. [Azure Advisor](../../advisor/advisor-overview.md) identifies resources that aren't using the latest version of the machine agent and recommends that you upgrade to the latest version. It notifies you when you select the Azure Arc-enabled server by presenting a banner on the **Overview** page or when you access Advisor through the Azure portal.

+The Azure Connected Machine agent for Windows and Linux can be upgraded to the latest release manually or automatically depending on your requirements. Installing, upgrading, or uninstalling the Azure Connected Machine Agent doesn't require you to restart your server.

+The next time computers in your selected scope refresh their policy, they'll start to check for updates in both Windows Update and Microsoft Update.

+If the Setup Wizard discovers a previous version of the agent, it upgrades it automatically. When the upgrade completes, the Setup Wizard closes automatically.

+When you change the name of a Linux or Windows machine connected to Azure Arc-enabled servers, the new name isn't recognized automatically because the resource name in Azure is immutable. As with other Azure resources, you must delete the resource and re-create it in order to use the new name.

+ Disconnecting the machine from Azure Arc-enabled servers doesn't remove the Connected Machine agent, and you don't need to remove the agent as part of this process.

+Disconnecting the agent deletes the corresponding Azure resource for the server and clears the local state of the agent. To disconnect the agent, run the `azcmagent disconnect` command as an administrator on the server. You'll be prompted to sign in with an Azure account that has permission to delete the resource in your subscription. If the resource has already been deleted in Azure, pass an additional flag to clean up the local state: `azcmagent disconnect --force-local-only`.

+Both of the following methods remove the agent, but they don't remove the *C:\Program Files\AzureConnectedMachineAgent* folder on the machine.

+The proxy bypass feature doesn't require you to enter specific URLs to bypass. Instead, you provide the name of the service(s) that shouldn't use the proxy server. The location parameter refers to the Azure region of the Arc Server(s).

+## Alerting for Azure Arc-enabled server disconnection

+The Connected Machine agent [sends a regular heartbeat message](overview.md#agent-status) to the service every five minutes. If an Arc-enabled server stops sending heartbeats to Azure for longer than 15 minutes, it can mean that it's offline, the network connection has been blocked, or the agent isn't running. Develop a plan for how youΓÇÖll respond and investigate these incidents, including setting up [Resource Health alerts](../..//service-health/resource-health-alert-monitor-guide.md) to get notified when such incidents occur.

+>

+## Prerequisites

+1. The disaster recovery script must be run from the same folder where the config (.yaml) files are present. The config files are present on the machine used to run the script to deploy Arc resource bridge.

+1. The machine being used to run the script must have bidirectional connectivity to the Arc resource bridge VM on port 6443 (Kubernetes API server) and 22 (SSH), and outbound connectivity to the Arc resource bridge VM on port 443 (HTTPS).

+- [Open an Azure support request](../../azure-portal/supportability/how-to-create-azure-support-request.md).

+>[!IMPORTANT]

+>After the successful installation of Azure Arc Resource Bridge, it's recommended to retain a copy of the resource bridge config (.yaml) files in a secure place that facilitates easy retrieval. These files are needed later to run commands to perform management operations (e.g. [az arcappliance upgrade](/cli/azure/arcappliance/upgrade#az-arcappliance-upgrade-vmware)) on the resource bridge. You can find the three config files (.yaml files) in the same folder where you ran the onboarding script.

+When you bind to an [output type](#usage) that doesn't support streaming, such as `string`, or `Byte[]`, the runtime must load the entire blob into memory more than one time during processing. This can result in higher-than expected memory usage when processing blobs. When possible, use a stream-supporting type. Type support depends on the C# mode and extension version. For more information, see [Binding types](./functions-bindings-storage-blob.md#binding-types).

+resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = {

+| Column | Type | Description |

+- To create an activity log alert rule using PowerShell, use the [New-AzActivityLogAlert](/powershell/module/az.monitor/new-azactivitylogalert) cmdlet.

+This feature requires no special setup, other than [configuring your app to send telemetry](../app/usage.md).

+The telemetry is available in the `customEvents` table on the [Application Insights Logs tab](../logs/log-query-overview.md) or [usage experience](usage.md). Events might come from `trackEvent(..)` or the [Click Analytics Auto-collection plug-in](javascript-feature-extensions.md).

+In a web app, users are [identified by cookies](./usage.md#users-sessions-and-eventsanalyze-telemetry-from-three-perspectives) by default. A user might be counted more than once if they access your app from a different machine or browser, or if they delete cookies.

+* [Application dashboard](overview-dashboard.md): An at-a-glance assessment of your application's health and performance.

+* [Application map](app-map.md): A visual overview of application architecture and components' interactions.

+* [Live metrics](live-stream.md): A real-time analytics dashboard for insight into application activity and performance.

+* [Transaction search](transaction-search-and-diagnostics.md?tabs=transaction-search): Trace and diagnose transactions to identify issues and optimize performance.

+* [Availability view](availability-overview.md): Proactively monitor and test the availability and responsiveness of application endpoints.

+* [Failures view](failures-and-performance-views.md?tabs=failures-view): Identify and analyze failures in your application to minimize downtime.

+* [Performance view](failures-and-performance-views.md?tabs=performance-view): Review application performance metrics and potential bottlenecks.

+* [Alerts](../alerts/alerts-overview.md): Monitor a wide range of aspects of your application and trigger various actions.

+* [Metrics](../essentials/metrics-getting-started.md): Dive deep into metrics data to understand usage patterns and trends.

+* [Diagnostic settings](../essentials/diagnostic-settings.md): Configure streaming export of platform logs and metrics to the destination of your choice.

+* [Logs](../logs/log-analytics-overview.md): Retrieve, consolidate, and analyze all data collected into Azure Monitoring Logs.

+* [Workbooks](../visualize/workbooks-overview.md): Create interactive reports and dashboards that visualize application monitoring data.

+* [Users, sessions, and events](usage.md#users-sessions-and-eventsanalyze-telemetry-from-three-perspectives): Determine when, where, and how users interact with your web app.

+* [Funnels](usage.md#funnelsdiscover-how-customers-use-your-application): Analyze conversion rates to identify where users progress or drop off in the funnel.

+* [Flows](usage.md#user-flowsanalyze-user-navigation-patterns): Visualize user paths on your site to identify high engagement areas and exit points.

+* [Cohorts](usage.md#cohortsanalyze-a-specific-set-of-users-sessions-events-or-operations): Group users by shared characteristics to simplify trend identification, segmentation, and performance troubleshooting.

+* [Profiler](../profiler/profiler-overview.md): Capture, identify, and view performance traces for your application.

+* [Code optimizations](../insights/code-optimizations.md): Harness AI to create better and more efficient applications.

+* [Snapshot debugger](../snapshot-debugger/snapshot-debugger.md): Automatically collect debug snapshots when exceptions occur in .NET application

+- [Users, sessions, and events](usage.md)

+The preceding steps are enough to help you start collecting server-side telemetry. If your application has client-side components, follow the next steps to start collecting [usage telemetry](./usage.md) using JavaScript (Web) SDK Loader Script injection by configuration.

+* [Explore user flows](./usage.md#user-flowsanalyze-user-navigation-patterns) to understand how users move through your app.

+This article explains how geolocation lookup and IP address handling work in [Application Insights](app-insights-overview.md#application-insights-overview).

+By default, IP addresses are temporarily collected but not stored.

+When telemetry is sent to Azure, the IP address is used in a geolocation lookup. The result is used to populate the fields `client_City`, `client_StateOrProvince`, and `client_CountryOrRegion`. The address is then discarded, and `0.0.0.0` is written to the `client_IP` field.

+* **Server telemetry**: The Application Insights telemetry module temporarily collects the client IP address when the `X-Forwarded-For` header isn't set. When the incoming IP address list has more than one item, the last IP address is used to populate geolocation fields.

+This behavior is by design to help avoid unnecessary collection of personal data and IP address location information.

+When IP addresses aren't collected, city and other geolocation attributes also aren't collected.

+## Storage of IP address data

+> [!WARNING]

+> The default and our recommendation is to not collect IP addresses. If you override this behavior, verify the collection doesn't break any compliance requirements or local regulations.

+>

+> To learn more about handling personal data, see [Guidance for personal data](../logs/personal-data-mgmt.md).

+To enable IP collection and storage, the `DisableIpMasking` property of the Application Insights component must be set to `true`.

+Options to set this property include:

+- [ARM template](#arm-template)

+- [Portal](#portal)

+- [REST API](#rest-api)

+- [PowerShell](#powershell)

+ If you select and edit the template again, only the default template without the newly added property. If you aren't seeing IP address data and want to confirm that `"DisableIpMasking": true` is set, run the following PowerShell commands:

+ A list of properties is returned as a result. One of the properties should read `DisableIpMasking: true`. If you run the PowerShell commands before you deploy the new property with Azure Resource Manager, the property doesn't exist.

+```json

+The PowerShell `Update-AzApplicationInsights` cmdlet can disable IP masking with the `DisableIPMasking` parameter.

+For more information on the `Update-AzApplicationInsights` cmdlet, see [Update-AzApplicationInsights](/powershell/module/az.applicationinsights/update-azapplicationinsights)

+* Learn more about [personal data collection](../logs/personal-data-mgmt.md) in Azure Monitor.

+* Learn how to [set the user IP](opentelemetry-add-modify.md#set-the-user-ip) using OpenTelemetry.

+If you're using a HEART workbook with the Click Analytics plug-in, you don't need to set the authenticated user context to see telemetry data. For more information, see the [HEART workbook documentation](./usage.md#confirm-that-data-is-flowing).

+* [Confirm data is flowing](./javascript-sdk.md#confirm-data-is-flowing).

+* See the [documentation on utilizing HEART workbook](usage.md#heartfive-dimensions-of-customer-experience) for expanded product analytics.

+* See the [GitHub repository](https://github.com/microsoft/ApplicationInsights-JS/tree/master/extensions/applicationinsights-clickanalytics-js) and [npm Package](https://www.npmjs.com/package/@microsoft/applicationinsights-clickanalytics-js) for the Click Analytics Autocollection Plug-in.

+* Use [Events Analysis in the Usage experience](usage.md#users-sessions-and-eventsanalyze-telemetry-from-three-perspectives) to analyze top clicks and slice by available dimensions.

+* See [Log Analytics](../logs/log-analytics-tutorial.md#write-a-query) if you arenΓÇÖt familiar with the process of writing a query.

+* Build a [workbook](../visualize/workbooks-overview.md) or [export to Power BI](../logs/log-powerbi.md) to create custom visualizations of click data.

+* [Track usage](usage.md)

+* [Explore Application Insights usage experiences](usage.md)

+* [Monitor usage with Application Insights](./usage.md)

+activity.SetTag("client.address", "<IP Address>");

+* [Funnels](./usage.md#funnelsdiscover-how-customers-use-your-application)

+* [Retention](./usage.md#user-retention-analysis)

+* [User flows](./usage.md#user-flowsanalyze-user-navigation-patterns)

+* In the tutorial, you learned how to create custom dashboards. Now look at the rest of the Application Insights documentation, which also includes a case study.

+ Title: Usage analysis with Application Insights | Azure Monitor

+description: Understand your users and what they do with your application.

+# Usage analysis with Application Insights

+Which features of your web or mobile app are most popular? Do your users achieve their goals with your app? Do they drop out at particular points, and do they return later?

+[Application Insights](./app-insights-overview.md) is a powerful tool for monitoring the performance and usage of your applications. It provides insights into how users interact with your app, identifies areas for improvement, and helps you understand the impact of changes. With this knowledge, you can make data-driven decisions about your next development cycles.

+This article covers the following areas:

+* [Users, Sessions & Events](#users-sessions-and-eventsanalyze-telemetry-from-three-perspectives) - Track and analyze user interaction with your application, session trends, and specific events to gain insights into user behavior and app performance.

+* [Funnels](#funnelsdiscover-how-customers-use-your-application) - Understand how users progress through a series of steps in your application and where they might be dropping off.

+* [User Flows](#user-flowsanalyze-user-navigation-patterns) - Visualize user paths to identify the most common routes and pinpointing areas where users are most engaged users or may encounter issues.

+* [Cohorts](#cohortsanalyze-a-specific-set-of-users-sessions-events-or-operations) - Group users or events by common characteristics to analyze behavior patterns, feature usage, and the impact of changes over time.

+* [Impact Analysis](#impact-analysisdiscover-how-different-properties-influence-conversion-rates) - Analyze how application performance metrics, like load times, influence user experience and behavior, to help you to prioritize improvements.

+* [HEART](#heartfive-dimensions-of-customer-experience) - Utilize the HEART framework to measure and understand user Happiness, Engagement, Adoption, Retention, and Task success.

+## Send telemetry from your application

+To optimize your experience, consider integrating Application Insights into both your app server code and your webpages. This dual implementation enables telemetry collection from both the client and server components of your application.

+1. **Server code:** Install the appropriate module for your [ASP.NET](./asp-net.md), [Azure](./app-insights-overview.md), [Java](./opentelemetry-enable.md?tabs=java), [Node.js](./nodejs.md), or [other](./app-insights-overview.md#supported-languages) app.

+ If you don't want to install server code, [create an Application Insights resource](./create-workspace-resource.md).

+1. **Webpage code:** Use the JavaScript SDK to collect data from webpages, see [Get started with the JavaScript SDK](./javascript-sdk.md).

+ [!INCLUDE [azure-monitor-log-analytics-rebrand](~/reusable-content/ce-skilling/azure/includes/azure-monitor-instrumentation-key-deprecation.md)]

+ To learn more advanced configurations for monitoring websites, check out the [JavaScript SDK reference article](./javascript.md).

+1. **Mobile app code:** Use the App Center SDK to collect events from your app. Then send copies of these events to Application Insights for analysis by [following this guide](https://github.com/Microsoft/appcenter).

+1. **Get telemetry:** Run your project in debug mode for a few minutes. Then look for results in the **Overview** pane in Application Insights.

+ Publish your app to monitor your app's performance and find out what your users are doing with your app.

+## Users, Sessions, and Events - Analyze telemetry from three perspectives

+Three of the **Usage** panes use the same tool to slice and dice telemetry from your web app from three perspectives. By filtering and splitting the data, you can uncover insights about the relative use of different pages and features.

+* **Users tool**: How many people used your app and its features? Users are counted by using anonymous IDs stored in browser cookies. A single person using different browsers or machines will be counted as more than one user.

+* **Sessions tool**: How many sessions of user activity have included certain pages and features of your app? A session is reset after half an hour of user inactivity, or after 24 hours of continuous use.

+* **Events tool**: How often are certain pages and features of your app used? A page view is counted when a browser loads a page from your app, provided you've [instrumented it](./javascript.md).

+ A custom event represents one occurrence of something happening in your app. It's often a user interaction like a button selection or the completion of a task. You insert code in your app to [generate custom events](./api-custom-events-metrics.md#trackevent) or use the [Click Analytics](javascript-feature-extensions.md) extension.

+> [!NOTE]

+> For information on an alternatives to using [anonymous IDs](./data-model-complete.md#anonymous-user-id) and ensuring an accurate count, see the documentation for [authenticated IDs](./data-model-complete.md#authenticated-user-id).

+Clicking **View More Insights** displays the following information:

+* **Application Performance:** Sessions, Events, and a Performance evaluation related to users' perception of responsiveness.

+* **Properties:** Charts containing up to six user properties such as browser version, country or region, and operating system.

+* **Meet Your Users:** View timelines of user activity.

+### Explore usage demographics and statistics

+Find out when people use your web app, what pages they're most interested in, where your users are located, and what browsers and operating systems they use. Analyze business and usage telemetry by using Application Insights.

+* The **Users** report counts the numbers of unique users that access your pages within your chosen time periods. For web apps, users are counted by using cookies. If someone accesses your site with different browsers or client machines, or clears their cookies, they're counted more than once.

+* The **Sessions** report tabulates the number of user sessions that access your site. A session represents a period of activity initiated by a user and concludes with a period of inactivity exceeding half an hour.

+#### Query for certain users

+Explore different groups of users by adjusting the query options at the top of the Users pane:

+| Option | Description |

+|--|-|

+| During | Choose a time range. |

+| Show | Choose a cohort of users to analyze. |

+| Who used | Choose custom events, requests, and page views. |

+| Events | Choose multiple events, requests, and page views that will show users who did at least one, not necessarily all, of the selected options. |

+| By value x-axis | Choose how to categorize the data, either by time range or by another property, such as browser or city. |

+| Split By | Choose a property to use to split or segment the data. |

+| Add Filters | Limit the query to certain users, sessions, or events based on their properties, such as browser or city. |

+#### Meet your users

+The **Meet your users** section shows information about five sample users matched by the current query. Exploring the behaviors of individuals and in aggregate can provide insights about how people use your app.

+### User retention analysis

+The Application Insights retention feature provides valuable insights into user engagement by tracking the frequency and patterns of users returning to your app and their interactions with specific features. It enables you to compare user behaviors, such as the difference in return rates between users who win or lose a game, offering actionable data to enhance user experience and inform business strategies.

+By analyzing cohorts of users based on their actions within a given timeframe, you can identify which features drive repeat usage. This knowledge can help you:

+* Understand what specific features cause users to come back more than others.

+* Determine whether retention is a problem in your product.

+* Form hypotheses based on real user data to help you improve the user experience and your business strategy.

+You can use the retention controls on top to define specific events and time ranges to calculate retention. The graph in the middle gives a visual representation of the overall retention percentage by the time range specified. The graph on the bottom represents individual retention in a specific time period. This level of detail allows you to understand what your users are doing and what might affect returning users on a more detailed granularity.

+For more information about the Retention workbook, see the section below.

+#### The retention workbook

+To use the retention workbook in Application Insights, navigate to the **Workbooks** pane, select **Public Templates** at the top, and locate the **User Retention Analysis** workbook listed under the **Usage** category.

+**Workbook capabilities:**

+* By default, retention shows all users who did anything and then came back and did anything else over a defined period. You can select different combinations of events to narrow the focus on specific user activities.

+* To add one or more filters on properties, select **Add Filters**. For example, you can focus on users in a particular country or region.

+* The **Overall Retention** chart shows a summary of user retention across the selected time period.

+* The grid shows the number of users retained. Each row represents a cohort of users who performed any event in the time period shown. Each cell in the row shows how many of that cohort returned at least once in a later period. Some users might return in more than one period.

+* The insights cards show the top five initiating events and the top five returned events. This information gives users a better understanding of their retention report.

+ :::image type="content" source="./media/usage-retention/retention-2.png" alt-text="Screenshot that shows the Retention workbook showing the User returned after number of weeks chart." lightbox="./media/usage-retention/retention-2.png":::

+#### Use business events to track retention

+You should measure events that represent significant business activities to get the most useful retention analysis.

+For more information and example code, see the section below.

+### Track user interactions with custom events

+To understand user interactions in your app, insert code lines to log custom events. These events track various user actions, like button selections, or important business events, such as purchases or game victories.

+You can also use the [Click Analytics Autocollection plug-in](javascript-feature-extensions.md) to collect custom events.

+> [!TIP]

+> When you design each feature of your app, consider how you're going to measure its success with your users. Decide what business events you need to record, and code the tracking calls for those events into your app from the start.

+In some cases, page views can represent useful events, but it isn't true in general. A user can open a product page without buying the product.

+With specific business events, you can chart your users' progress through your site. You can find out their preferences for different options and where they drop out or have difficulties. With this knowledge, you can make informed decisions about the priorities in your development backlog.

+Events can be logged from the client side of the app:

+```javascript

+appInsights.trackEvent({name: "incrementCount"});

+```

+Or events can be logged from the server side:

+```csharp

+var tc = new Microsoft.ApplicationInsights.TelemetryClient();

+tc.TrackEvent("CreatedAccount", new Dictionary<string,string> {"AccountType":account.Type}, null);

+...

+tc.TrackEvent("AddedItemToCart", new Dictionary<string,string> {"Item":item.Name}, null);

+...

+tc.TrackEvent("CompletedPurchase");

+```

+You can attach property values to these events so that you can filter or split the events when you inspect them in the portal. A standard set of properties is also attached to each event, such as anonymous user ID, which allows you to trace the sequence of activities of an individual user.

+Learn more about [custom events](./api-custom-events-metrics.md#trackevent) and [properties](./api-custom-events-metrics.md#properties).

+#### Slice and dice events

+In the Users, Sessions, and Events tools, you can slice and dice custom events by user, event name, and properties.

+Whenever youΓÇÖre in any usage experience, select the **Open the last run query** icon to take you back to the underlying query.

+You can then modify the underlying query to get the kind of information youΓÇÖre looking for.

+HereΓÇÖs an example of an underlying query about page views. Go ahead and paste it directly into the query editor to test it out.

+```kusto

+// average pageView duration by name

+let timeGrain=5m;

+let dataset=pageViews

+// additional filters can be applied here

+| where timestamp > ago(1d)

+| where client_Type == "Browser" ;

+// calculate average pageView duration for all pageViews

+dataset

+| summarize avg(duration) by bin(timestamp, timeGrain)

+| extend pageView='Overall'

+// render result in a chart

+| render timechart

+```

+### Determine feature success with A/B testing

+If you're unsure which feature variant is more successful, release both and let different users access each variant. Measure the success of each variant, and then transition to a unified version.

+In this technique, you attach unique property values to all the telemetry sent by each version of your app. You can do it by defining properties in the active TelemetryContext. These default properties get included in every telemetry message sent by the application. It includes both custom messages and standard telemetry.

+In the Application Insights portal, filter and split your data on the property values so that you can compare the different versions.

+To do this step, [set up a telemetry initializer](./api-filtering-sampling.md#addmodify-properties-itelemetryinitializer):

+```csharp

+// Telemetry initializer class

+public class MyTelemetryInitializer : ITelemetryInitializer

+{

+ // In this example, to differentiate versions, we use the value specified in the AssemblyInfo.cs

+ // for ASP.NET apps, or in your project file (.csproj) for the ASP.NET Core apps. Make sure that

+ // you set a different assembly version when you deploy your application for A/B testing.

+ static readonly string _version =

+ System.Reflection.Assembly.GetExecutingAssembly().GetName().Version.ToString();

+

+ public void Initialize(ITelemetry item)

+ {

+ item.Context.Component.Version = _version;

+ }

+}

+```

+#### [.NET Core](#tab/aspnetcore)

+For [ASP.NET Core](asp-net-core.md#add-telemetryinitializers) applications, add a new telemetry initializer to the Dependency Injection service collection in the `Program.cs` class:

+```csharp

+using Microsoft.ApplicationInsights.Extensibility;

+builder.Services.AddSingleton<ITelemetryInitializer, MyTelemetryInitializer>();

+```

+#### [.NET Framework 4.8](#tab/aspnet-framework)

+In the web app initializer, such as `Global.asax.cs`:

+```csharp

+protected void Application_Start()

+{

+ // ...

+ TelemetryConfiguration.Active.TelemetryInitializers

+ .Add(new MyTelemetryInitializer());

+}

+```

+## Funnels - Discover how customers use your application

+Understanding the customer experience is of great importance to your business. If your application involves multiple stages, you need to know if customers are progressing through the entire process or ending the process at some point. The progression through a series of steps in a web application is known as a *funnel*. You can use Application Insights funnels to gain insights into your users and monitor step-by-step conversion rates.

+**Funnel features:**

+* If your app is sampled, you'll see a banner. Selecting it opens a context pane that explains how to turn off sampling.

+* Select a step to see more details on the right.

+* The historical conversion graph shows the conversion rates over the last 90 days.

+* Understand your users better by accessing the users tool. You can use filters in each step.

+### Create a funnel

+#### Prerequisites

+Before you create a funnel, decide on the question you want to answer. For example, you might want to know how many users view the home page, view a customer profile, and create a ticket.

+#### Get started

+To create a funnel:

+1. On the **Funnels** tab, select **Edit**.

+1. Choose your **Top Step**.

+ :::image type="content" source="./media/usage-funnels/funnel.png" alt-text="Screenshot that shows the Funnel tab and selecting steps on the Edit tab." lightbox="./media/usage-funnels/funnel.png":::

+1. To apply filters to the step, select **Add filters**. This option appears after you choose an item for the top step.

+1. Then choose your **Second Step** and so on.

+ > [!NOTE]

+ > Funnels are limited to a maximum of six steps.

+1. Select the **View** tab to see your funnel results.

+ :::image type="content" source="./media/usage-funnels/funnel-2.png" alt-text="Screenshot that shows the Funnels View tab that shows results from the top and second steps." lightbox="./media/usage-funnels/funnel-2.png":::

+1. To save your funnel to view at another time, select **Save** at the top. Use **Open** to open your saved funnels.

+## User Flows - Analyze user navigation patterns

+The User Flows tool visualizes how users move between the pages and features of your site. It's great for answering questions like:

+* How do users move away from a page on your site?

+* What do users select on a page on your site?

+* Where are the places that users churn most from your site?

+* Are there places where users repeat the same action over and over?

+The User Flows tool starts from an initial custom event, exception, dependency, page view or request that you specify. From this initial event, User Flows shows the events that happened before and after user sessions. Lines of varying thickness show how many times users followed each path. Special **Session Started** nodes show where the subsequent nodes began a session. **Session Ended** nodes show how many users sent no page views or custom events after the preceding node, highlighting where users probably left your site.

+> [!NOTE]

+> Your Application Insights resource must contain page views or custom events to use the User Flows tool. [Learn how to set up your app to collect page views automatically with the Application Insights JavaScript SDK](./javascript.md).

+### Choose an initial event

+To begin answering questions with the User Flows tool, choose an initial custom event, exception, dependency, page view or request to serve as the starting point for the visualization:

+1. Select the link in the **What do users do after?** title or select **Edit**.

+1. Select a custom event, exception, dependency, page view or request from the **Initial event** dropdown list.

+1. Select **Create graph**.

+The **Step 1** column of the visualization shows what users did most frequently after the initial event. The items are ordered from top to bottom and from most to least frequent. The **Step 2** and subsequent columns show what users did next. The information creates a picture of all the ways that users moved through your site.

+By default, the User Flows tool randomly samples only the last 24 hours of page views and custom events from your site. You can increase the time range and change the balance of performance and accuracy for random sampling on the **Edit** menu.

+If some of the page views, custom events, and exceptions aren't relevant to you, select **X** on the nodes you want to hide. After you've selected the nodes you want to hide, select **Create graph**. To see all the nodes you've hidden, select **Edit** and look at the **Excluded events** section.

+If page views or custom events you expect to see in the visualization are missing that:

+* Check the **Excluded events** section on the **Edit** menu.

+* Use the plus buttons on **Others** nodes to include less-frequent events in the visualization.

+* If the page view or custom event you expect is sent infrequently by users, increase the time range of the visualization on the **Edit** menu.

+* Make sure the custom event, exception, dependency, page view or request you expect is set up to be collected by the Application Insights SDK in the source code of your site.

+If you want to see more steps in the visualization, use the **Previous steps** and **Next steps** dropdown lists above the visualization.

+### After users visit a page or feature, where do they go and what do they select?

+If your initial event is a page view, the first column (**Step 1**) of the visualization is a quick way to understand what users did immediately after they visited the page.

+Open your site in a window next to the User Flows visualization. Compare your expectations of how users interact with the page to the list of events in the **Step 1** column. Often, a UI element on the page that seems insignificant to your team can be among the most used on the page. It can be a great starting point for design improvements to your site.

+If your initial event is a custom event, the first column shows what users did after they performed that action. As with page views, consider if the observed behavior of your users matches your team's goals and expectations.

+If your selected initial event is **Added Item to Shopping Cart**, for example, look to see if **Go to Checkout** and **Completed Purchase** appear in the visualization shortly thereafter. If user behavior is different from your expectations, use the visualization to understand how users are getting "trapped" by your site's current design.

+### Where are the places that users churn most from your site?

+Watch for **Session Ended** nodes that appear high up in a column in the visualization, especially early in a flow. This positioning means many users probably churned from your site after they followed the preceding path of pages and UI interactions.

+Sometimes churn is expected. For example, it's expected after a user makes a purchase on an e-commerce site. But usually churn is a sign of design problems, poor performance, or other issues with your site that can be improved.

+Keep in mind that **Session Ended** nodes are based only on telemetry collected by this Application Insights resource. If Application Insights doesn't receive telemetry for certain user interactions, users might have interacted with your site in those ways after the User Flows tool says the session ended.

+### Are there places where users repeat the same action over and over?

+Look for a page view or custom event that's repeated by many users across subsequent steps in the visualization. This activity usually means that users are performing repetitive actions on your site. If you find repetition, think about changing the design of your site or adding new functionality to reduce repetition. For example, you might add bulk edit functionality if you find users performing repetitive actions on each row of a table element.

+## Cohorts - Analyze a specific set of users, sessions, events, or operations

+A cohort is a set of users, sessions, events, or operations that have something in common. In Application Insights, cohorts are defined by an analytics query. In cases where you have to analyze a specific set of users or events repeatedly, cohorts can give you more flexibility to express exactly the set you're interested in.

+### Cohorts vs basic filters

+You can use cohorts in ways similar to filters. But cohorts' definitions are built from custom analytics queries, so they're much more adaptable and complex. Unlike filters, you can save cohorts so that other members of your team can reuse them.

+You might define a cohort of users who have all tried a new feature in your app. You can save this cohort in your Application Insights resource. It's easy to analyze this saved group of specific users in the future.

+> [!NOTE]

+> After cohorts are created, they're available from the Users, Sessions, Events, and User Flows tools.

+### Example: Engaged users

+Your team defines an engaged user as anyone who uses your app five or more times in a given month. In this section, you define a cohort of these engaged users.

+1. Select **Create a Cohort**.

+1. Select the **Template Gallery** tab to see a collection of templates for various cohorts.

+1. Select **Engaged Users -- by Days Used**.

+ There are three parameters for this cohort:

+ * **Activities**: Where you choose which events and page views count as usage.

+ * **Period**: The definition of a month.

+ * **UsedAtLeastCustom**: The number of times users need to use something within a period to count as engaged.

+1. Change **UsedAtLeastCustom** to **5+ days**. Leave **Period** set as the default of 28 days.

+ Now this cohort represents all user IDs sent with any custom event or page view on 5 separate days in the past 28 days.

+1. Select **Save**.

+ > [!TIP]

+ > Give your cohort a name, like *Engaged Users (5+ Days)*. Save it to *My reports* or *Shared reports*, depending on whether you want other people who have access to this Application Insights resource to see this cohort.

+1. Select **Back to Gallery**.

+#### What can you do by using this cohort?

+Open the Users tool. In the **Show** dropdown box, choose the cohort you created under **Users who belong to**.

+Important points to notice:

+* You can't create this set through normal filters. The date logic is more advanced.

+* You can further filter this cohort by using the normal filters in the Users tool. Although the cohort is defined on 28-day windows, you can still adjust the time range in the Users tool to be 30, 60, or 90 days.

+These filters support more sophisticated questions that are impossible to express through the query builder. An example is *people who were engaged in the past 28 days. How did those same people behave over the past 60 days?*

+### Example: Events cohort

+You can also make cohorts of events. In this section, you define a cohort of events and page views. Then you see how to use them from the other tools. This cohort might define a set of events that your team considers *active usage* or a set related to a certain new feature.

+1. Select **Create a Cohort**.

+1. Select the **Template Gallery** tab to see a collection of templates for various cohorts.

+1. Select **Events Picker**.

+1. In the **Activities** dropdown box, select the events you want to be in the cohort.

+1. Save the cohort and give it a name.

+### Example: Active users where you modify a query

+The previous two cohorts were defined by using dropdown boxes. You can also define cohorts by using analytics queries for total flexibility. To see how, create a cohort of users from the United Kingdom.

+1. Open the Cohorts tool, select the **Template Gallery** tab, and select **Blank Users cohort**.

+ :::image type="content" source="./media/usage-cohorts/cohort.png" alt-text="Screenshot that shows the template gallery for cohorts." lightbox="./media/usage-cohorts/cohort.png":::

+ There are three sections:

+ * **Markdown text**: Where you describe the cohort in more detail for other members on your team.

+ * **Parameters**: Where you make your own parameters, like **Activities**, and other dropdown boxes from the previous two examples.

+ * **Query**: Where you define the cohort by using an analytics query.

+ In the query section, you [write an analytics query](/azure/kusto/query). The query selects the certain set of rows that describe the cohort you want to define. The Cohorts tool then implicitly adds a `| summarize by user_Id` clause to the query. This data appears as a preview underneath the query in a table, so you can make sure your query is returning results.

+ > [!NOTE]

+ > If you don't see the query, resize the section to make it taller and reveal the query.

+1. Copy and paste the following text into the query editor:

+ ```KQL

+ union customEvents, pageViews

+ | where client_CountryOrRegion == "United Kingdom"

+ ```

+1. Select **Run Query**. If you don't see user IDs appear in the table, change to a country/region where your application has users.

+1. Save and name the cohort.

+## Impact Analysis - Discover how different properties influence conversion rates

+Impact Analysis discovers how any dimension of a page view, custom event, or request affects the usage of a different page view or custom event.

+One way to think of Impact is as the ultimate tool for settling arguments with someone on your team about how slowness in some aspect of your site is affecting whether users stick around. Users might tolerate some slowness, but Impact gives you insight into how best to balance optimization and performance to maximize user conversion.

+Analyzing performance is only a subset of Impact's capabilities. Impact supports custom events and dimensions, so you can easily answer questions like, How does user browser choice correlate with different rates of conversion?

+> [!NOTE]

+> Your Application Insights resource must contain page views or custom events to use the Impact analysis workbook. Learn how to [set up your app to collect page views automatically with the Application Insights JavaScript SDK](./javascript.md). Also, because you're analyzing correlation, sample size matters.

+### Impact analysis workbook

+To use the Impact analysis workbook, in your Application Insights resources go to **Usage** > **More** and select **User Impact Analysis Workbook**. Or on the **Workbooks** tab, select **Public Templates**. Then under **Usage**, select **User Impact Analysis**.

+#### Use the workbook

+1. From the **Selected event** dropdown list, select an event.

+1. From the **analyze how its** dropdown list, select a metric.

+1. From the **Impacting event** dropdown list, select an event.

+1. To add a filter, use the **Add selected event filters** tab or the **Add impacting event filters** tab.

+### Is page load time affecting how many people convert on my page?

+To begin answering questions with the Impact workbook, choose an initial page view, custom event, or request.

+1. From the **Selected event** dropdown list, select an event.

+1. Leave the **analyze how its** dropdown list on the default selection of **Duration**. (In this context, **Duration** is an alias for **Page Load Time**.)

+1. From the **Impacting event** dropdown list, select a custom event. This event should correspond to a UI element on the page view you selected in step 1.

+ :::image type="content" source="./media/usage-impact/impact.png" alt-text="Screenshot that shows an example with the selected event as Home Page analyzed by duration." lightbox="./media/usage-impact/impact.png":::

+### What if I'm tracking page views or load times in custom ways?

+Impact supports both standard and custom properties and measurements. Use whatever you want. Instead of duration, use filters on the primary and secondary events to get more specific.

+### Do users from different countries or regions convert at different rates?

+1. From the **Selected event** dropdown list, select an event.

+1. From the **analyze how its** dropdown list, select **Country or region**.

+1. From the **Impacting event** dropdown list, select a custom event that corresponds to a UI element on the page view you chose in step 1.

+ :::image type="content" source="./media/usage-impact/regions.png" alt-text="Screenshot that shows an example with the selected event as GET analyzed by country and region." lightbox="./media/usage-impact/regions.png":::

+### How does the Impact analysis workbook calculate these conversion rates?

+Under the hood, the Impact analysis workbook relies on the [Pearson correlation coefficient](https://en.wikipedia.org/wiki/Pearson_correlation_coefficient). Results are computed between -1 and 1. The coefficient -1 represents a negative linear correlation and 1 represents a positive linear correlation.

+The basic breakdown of how Impact analysis works is listed here:

+* Let *A* = the main page view, custom event, or request you select in the **Selected event** dropdown list.

+* Let *B* = the secondary page view or custom event you select in the **impacts the usage of** dropdown list.

+Impact looks at a sample of all the sessions from users in the selected time range. For each session, it looks for each occurrence of *A*.

+Sessions are then broken into two different kinds of *subsessions* based on one of two conditions:

+* A converted subsession consists of a session ending with a *B* event and encompasses all *A* events that occur prior to *B*.

+* An unconverted subsession occurs when all *A*s occur without a terminal *B*.

+How Impact is ultimately calculated varies based on whether we're analyzing by metric or by dimension. For metrics, all *A*s in a subsession are averaged. For dimensions, the value of each *A* contributes *1/N* to the value assigned to *B*, where *N* is the number of *A*s in the subsession.

+## HEART - Five dimensions of customer experience

+This article describes how to enable and use the Heart Workbook on Azure Monitor. The HEART workbook is based on the HEART measurement framework, which was originally introduced by Google. Several Microsoft internal teams use HEART to deliver better software.

+### Overview

+HEART is an acronym that stands for happiness, engagement, adoption, retention, and task success. It helps product teams deliver better software by focusing on five dimensions of customer experience:

+* **Happiness**: Measure of user attitude

+* **Engagement**: Level of active user involvement

+* **Adoption**: Target audience penetration

+* **Retention**: Rate at which users return

+* **Task success**: Productivity empowerment

+These dimensions are measured independently, but they interact with each other.

+* Adoption, engagement, and retention form a user activity funnel. Only a portion of users who adopt the tool come back to use it.

+* Task success is the driver that progresses users down the funnel and moves them from adoption to retention.

+* Happiness is an outcome of the other dimensions and not a stand-alone measurement. Users who have progressed down the funnel and are showing a higher level of activity are ideally happier.

+### Get started

+#### Prerequisites

+* **Azure subscription**: [Create an Azure subscription for free](https://azure.microsoft.com/free/)

+* **Application Insights resource**: [Create an Application Insights resource](create-workspace-resource.md#create-a-workspace-based-resource)

+* **Click Analytics**: Set up the [Click Analytics Autocollection plug-in](javascript-feature-extensions.md).

+* **Specific attributes**: Instrument the following attributes to calculate HEART metrics.

+ | Source | Attribute | Description |

+ |-|-|--|

+ | customEvents | session_Id | Unique session identifier |

+ | customEvents | appName | Unique Application Insights app identifier |

+ | customEvents | itemType | Category of customEvents record |

+ | customEvents | timestamp | Datetime of event |

+ | customEvents | operation_Id | Correlate telemetry events |

+ | customEvents | user_Id | Unique user identifier |

+ | customEvents ┬╣ | parentId | Name of feature |

+ | customEvents ┬╣ | pageName | Name of page |

+ | customEvents ┬╣ | actionType | Category of Click Analytics record |

+ | pageViews | user_AuthenticatedId | Unique authenticated user identifier |

+ | pageViews | session_Id | Unique session identifier |

+ | pageViews | appName | Unique Application Insights app identifier |

+ | pageViews | timestamp | Datetime of event |

+ | pageViews | operation_Id | Correlate telemetry events |

+ | pageViews | user_Id | Unique user identifier |

+* If you're setting up the authenticated user context, instrument the below attributes:

+| Source | Attribute | Description |

+|--|-|--|

+| customEvents | user_AuthenticatedId | Unique authenticated user identifier |

+**Footnotes**

+┬╣: To emit these attributes, use the [Click Analytics Autocollection plug-in](javascript-feature-extensions.md) via npm.

+>[!TIP]

+> To understand how to effectively use the Click Analytics plug-in, see [Feature extensions for the Application Insights JavaScript SDK (Click Analytics)](javascript-feature-extensions.md#use-the-plug-in).

+#### Open the workbook

+You can find the workbook in the gallery under **Public Templates**. The workbook appears in the section **Product Analytics using the Click Analytics Plugin**.

+There are seven workbooks.

+You only have to interact with the main workbook, **HEART Analytics - All Sections**. This workbook contains the other six workbooks as tabs. You can also access the individual workbooks related to each tab through the gallery.

+#### Confirm that data is flowing

+To validate that data is flowing as expected to light up the metrics accurately, select the **Development Requirements** tab.

+> [!IMPORTANT]

+> Unless you [set the authenticated user context](./javascript-feature-extensions.md#optional-set-the-authenticated-user-context), you must select **Anonymous Users** from the **ConversionScope** dropdown to see telemetry data.

+If data isn't flowing as expected, this tab shows the specific attributes with issues.

+### Workbook structure

+The workbook shows metric trends for the HEART dimensions split over seven tabs. Each tab contains descriptions of the dimensions, the metrics contained within each dimension, and how to use them.

+The tabs are:

+* **Summary**: Summarizes usage funnel metrics for a high-level view of visits, interactions, and repeat usage.

+* **Adoption**: Helps you understand the penetration among the target audience, acquisition velocity, and total user base.

+* **Engagement**: Shows frequency, depth, and breadth of usage.

+* **Retention**: Shows repeat usage.

+* **Task success**: Enables understanding of user flows and their time distributions.

+* **Happiness**: We recommend using a survey tool to measure customer satisfaction score (CSAT) over a five-point scale. On this tab, we've provided the likelihood of happiness via usage and performance metrics.

+* **Feature metrics**: Enables understanding of HEART metrics at feature granularity.

+> [!WARNING]

+> The HEART workbook is currently built on logs and effectively are [log-based metrics](pre-aggregated-metrics-log-metrics.md). The accuracy of these metrics are negatively affected by sampling and filtering.

+### How HEART dimensions are defined and measured

+#### Happiness

+Happiness is a user-reported dimension that measures how users feel about the product offered to them.

+A common approach to measure happiness is to ask users a CSAT question like How satisfied are you with this product? Users' responses on a three- or a five-point scale (for example, *no, maybe,* and *yes*) are aggregated to create a product-level score that ranges from 1 to 5. Because user-initiated feedback tends to be negatively biased, HEART tracks happiness from surveys displayed to users at predefined intervals.

+Common happiness metrics include values such as **Average Star Rating** and **Customer Satisfaction Score**. Send these values to Azure Monitor by using one of the custom ingestion methods described in [Custom sources](../data-sources.md#custom-sources).

+#### Engagement

+Engagement is a measure of user activity. Specifically, user actions are intentional, such as clicks. Active usage can be broken down into three subdimensions:

+* **Activity frequency**: Measures how often a user interacts with the product. For example, users typically interact daily, weekly, or monthly.

+* **Activity breadth**: Measures the number of features users interact with over a specific time period. For example, users interacted with a total of five features in June 2021.

+* **Activity depth**: Measures the number of features users interact with each time they launch the product. For example, users interacted with two features on every launch.

+Measuring engagement can vary based on the type of product being used. For example, a product like Microsoft Teams is expected to have a high daily usage, which makes it an important metric to track. But for a product like a paycheck portal, measurement might make more sense at a monthly or weekly level.

+>[!IMPORTANT]

+>A user who performs an intentional action, such as clicking a button or typing an input, is counted as an active user. For this reason, engagement metrics require the [Click Analytics plug-in for Application Insights](javascript-feature-extensions.md) to be implemented in the application.

+#### Adoption

+Adoption enables understanding of penetration among the relevant users, who you're gaining as your user base, and how you're gaining them. Adoption metrics are useful for measuring:

+* Newly released products.

+* Newly updated products.

+* Marketing campaigns.

+#### Retention

+A retained user is a user who was active in a specified reporting period and its previous reporting period. Retention is typically measured with the following metrics.

+| Metric | Definition | Question answered |

+|-|-|-|

+| Retained users | Count of active users who were also active the previous period | How many users are staying engaged with the product? |

+| Retention | Proportion of active users from the previous period who are also active this period | What percent of users are staying engaged with the product? |

+>[!IMPORTANT]

+>Because active users must have at least one telemetry event with an action type, retention metrics require the [Click Analytics plug-in for Application Insights](javascript-feature-extensions.md) to be implemented in the application.

+#### Task success

+Task success tracks whether users can do a task efficiently and effectively by using the product's features. Many products include structures that are designed to funnel users through completing a task. Some examples include:

+* Adding items to a cart and then completing a purchase.

+* Searching a keyword and then selecting a result.

+* Starting a new account and then completing account registration.

+A successful task meets three requirements:

+* **Expected task flow**: The intended task flow of the feature was completed by the user and aligns with the expected task flow.

+* **High performance**: The intended functionality of the feature was accomplished in a reasonable amount of time.

+* **High reliability**: The intended functionality of the feature was accomplished without failure.

+A task is considered unsuccessful if any of the preceding requirements isn't met.

+>[!IMPORTANT]

+>Task success metrics require the [Click Analytics plug-in for Application Insights](javascript-feature-extensions.md) to be implemented in the application.

+Set up a custom task by using the following parameters.

+| Parameter | Description |

+|||

+| First step | The feature that starts the task. In the cart/purchase example, **Adding items to a cart** is the first step. |

+| Expected task duration | The time window to consider a completed task a success. Any tasks completed outside of this constraint are considered a failure. Not all tasks necessarily have a time constraint. For such tasks, select **No Time Expectation**. |

+| Last step | The feature that completes the task. In the cart/purchase example, **Purchasing items from the cart** is the last step. |

+## Frequently asked questions

+### Does the initial event represent the first time the event appears in a session or any time it appears in a session?

+The initial event on the visualization only represents the first time a user sent that page view or custom event during a session. If users can send the initial event multiple times in a session, then the **Step 1** column only shows how users behave after the *first* instance of an initial event, not all instances.

+### Some of the nodes in my visualization have a level that's too high. How can I get more detailed nodes?

+Use the **Split by** options on the **Edit** menu:

+1. Select the event you want to break down on the **Event** menu.

+1. Select a dimension on the **Dimension** menu. For example, if you have an event called **Button Clicked**, try a custom property called **Button Name**.

+### I defined a cohort of users from a certain country/region. When I compare this cohort in the Users tool to setting a filter on that country/region, why do I see different results?

+Cohorts and filters are different. Suppose you have a cohort of users from the United Kingdom (defined like the previous example), and you compare its results to setting the filter `Country or region = United Kingdom`:

+* The cohort version shows all events from users who sent one or more events from the United Kingdom in the current time range. If you split by country or region, you likely see many countries and regions.

+* The filters version only shows events from the United Kingdom. If you split by country or region, you see only the United Kingdom.

+### How do I view the data at different grains (daily, monthly, or weekly)?

+You can select the **Date Grain** filter to change the grain. The filter is available across all the dimension tabs.

+### How do I access insights from my application that aren't available on the HEART workbooks?

+You can dig into the data that feeds the HEART workbook if the visuals don't answer all your questions. To do this task, under the **Monitoring** section, select **Logs** and query the `customEvents` table. Some of the Click Analytics attributes are contained within the `customDimensions` field. A sample query is shown here.

+To learn more about Logs in Azure Monitor, see [Azure Monitor Logs overview](../logs/data-platform-logs.md).

+### Can I edit visuals in the workbook?

+Yes. When you select the public template of the workbook:

+1. Select **Edit** and make your changes.

+ :::image type="content" source="media/usage-overview/workbook-edit-faq.png" alt-text="Screenshot that shows the Edit button in the upper-left corner of the workbook template.":::

+1. After you make your changes, select **Done Editing**, and then select the **Save** icon.

+ :::image type="content" source="media/usage-overview/workbook-save-faq.png" alt-text="Screenshot that shows the Save icon at the top of the workbook template that becomes available after you make edits.":::

+1. To view your saved workbook, under **Monitoring**, go to the **Workbooks** section and then select the **Workbooks** tab. A copy of your customized workbook appears there. You can make any further changes you want in this copy.

+ :::image type="content" source="media/usage-overview/workbook-view-faq.png" alt-text="Screenshot that shows the Workbooks tab next to the Public Templates tab, where the edited copy of the workbook is located.":::

+For more on editing workbook templates, see [Azure Workbooks templates](../visualize/workbooks-templates.md).

+## Next steps

+* Check out the [GitHub repository](https://github.com/microsoft/ApplicationInsights-JS/tree/master/extensions/applicationinsights-clickanalytics-js) and [npm Package](https://www.npmjs.com/package/@microsoft/applicationinsights-clickanalytics-js) for the Click Analytics Autocollection plug-in.

+* Learn more about the [Google HEART framework](https://storage.googleapis.com/pub-tools-public-publication-data/pdf/36299.pdf).

+* To learn more about workbooks, see the [Workbooks overview](../visualize/workbooks-overview.md).

+|Geo|Regions|

+|||

+|Africa|South Africa North|

+|Asia Pacific|East Asia, Southeast Asia|

+|Australia|Australia Central, Australia East, Australia Southeast|

+|Brazil|Brazil South, Brazil Southeast|

+|Canada|Canada Central, Canada East|

+|Europe|North Europe, West Europe|

+|France|France Central, France South|

+|Germany|Germany West Central|

+|India|Central India, South India|

+|Israel|Israel Central|

+|Italy|Italy North|

+|Japan|Japan East, Japan West|

+|Korea|Korea Central, Korea South|

+|Norway|Norway East, Norway West|

+|Spain|Spain Central|

+|Sweden|Sweden South, Sweden Central|

+|Switzerland|Switzerland North, Switzerland West|

+|UAE|UAE North|

+|UK|UK South, UK West|

+|US|Central US, East US, East US 2, South Central US, West Central US, West US, West US 2, West US 3|

+|US Government|USGov Virginia, USGov Texas|

+|Logs|[Best practices for Azure Monitor Logs](best-practices-logs.md)|Dedicated clusters are now available in all commitment tiers, with a minimum daily ingestion of 100 GB.|

+Application-Insights|[Usage analysis with Application Insights](app/usage.md)|Code samples have been updated for the latest versions of .NET.|

+Application-Insights|[Analyze product usage with HEART](app/usage.md#heartfive-dimensions-of-customer-experience)|Updated and overhauled HEART framework documentation.|

+| Maximum size of a single capacity pool | 2,048 TiB | No |

+- Volumes contain a capacity of between 100 GiB and 100 TiB. You can create a [large volume](#large-volumes) with a size of between 50 TiB and 1 PiB.

+# Bicep core diagnostics

+If you need more information about a particular diagnostic code, select the **Feedback** button in the upper right corner of the page and specify the code.

+> [!NOTE]

+> You can't move Azure resources to another resource group or another subscription if there's a read-only lock, whether in the source or in the destination.

+ Title: SignalR Application Firewall (Preview)

+description: An introduction about why and how to set up Application Firewall for Azure SignalR service

+# Application Firewall for Azure SignalR Service

+The Application Firewall provides sophisticated control over client connections in a distributed system. Before diving into its functionality and setup, let's clarify what the Application Firewall does not do:

+1. It does not replace authentication. The firewall operates behind the client connection authentication layer.

+2. It is not related to network layer access control.

+## What Does the Application Firewall Do?

+The Application Firewall consists of various rule lists. Currently, there is a rule list called *Client Connection Count Rules*. Future updates will support more rule lists to control aspects like connection lifetime and message throughput.

+This guideline is divided into three parts:

+1. Introduction to different application firewall rules.

+2. Instructions on configuring the rules using the Portal or Bicep on the SignalR service side.

+3. Steps to configure the token on the server side.

+## Prerequisites

+* An Azure SignalR Service in [Premium tier](https://azure.microsoft.com/pricing/details/signalr-service/).

+## Client Connection Count Rules

+Client Connection Count Rules restrict concurrent client connections. When a client attempts to establish a new connection, the rules are checked **sequentially**. If any rule is violated, the connection is rejected with a status code 429.

+ #### ThrottleByUserIdRule

+ This rule limits the concurrent connections of a user. For example, if a user opens multiple browser tabs or logs in using different devices, you can use this rule to restrict the number of concurrent connections for that user.

+ > [!NOTE]

+ > * The **UserId** must exist in the access token for this rule to work. Refer to [Configure access token](#configure-access-token).

+

+ #### ThrottleByJwtSignatureRule

+ This rule limits the concurrent connections of the same token to prevent malicious users from reusing tokens to establish infinite connections, which can exhaust connection quota.

+ > [!NOTE]

+ > * It's not guaranteed by default that tokens generated by the SDK are different each time. Though each token contains a timestamp, this timestamp might be the same if vast tokens are generated within seconds. To avoid identical tokens, insert a random claim into the token claims. Refer to [Configure access token](#configure-access-token).

+ #### ThrottleByJwtCustomClaimRule

+ More advanced, connections could be grouped into different groups according to custom claim. Connections with the same claim are aggregated to do the check. For example, you could add a **ThrottleByJwtCustomClaimRule** to allow 5 concurrent connections with custom claim name *freeUser*.

+ > [!NOTE]

+ > * The rule applies to all claims with a certain claim name. The connection count aggregation is on the same claim (including claim name and claim value). The *ThrottleByUserIdRule* is a special case of this rule, applying to all connections with the userIdentity claim.

+

+> [!WARNING]

+> * **Avoid using too aggressive maxCount**. Client connections may close without completing the TCP handshake. SignalR service can't detect those "half-closed" connections immediately. The connection is taken as active until the heartbeat failure. Therefore, aggressive throttling strategies might unexpectedly throttle clients. A smoother approach is to **leave some buffer** for the connection count, for example: double the *maxCount*.

+## Set up Application Firewall

+# [Portal](#tab/Portal)

+To use Application Firewall, navigate to the SignalR **Application Firewall** blade on the Azure portal and click **Add** to add a rule.

+

+# [Bicep](#tab/Bicep)

+Use Visual Studio Code or your favorite editor to create a file with the following content and name it main.bicep:

+```bicep

+@description('The name for your SignalR service')

+param resourceName string = 'contoso'

+resource signalr 'Microsoft.SignalRService/signalr@2024-04-01-preview' = {

+ name: resourceName

+ properties: {

+ applicationFirewall:{

+ clientConnectionCountRules:[

+ // Add or remove rules as needed

+ {

+ // This rule will be skipped if no userId is set

+ type: 'ThrottleByUserIdRule'

+ maxCount: 5

+ }

+ {

+ type: 'ThrottleByJwtSignatureRule'

+ maxCount: 10

+ }

+ {

+ // This rule will be skipped if no freeUser claim is set

+ type: 'ThrottleByJwtCustomClaimRule'

+ maxCount: 10

+ claimName: 'freeUser'

+ }

+ {

+ // This rule will be skipped if no paidUser claim is set

+ type: 'ThrottleByJwtCustomClaimRule'

+ maxCount: 100

+ claimName: 'paidUser'

+ }

+ ]

+ }

+ }

+}

+```

+Deploy the Bicep file using Azure CLI

+ ```azurecli

+ az deployment group create --resource-group MyResourceGroup --template-file main.bicep

+ ```

+-

+## Configure access token

+The application firewall rules only take effect when the access token contains the corresponding claim. A rule is **skipped** if the connection does not have the corresponding claim.

+Below is an example to add userId or custom claim in the access token in **Default Mode**:

+```cs

+services.AddSignalR().AddAzureSignalR(options =>

+ {

+ // Add necessary claims according to your rules.

+ options.ClaimsProvider = context => new[]

+ {

+ // Add UserId: Used in ThrottleByUserIdRule

+ new Claim(ClaimTypes.NameIdentifier, context.Request.Query["username"]),

+ // Add unique claim: Ensure uniqueness when using ThrottleByJwtSignatureRule.

+ // The token name is not important. You could change it as you like.

+ new Claim("uniqueToken", Guid.NewGuid().ToString()),

+

+ // Cutom claim: Used in ThrottleByJwtCustomClaimRule

+ new Claim("<Custom Claim Name>", "<Custom Claim Value>"),

+ // Custom claim example

+ new Claim("freeUser", context.Request.Query["username"]),

+ };

+ });

+```

+The logic for **Serverless Mode** is similar.

+For more details, refer to [Client negotiation](signalr-concept-client-negotiation.md#what-can-you-do-during-negotiation) .

+ - **Problem type:** AVS Quota request

+ > [!NOTE]

+ > If the *Problem Type* is not is not visible from the short-list offered, select **None of the Above**. *AVS Quota requests* will be in the offered list of *Problem Types*.

+ Title: Web PubSub Application Firewall (Preview)

+description: An introduction about why and how to set up Application Firewall for Azure Web PubSub service

+# Application Firewall for Azure Web PubSub Service

+The Application Firewall provides sophisticated control over client connections in a distributed system. Before diving into its functionality and setup, let's clarify what the Application Firewall does not do:

+1. It does not replace authentication. The firewall operates behind the client connection authentication layer.

+2. It is not related to network layer access control.

+## What Does the Application Firewall Do?

+The Application Firewall consists of various rule lists. Currently, there is a rule list called *Client Connection Count Rules*. Future updates will support more rule lists to control aspects like connection lifetime and message throughput.

+This guideline is divided into three parts:

+1. Introduction to different application firewall rules.

+2. Instructions on configuring the rules using the Portal or Bicep on the Web PubSub service side.

+3. Steps to configure the token on the server side.

+## Prerequisites

+* A Web PubSub resource in [premium tier](https://azure.microsoft.com/pricing/details/web-pubsub/).

+## Client Connection Count Rules

+Client Connection Count Rules restrict concurrent client connections. When a client attempts to establish a new connection, the rules are checked **sequentially**. If any rule is violated, the connection is rejected with a status code 429.

+ #### ThrottleByUserIdRule

+ This rule limits the concurrent connections of a user. For example, if a user opens multiple browser tabs or logs in using different devices, you can use this rule to restrict the number of concurrent connections for that user.

+ > [!NOTE]

+ > * The UserId must exist in the access token for this rule to work. Refer to [Configure access token](#configure-access-token).

+

+ #### ThrottleByJwtSignatureRule

+ This rule limits the concurrent connections of the same token to prevent malicious users from reusing tokens to establish infinite connections, which can exhaust connection quota.

+ > [!NOTE]

+ > * It's not guaranteed by default that tokens generated by the SDK are different each time. Though each token contains a timestamp, this timestamp might be the same if vast tokens are generated within seconds. To avoid identical tokens, insert a random claim into the token claims. Refer to [Configure access token](#configure-access-token).

+> [!WARNING]

+> * **Avoid using too aggressive maxCount**. Client connections may close without completing the TCP handshake. SignalR service can't detect those "half-closed" connections immediately. The connection is taken as active until the heartbeat failure. Therefore, aggressive throttling strategies might unexpectedly throttle clients. A smoother approach is to **leave some buffer** for the connection count, for example: double the *maxCount*.

+## Set up Application Firewall

+# [Portal](#tab/Portal)

+To use Application Firewall, navigate to the Web PubSub **Application Firewall** blade on the Azure portal and click **Add** to add a rule.

+

+# [Bicep](#tab/Bicep)

+Use Visual Studio Code or your favorite editor to create a file with the following content and name it main.bicep:

+```bicep

+@description('The name for your Web PubSub service')

+param resourceName string = 'contoso'

+resource webpubsub 'Microsoft.SignalRService/webpubsub@2024-04-01-preview' = {

+ name: resourceName

+ properties: {

+ applicationFirewall:{

+ clientConnectionCountRules:[

+ // Add or remove rules as needed

+ {

+ // This rule will be skipped if no userId is set

+ type: 'ThrottleByUserIdRule'

+ maxCount: 5

+ }

+ {

+ type: 'ThrottleByJwtSignatureRule'

+ maxCount: 10

+ }

+ ]

+ }

+ }

+}

+```

+Deploy the Bicep file using Azure CLI

+ ```azurecli

+ az deployment group create --resource-group MyResourceGroup --template-file main.bicep

+ ```

+-

+## Configure access token

+The application firewall rules only take effect when the access token contains the corresponding claim. A rule is **skipped** if the connection does not have the corresponding claim. *userId" and *roles* are currently supported claims in the SDK.

+Below is an example to add userId and insert a unique placeholder in the access token:

+```cs

+// The GUID role wont have any effect. But it esures this token's uniqueness when using rule ThrottleByJwtSignatureRule.

+var url = service.GetClientAccessUri((userId: "user1" , roles: new string[] { "webpubsub.joinLeaveGroup.group1", Guid.NewGuid().ToString()});

+```

+For more details, refer to [Client negotiation](howto-generate-client-access-url.md#generate-from-service-sdk) .

+- In case you are trying to restore a backup stored in Vault Tier, you need to provide a storage account in input as a staging location. Backup data is stored in the Backup vault as a blob within the Microsoft tenant. During a restore operation, the backup data is copied from one vault to staging storage account across tenants. Ensure that the staging storage account for the restore has the **AllowCrossTenantReplication** property set to **true**.

+2. On the next page, select **Select backup instance**, and then select the *instance* that you want to restore.

+6. If you selected a recovery point for restore from *Vault-standard datastore*, then provide a *snapshot resource group* and *storage account* as the staging location.

+ Title: Troubleshoot Azure Backup Vault

+description: Symptoms, causes, and resolutions of the Azure Backup Vault related operations.

+# Troubleshoot Azure Backup Vault related operations

+This article provides troubleshooting steps that help you resolve Azure Backup Vault management errors.

+## Common user errors

+#### Error code: UserErrorSystemIdentityNotEnabledWithVault

+**Possible Cause:** Backup Vault is created with System Identity enabled by default. This error appears when System Identity of the Backup Vault is in a disabled state and a backup related operation fails with this error.

+**Resolution:** To resolve this error, enable the System Identity of the Backup Vault and reassign all the necessary roles to it. Else use a User Identity in its place with all the roles assigned and update Managed Identity for all the Backup Instances using the now disabled System Identity.

+#### Error code: UserErrorUserIdentityNotFoundOrNotAssociatedWithVault

+**Possible Cause:** Backup Instances can be created with a User Identity having all the required roles assigned to it. In addition, User Identity can also be used for operations like Encryption using a Customer Managed Key. This error appears when the particular User Identity is deleted or not attached with the Backup Vault.

+**Resolution:** To resolve this error, assign the same or alternate User Identity to the Backup Vault and update the Backup Instance to use the new identity in latter case. Otherwise, enable the System Identity of the Backup Vault, update the Backup Instance and assign all the necessary roles to it.

+## Next steps

+- [About Azure Backup Vault](create-manage-backup-vault.md)

+To configure backup with vaulted backup enabled, refer the below request body.

+#### Example request body for vaulted backup

+To configure a backup policy with the vaulted backup, use the following JSON script:

+You can now do the restore operation for *operational backup* and *vaulted backup* for Azure Blobs.

+# [Vaulted backup](#tab/vaulted-backup)

+## Prerequisites

+Backup data is stored in the Backup vault as a blob within the Microsoft tenant. During a restore operation, the backup data is copied from one storage account to another across tenants. Ensure that the target storage account for the restore has the **AllowCrossTenantReplication** property set to **true**.

+- [Back up the Azure Database for MySQL - Flexible Server (preview)](backup-azure-mysql-flexible-server.md)

+# Quickstart: Back up a storage account with Blob data using an ARM template

+# Quickstart: Back up a storage account with Blob data using Azure Backup via a Bicep template

+You can create a backup policy for *operational backup* and *vaulted backup* for Azure Blobs using Azure CLI.

+# [Vaulted backup](#tab/vaulted-backup)

+# [Vaulted Backup](#tab/vaulted-backup)

+# [Vaulted Backup](#tab/vaulted-backup)

+- Operational backup of blobs is a local backup solution that maintains data for a specified duration in the source storage account itself. This solution doesn't maintain an additional copy of data in the vault. This solution allows you to retain your data for restore for up to 360 days. Long retention durations can, however, lead to longer time taken during the restore operation.

+- The solution can be used to perform restores to the source storage account only and can result in data being overwritten.

+- If you delete a container from the storage account by calling the *Delete Container operation*, that container can't be restored with a restore operation. Rather than deleting an entire container, delete individual blobs if you want to restore them later. Also, Microsoft recommends enabling soft delete for containers, in addition to operational backup, to protect against accidental deletion of containers.

+1. In the storage account that needs to be protected, go to the **Access Control (IAM)** tab on the left navigation blade.

+1. In the Add role assignment blade:

+1. Go to the storage account for which you want to configure backup for blobs, and then go to **Data Protection** in left blade (under **Data management**).

+ 1. On selecting **Manage identity**, brings you to the Identity blade of the storage account.

+ 1. Select the cancel icon (**x**) on the top right corner to return to the **Data protection** blade of the storage account.<br><br>Once back, continue configuring backup.

+- In storage accounts (for which you've configured vaulted backups), the object replication rules get created under the **Object replication** item in the left blade.

+You can use Backup Center as your single blade of glass for managing all your backups. Regarding backup for Azure Blobs, you can use Backup Center to do the following:

+After stopping backup, you can disable other storage data protection capabilities (enabled for configuring backups) from the data protection blade of the storage account.

+ Title: Quickstart - Configure vaulted backup for Azure Blobs using Azure Backup

+description: In this quickstart, learn how to configure vaulted backup for Azure Blobs.

+# Quickstart: Configure vaulted backup for Azure Blobs using Azure Backup

+This quickstart describes how to create a backup policy and configure vaulted backup for Azure Blobs from the Azure portal.

+## Prerequisites

+Before you configure blob vaulted backup, ensure that:

+- You have a Backup vault to configure Azure Blob backup. If you haven't created the Backup vault, [create one](blob-backup-configure-manage.md?tabs=vaulted-backup#create-a-backup-vault).

+- You assign permissions to the Backup vault on the storage account. [Learn more](blob-backup-configure-manage.md?tabs=vaulted-backup#grant-permissions-to-the-backup-vault-on-storage-accounts).

+- You create a backup policy for Azure Blobs vaulted backup. [Learn more](blob-backup-configure-manage.md?tabs=vaulted-backup#create-a-backup-policy).

+## Before you start

+Things to remember before you start configuring blob vaulted backup:

+- Vaulted backup of blobs is a managed offsite backup solution that transfers data to the backup vault and retains as per the retention configured in the backup policy. You can retain data for a maximum of *10 years*.

+- Currently, you can use the vaulted backup solution to restore data to a different storage account only. While performing restores, ensure that the target storage account doesn't contain any *containers* with the same name as those backed up in a recovery point. If any conflicts arise due to the same name of containers, the restore operation fails.

+- Storage accounts to be backed up need to have *cross-tenant replication* enabled. To ensure if the checkbox for this setting is enabled, go to the **storage account** > **Object replication** > **Advanced settings**.

+For more information about the supported scenarios, limitations, and availability, see the [support matrix](blob-backup-support-matrix.md).

+## Next step

+[Restore Azure Blobs using Azure Backup](blob-restore.md)

+ Title: Tutorial - Configure vaulted backup for Azure Blobs using Azure Backup

+description: In this tutorial, learn how to configure vaulted backup for Azure Blobs.

+# Tutorial: Configure vaulted backup for Azure Blobs using Azure Backup

+This tutorial describes how to create a backup policy and configure vaulted backup for Azure Blobs from the Azure portal.

+## Prerequisites

+Before you configure blob vaulted backup, ensure that:

+- You have a Backup vault to configure Azure Blob backup. If you haven't created the Backup vault, [create one](blob-backup-configure-manage.md?tabs=vaulted-backup#create-a-backup-vault).

+- You assign permissions to the Backup vault on the storage account. [Learn more](blob-backup-configure-manage.md?tabs=vaulted-backup#grant-permissions-to-the-backup-vault-on-storage-accounts).

+## Before you start

+Things to remember before you start configuring blob vaulted backup:

+- Vaulted backup of blobs is a managed offsite backup solution that transfers data to the backup vault and retains as per the retention configured in the backup policy. You can retain data for a maximum of *10 years*.

+- Currently, you can use the vaulted backup solution to restore data to a different storage account only. While performing restores, ensure that the target storage account doesn't contain any *containers* with the same name as those backed up in a recovery point. If any conflicts arise due to the same name of containers, the restore operation fails.

+- Storage accounts to be backed up need to have *cross-tenant replication* enabled. To ensure if the checkbox for this setting is enabled, go to the **storage account** > **Object replication** > **Advanced settings**.

+For more information about the supported scenarios, limitations, and availability, see the [support matrix](blob-backup-support-matrix.md).

+## Next step

+[Restore Azure Blobs using Azure Backup](blob-restore.md).

+- **Periodic backups**: You can configure vaulted backup, a managed offsite data protection solution, to get protection against any accidental or malicious deletion of blobs or storage account. The backup data using vaulted backups is copied and stored in the Backup vault as per the schedule and frequency you define via the backup policy and retained as per the retention configured in the policy.

+# [Vaulted backup](#tab/vaulted-backup)

+Vaulted backup uses the platform capability of object replication to copy data to the Backup vault. Object replication asynchronously copies block blobs between a source storage account and a destination storage account. The contents of the blob, any versions associated with the blob, and the blob's metadata and properties are all copied from the source container to the destination container.

+# [Vaulted backup](#tab/vaulted-backup)

+Both operational and vaulted backups integrate directly with Backup Center to help you manage the protection of all your storage accounts centrally, along with all other Backup supported workloads. Backup Center is your single blade of glass for all your Backup requirements like monitoring jobs and state of backups and restores, ensuring compliance and governance, analyzing backup usage, and performing operations pertaining to back up and restore of data.

+# [Vaulted backup](#tab/vaulted-backup)

+You will incur backup storage charges or instance fees, and the source side cost ([associated with Object replication](../storage/blobs/object-replication-overview.md#billing)) on the backed-up source account.

+Vaulted backup for blobs is currently available in all public regions **except** South Africa West, Sweden Central, Sweden South, Israel Central, Poland Central, India Central, Italy North and Malaysia South.

+- The storage accounts to be backed up must contain *a minimum of one container*. If the storage account doesn't contain any containers or if no containers are selected, an error may appear when you configure backup.

+ Title: Quickstart - Configure vaulted backup for Azure Blobs using Azure CLI

+description: In this Quickstart, learn how to configure vaulted backup for Azure Blobs using Azure CLI.

+ms.devlang: azurecli

+# Quickstart: Configure vaulted backup for Azure Blobs using Azure Backup via Azure CLI

+This quickstart describes how to configure vaulted backup for Azure Blobs using Azure CLI.

+## Prerequisites

+Before you configure blob vaulted backup, ensure that:

+- You review the [support matrix](../backup/blob-backup-support-matrix.md) to learn about the Azure Blob region availability, supported scenarios, and limitations.

+- You have a Backup vault to configure Azure Blob backup. If you haven't created the Backup vault, [create one](../backup/backup-blobs-storage-account-ps.md#create-a-backup-vault).

+## Create a backup policy

+## Configure backup

+## Prepare the request to configure blob backup

+## Next step

+[Restore Azure Blobs using Azure CLI](/azure/backup/restore-blobs-storage-account-cli).

+ Title: Quickstart - Configure vaulted backup for Azure Blobs using Azure PowerShell

+description: In this Quickstart, learn how to configure vaulted backup for Azure Blobs using Azure PowerShell.

+ms.devlang: azurecli

+# Quickstart: Configure vaulted backup for Azure Blobs using Azure Backup via Azure PowerShell

+This quickstart describes how to configure vaulted backup for Azure Blobs using Azure PowerShell.

+## Prerequisites

+Before you configure blob vaulted backup, ensure that:

+- You install the Azure PowerShell version **Az 5.9.0**.

+- You review the [support matrix](../backup/blob-backup-support-matrix.md) to learn about the Azure Blob region availability, supported scenarios, and limitations.

+- You have a Backup vault to configure Azure Blob backup. If you haven't created the Backup vault, [create one](../backup/backup-blobs-storage-account-ps.md#create-a-backup-vault).

+## Create a backup policy

+## Configure backup

+## Prepare the request to configure blob backup

+## Next step

+[Restore Azure blobs using Azure PowerShell](/azure/backup/restore-blobs-storage-account-ps).

+1. Before you restore from Azure Database for PostgreSQL Flexible server backups, ensure that you have the required [permissions for the restore operation](backup-azure-database-postgresql-flex-overview.md#permissions-for-backup).

+2. Backup data is stored in the Backup vault as a blob within the Microsoft tenant. During a restore operation, the backup data is copied from one storage account to another across tenants. Ensure that the target storage account for the restore has the **AllowCrossTenantReplication** property set to **true**.

+1. Once the job is finished, the backed-up data is restored into the storage account. Below are the set of files recovered in your storage account after the restore:

+ - The first file is a marker or timestamp file that gives the customer the time the backup was taken at. The file cannot be restored but if opened with a text editor should tell the customer the UTC time when the backup was taken.

+

+ - The Second file **_database_** is an individual database backup for database called tempdata2 taken using pg_dump. Each database has a separate file with format **ΓÇô {backup_name}_database_{db_name}.sql**

+

+ - The Third File **_roles**. Has roles backed up using pg_dumpall

+

+ - The Fourth file **_schemas**. backed up using pg_dumpall

+

+ - The Fifth file **_tablespaces**. Has the tablespaces backed up using pg_dumpall

+1. Post restoration completion to the target storage account, you can use pg_restore utility to restore an Azure Database for PostgreSQL flexible server database from the target. Use the following command to connect to an existing postgresql flexible server and an existing database

+ `pg_restore -h <hostname> -U <username> -d <db name> -Fd -j <NUM> -C <dump directory>`

+ * `-Fd`: The directory format.

+ * `-j`: The number of jobs.

+ * `-C`: Begin the output with a command to create the database itself and then reconnect to it.

+ Here's an example of how this syntax might appear:

+ `pg_restore -h <hostname> -U <username> -j <Num of parallel jobs> -Fd -C -d <databasename> sampledb_dir_format`

+ If you have more than one database to restore, re-run the earlier command for each database.

+ Also, by using multiple concurrent jobs **-j**, you can reduce the time it takes to restore a large database on a multi-vCore target server. The number of jobs can be equal to or less than the number of vCPUs that are allocated for the target server.

+[Support matrix for PostgreSQL-Flex database backup by using Azure Backup](backup-azure-database-postgresql-flex-support-matrix.md).

+You can restore Azure Blobs to point-in-time using *operational backups* and *vaulted backups* for Azure Blobs via Azure CLI. Here, let's use an existing Backup vault `TestBkpVault`, under the resource group `testBkpVaultRG` in the examples.

+To restore a blob backup, you need to *fetch the valid time range for *operational backup* and *fetch the list of recovery points* for *vaulted backup*.

+# [Vaulted backup](#tab/vaulted-backup)

+To fetch the list of recovery points available to restore vaulted backup, use the `az dataprotection recovery-point list` command.

+# [Vaulted backup](#tab/vaulted-backup)

+Prepare the request body for the following restore scenarios supported by Azure Blobs vaulted backup.

+This article describes how to use the PowerShell to perform restores for Azure Blob from [operational](blob-backup-overview.md?tabs=operational-backup) or [vaulted](blob-backup-overview.md?tabs=vaulted-backup) backups. With operational backups, you can restore all block blobs in storage accounts with operational backup configured or a subset of blob content to any point-in-time within the retention range. With vaulted backups, you can perform restores using a recovery point created, based on your backup schedule.

+# [Vaulted backup](#tab/vaulted-backup)

+ Title: What's new in the Azure Backup service

+ - [Azure Blob vaulted backup is now generally available](#azure-blob-vaulted-backup-is-now-generally-available)

+## Azure Blob vaulted backup is now generally available

+Azure Backup now enables you to perform a vaulted backup of block blob data in *general-purpose v2 storage accounts* to protect data against ransomware attacks or source data loss due to malicious or rogue admin. You can define the backup schedule to create recovery points and the retention settings that determine how long backups will be retained in the vault. You can configure and manage the vaulted and operational backups using a single backup policy.

+Under vaulted backups, the data is copied and stored in the Backup vault. So, you get an offsite copy of data that can be retained for up to *10 years*. If any data loss happens on the source account, you can trigger a restore to an alternate account and get access to your data. The vaulted backups can be managed at scale via the Backup center, and monitored via the rich alerting and reporting capabilities offered by the Azure Backup service.

+If you're currently using operational backups, we recommend you to switch to vaulted backups for complete protection against different data loss scenarios.

+For more information, see [Azure Blob backup overview](blob-backup-overview.md?tabs=vaulted-backup).

+You can specify the virtual machine size of a role instance as part of the service model in the service definition file. The size of the role determines the number of CPU cores, memory capacity, and the local file system size.

+To retrieve a list of available sizes, see [Resource Skus - List](/rest/api/compute/resourceskus/list) and apply the following filters:

+1. Sign in to the [Azure portal](https://portal.azure.com) and navigate to the Key Vault. If you don't have a Key Vault set up, you can opt to create one in this same window.

+3. Ensure the access configuration includes the following property:

+A cloud service is created from three components, the service definition *(.csdef)*, the service config *(.cscfg)*, and a service package *(.cspkg)*. Both the **ServiceDefinition.csdef** and **ServiceConfig.cscfg** files are XML-based and describe the structure of the cloud service and its configuration. We collectively call these files the model. The **ServicePackage.cspkg** is a zip file that is generated from the **ServiceDefinition.csdef** and among other things, contains all the required binary-based dependencies. Azure creates a cloud service from both the **ServicePackage.cspkg** and the **ServiceConfig.cscfg**.

+Once the cloud service is running in Azure, you can reconfigure it through the **ServiceConfig.cscfg** file, but you can't alter the definition.

+You can refer to the [Service Definition Schema](schema-csdef-file.md)) for a better understanding of the XML schema used here, however, here's a quick explanation of some of the elements:

+The service configuration file isn't packaged with the application. It uploads to Azure as a separate file and is used to configure the cloud service. You can upload a new service configuration file without redeploying your cloud service. The configuration values for the cloud service can be changed while the cloud service is running. The following example shows the configuration settings that can be defined for the Web and Worker roles:

+You can refer to the [Service Configuration Schema](schema-cscfg-file.md) for better understanding the XML schema used here, however, here's a quick explanation of the elements:

+Configures the number of running instances for the role. To prevent your cloud service from potentially becoming unavailable during upgrades, we recommend you deploy more than one instance of your web-facing roles. By deploying more than one instance, you adhere to the guidelines in the [Azure Compute Service Level Agreement (SLA)](https://azure.microsoft.com/support/legal/sla/), which guarantees 99.95% external connectivity for Internet-facing roles when two or more role instances are deployed for a service.

+The following sample shows the configuration for a web role with a website and web application. The website is configured as the default entry location on port 80, and the web applications are configured to receive requests from an alternate host header called `mail.mysite.cloudapp.net`.

+You can update the configuration of your cloud service while it's running in Azure, without taking the service offline. To change configuration information, you can either upload a new configuration file, or edit the configuration file in place and apply it to your running service. The following changes can be made to the configuration of a service:

+ Topology changes don't affect running instances, except where an instance is being removed. All remaining instances generally don't need to be recycled; however, you can choose to recycle role instances in response to a topology change.

+ You can only update a certificate when a role instance is offline. If a certificate is added, deleted, or changed while a role instance is online, Azure gracefully takes the instance offline to update the certificate. Azure brings it back online after the change completes.

+| \[OutputFileName\] |The name for the generated package file. Typically, this variable is set to the name of the application. If no file name is specified, the application package is created as \[ApplicationName\].cspkg. |

+Conditions can be configured to enable Cloud Services (extended support) deployments to scale in and out. These conditions can be based on CPU usage, disk load, and network load.

+4. A page displays a list of all the roles in which scaling can be configured. Select the role you want to configure.

+ - **Manual scale** sets the absolute count of instances.

+ 4. The scaling operation begins immediately.

+ - **Custom Autoscale** allows you to set rules that govern how much or how little to scale.

+ 5. The scaling operations begin as soon as a rule is triggered.

+ - (Optional) You can assign a DNS name for your cloud service endpoint by updating the DNS label property of the public IP address associated with the cloud service.

+ - (Optional) **Start cloud service**: Select the checkbox if you want to start the service immediately after it deploys.

+To deploy Cloud Services (extended support), use any of the following PowerShell cmdlet options:

+ - The cmdlet creates the Cloud Services (extended support) role profile, network profile, and OS profile with minimal input.

+ - The cmdlet creates the cloud service role profile, network profile, and OS profile minimal input.

+1. Create an OS profile in-memory object. An OS profile specifies the certificates that are associated with Cloud Services (extended support) roles, which is the certificate that you created in the preceding step.

+1. Create a role profile in-memory object. A role profile defines a role's SKU-specific properties such as name, capacity, and tier. In this example, two roles are defined: frontendRole and backendRole. Role profile information must match the role configuration defined in the deployment configuration (.cscfg) file and definition (.csdef) file.

+Azure Key Vault stores certificates that are associated with Cloud Services (extended support). Add the certificates to a key vault, and then reference the certificate thumbprints in the configuration (.cscfg) file for your deployment. You also must enable the key vault access policy (in the portal) for **Azure Virtual Machines for deployment** so that the Cloud Services (extended support) resource can retrieve the certificate stored as secrets in the key vault. You can create a key vault in the [Azure portal](../key-vault/general/quick-create-portal.md) or by using [PowerShell](../key-vault/general/quick-create-powershell.md). You must create the key vault in the same region and subscription as the cloud service. For more information, see [Use certificates with Cloud Services (extended support)](certificates-and-key-vault.md).

+This article shows how to use the [Azure SDK](https://azure.microsoft.com/downloads/) to create an Azure Cloud Services (extended support) deployment that has multiple roles (WebRole and WorkerRole). It also covers how to use the Remote Desktop Protocol (RDP) extension. Cloud Services (extended support) is a deployment model of Azure Cloud Services based on Azure Resource Manager.

+1. Create a storage account and container where you store the package (.cspkg or .zip) file and configuration (.cscfg) file for the deployment. Install the [Azure Storage NuGet package](https://www.nuget.org/packages/Azure.Storage.Common/). This step is optional if you're using an existing storage account. The storage account name must be unique.

+ This example defines two roles: ContosoFrontend and ContosoBackend. Role profile information must match the role defined in the configuration (.cscfg) file and definition (.csdef) file.

+1. Create a Cloud Services (extended support) object. Add relevant `dependsOn` references if you deploy virtual networks or public IP addresses in your template.

+1. To create the Cloud Services (extended support) deployment, deploy the template and parameter file (to define parameters in the template file). You can use these [sample templates](https://github.com/Azure-Samples/cloud-services-extended-support).

+5. Input the desired conditions and required actions based on what metrics you want to track. You can define the rules based on individual metrics or the activity log.

+6. When you finish setting up alerts, save the changes and based on the metrics configured you begin to see the **Alerts** blade populate over time.

+# Apply the Key Vault Virtual Machine (VM) extension to Azure Cloud Services (extended support)

+The following procedure shows you how to install the Key Vault VM extension on Azure Cloud Services by first creating a bootstrap certificate in your vault to get a token from Microsoft Entra ID. That token helps in the authentication of the extension with the vault. After the authentication process is set up and the extension is installed, all the latest certificates will be pulled down automatically at regular polling intervals.

+The Azure portal uses the remote desktop extension to enable remote desktop even after the application is deployed. The remote desktop settings for your Cloud Service allow you to enable remote desktop, update the local administrator account, select the certificates used in authentication, and set the expiration date for those certificates.

+4. Fill in the required fields for user name, password, and expiration.

+5. When finished, select **Save**. It takes a few moments before your role instances are ready to receive connections.

+1. Select on **Roles and Instances** to open the instance settings.

+3. Select **Connect** to download a remote desktop connection file.

+Follow the below steps to update your cloud service to the latest module with a Remote Desktop Protocol (RDP) extension

+ Title: Apply the Microsoft Azure diagnostics extension in Cloud Services (extended support)

+description: Apply the Microsoft Azure diagnostics extension for Cloud Services (extended support)

+# Apply the Microsoft Azure diagnostics extension in Cloud Services (extended support)

+You can monitor key performance metrics for any cloud service. Every cloud service role collects minimal data: CPU usage, network usage, and disk utilization. If the cloud service has the Microsoft.Azure.Diagnostics extension applied to a role, that role can collect more points of data. For more information, see [Extensions Overview](extensions.md)

+Microsoft Azure Diagnostics extension can be enabled for Cloud Services (extended support) through [PowerShell](deploy-powershell.md) or [ARM template](deploy-template.md)

+## Apply Microsoft Azure Diagnostics extension using PowerShell

+Here's an example of the public configuration XML file

+Here's an example of the private configuration XML file

+## Apply Microsoft Azure Diagnostics extension using ARM template

+The Key Vault Virtual Machine (VM) extension provides automatic refresh of certificates stored in an Azure Key Vault. Specifically, the extension monitors a list of observed certificates stored in key vaults, and upon detecting a change, retrieves, and installs the corresponding certificates. It also allows cross region/cross subscription reference of certificates for Cloud Service (extended support).

+Remote Desktop enables you to access the desktop of a role running in Azure. You can use a remote desktop connection to troubleshoot and diagnose problems with your application while it's running.

+## Microsoft Azure Diagnostics extension

+You can monitor key performance metrics for any cloud service. Every cloud service role collects minimal data: CPU usage, network usage, and disk utilization. If the cloud service has the Microsoft.Azure.Diagnostics extension applied to a role, that role can collect more points of data.

+With basic monitoring, performance counter data from role instances is sampled and collected at 3-minute intervals. This basic monitoring data isn't stored in your storage account and has no additional cost associated with it.

+With advanced monitoring, more metrics are sampled and collected at intervals of 5 minutes, 1 hour, and 12 hours. The aggregated data is stored in a storage account, in tables, and is purged after 10 days. The storage account used configures based on role; you can use different storage accounts for different roles.

+For more information, see [Apply the Microsoft Azure diagnostics extension in Cloud Services (extended support)](enable-wad.md)

+An Azure application or service can enable and configure Microsoft Antimalware for Azure Cloud Services using PowerShell cmdlets. Microsoft Antimalware is installed in a disabled state in the Cloud Services platform running Windows Server 2012 R2 and older, which requires an action by an Azure application to enable it. For Windows Server 2016 and above, Windows Defender is enabled by default, and so, these cmdlets can be used for configuring Antimalware.

+To know more about Azure Antimalware, visit [Microsoft Antimalware for Azure Cloud Services and Virtual Machines](../security/fundamentals/antimalware.md)

+This article provides a feature analysis of Cloud Services (extended support) and Virtual Machine Scale Sets. For more information on Virtual Machine Scale Sets, visit the documentation [here](../virtual-machine-scale-sets/overview.md)

+|SKUs supported|D, Dv2, Dv3, Dav4 series, Ev3, Eav4 series, G series, H series|D series, E series, F series, A series, B series, Intel, AMD; Specialty SKUs (G, H, L, M, N) aren't supported|All SKUs|

+|Mix operating systems|Limited Windows support|Yes, Linux and Windows can reside in the same Flexible scale set|No, instances are the same operating system|

+|Availability Zones|No|Specify instances land across 1, 2, or 3 availability zones|Specify instances land across 1, 2, or 3 availability zones|

+|Fault Domain ΓÇô Max Spreading (Azure maximally spreads instances)|Yes|Yes|Yes|

+|Fault Domain ΓÇô Fixed Spreading|Five update domains|2-3 FDs (depending on regional maximum FD Count); 1 for zonal deployments|2, 3 5 FDs 1, 5 for zonal deployments|

+|Update Domains|Yes|Depreciated (platform maintenance performed FD by FD)|Five update domains|

+|Microsoft Edge Sites|No|Yes|Yes|

+ 1. Go to the Azure portal and [create a new cloud service](deploy-portal.md). Add your cloud service configuration, package, and definition files.

+ 2. Once you complete all fields, move to the Review and Create tab to validate your deployment configuration and select on **Download template for automation** your Cloud Service (extended support).

+| Role Instances restarting UD by UD after successful commit. | Restart operation follows the same method as monthly guest OS rollouts. Don't commit migration of cloud services with single role instance or impacted by restart.|

+| Azure portal can't read migration state after browser refresh. | Rerun validate and prepare operation to get back to the original migration state. |

+| Resource Group name is in all caps. | Nonimpacting. Solution not yet available. |

+| Name of the lock on Cloud Services (extended support) lock is incorrect. | Nonimpacting. Solution not yet available. |

+| IP address name is incorrect on Cloud Services (extended support) portal blade. | Nonimpacting. Solution not yet available. |

+| Invalid DNS name shown for virtual IP address after on update operation on a migrated cloud service. | Nonimpacting. Solution not yet available. |

+| After successful prepare, linking a new Cloud Services (extended support) deployment as swappable isn't allowed. | Don't link a new cloud service as swappable to a prepared cloud service. |

+| Error messages need to be updated. | Nonimpacting. |

+| The resource type couldn't be found in the namespace `Microsoft.Compute` for API version '2020-10-01-preview'. | [Register the subscription](in-place-migration-overview.md#set-up-access-for-migration) for CloudServices feature flag to access public preview. |

+| Deployment deployment-name in cloud service cloud-service-name must be within a virtual network to be migrated. | Deployment isn't located in a virtual network. For more information, see [the Migration of deployments not in a virtual network section of Technical details of migrating to Azure Cloud Services (extended support)](in-place-migration-technical-details.md#migration-of-deployments-not-in-a-virtual-network). |

+| The Deployment deployment-name in cloud service cloud-service-name can't be migrated because there are no subnets associated with the role(s) role-name. Associate all roles with a subnet, then retry the migration of the cloud service. | Update the cloud service (classic) deployment by placing it in a subnet before migration. |

+| The deployment deployment-name in cloud service cloud-service-name can't be migrated because the deployment requires at least one feature that not registered on the subscription in Azure Resource Manager. Register all required features to migrate this deployment. | Contact support to get the feature flags registered. |

+| The deployment can't be migrated because the deployment's cloud service has two occupied slots. Migration of cloud services is only supported for deployments that are the only deployment in their cloud service. To proceed with the migration of this deployment, delete the other deployment in the cloud service. | For more information, see the [unsupported scenario list](in-place-migration-technical-details.md#unsupported-configurations--migration-scenarios). |

+| Deployment deployment-name in HostedService cloud-service-name is in intermediate state: state. Migration not allowed. | Deployment is either being created, deleted, or updated. Wait for the operation to complete and retry. |

+| Migration of Deployment {0} in HostedService {1} is in the process of being committed and can't be changed until it completes successfully. | Wait or retry operation. |

+| Migration of Deployment {0} in HostedService {1} is in the process of being aborted and can't be changed until it completes successfully. | Wait or retry operation. |

+| Migration isn't supported for Deployment {0} in HostedService {1} because it uses following features not yet supported for migration: Nonvnet deployment.| Deployment isn't located in a virtual network. For more information, see [the Migration of deployments not in a virtual network section of Technical details of migrating to Azure Cloud Services (extended support)](in-place-migration-technical-details.md#migration-of-deployments-not-in-a-virtual-network). |

+| The virtual network name can't be null or empty. | Provide virtual network name in the REST request body |

+| The Subnet Name can't be null or empty. | Provide subnet name in the REST request body. |

+| Default virtual network destination option not implemented. | ΓÇ£DefaultΓÇ¥ value isn't supported for DestinationVirtualNetwork property in the REST request body. |

+| The deployment {0} can't be migrated because the CSPKG isn't available. | Upgrade the deployment and try again. |

+| The subnet with ID '{0}' is in a different location than deployment '{1}' in hosted service '{2}'. The location for the subnet is '{3}' and the location for the hosted service is '{4}'. Specify a subnet in the same location as the deployment. | Update the cloud service to have both subnet and cloud service in the same location before migration. |

+| Migration of Deployment {0} in HostedService {1} is in the process of being aborted and can't be changed until it completes successfully. | Wait for abort to complete or retry abort. Use [Microsoft Q&A](/answers/topics/azure-cloud-services-extended-support.html) or Contact support otherwise. |

+| Deployment {0} in HostedService {1} hasn't been prepared for Migration. | Run prepare on the cloud service before running the commit operation. |

+| The current quota for Resource name in Azure Resource Manager is insufficient to complete migration. Current quota is {0}, additional needed is {1}. File a support request to raise the quota and retry migration once the quota raises. | To request a quota increase, follow the appropriate channels: <br>[Quota increase for networking resources](../azure-portal/supportability/networking-quota-requests.md) <br>[Quota increase for compute resources](../azure-portal/supportability/per-vm-quota-requests.md) |

+|XrpPaaSMigrationCscfgCsdefValidationMismatch: Migration couldn't be completed on deployment deployment-name in hosted service service-name because the deployment's metadata is stale. Abort the migration and upgrade the deployment before retrying migration. Validation Message: The service name 'service-name'in the service definition file doesn't match the name 'service-name-in-config-file' in the service configuration file|match the service names in both .csdef and .cscfg file|

+Cloud Services (extended support) supports two paths for customers to migrate from Azure Service Manager to Azure Resource

+The following table highlights comparison between these two options.

+| This migration is a lift and shift scenario, which offers more flexibility but requires more time to migrate. | This scenario is an automated migration that offers quick migration but less flexibility. |

+When evaluating migration plans from Cloud Services (classic) to Cloud Services (extended support), you may want to investigate other Azure services such as: [Virtual Machine Scale Sets](../virtual-machine-scale-sets/overview.md), [App Service](../app-service/overview.md), [Azure Kubernetes Service](../aks/intro-kubernetes.md), and [Azure Service Fabric](../service-fabric/overview-managed-cluster.md). These services continue to feature other capabilities, while Cloud Services (extended support) maintains feature parity with Cloud Services (classic).

+Depending on the application, Cloud Services (extended support) may require substantially less effort to move to Azure Resource Manager compared to other options. If your application isn't evolving, Cloud Services (extended support) is a viable option to consider as it provides a quick migration path. Conversely, if your application is continuously evolving and needs a more modern feature set, do explore other Azure services to better address your current and future requirements.

+- Underlying update process with respect to update domains, how upgrade proceeds, rollback, and allowed service changes during an update remains unchanged.

+- Offers testing for migrated deployments after successful preparation. Commit and finalize the migration while abort rolls back the migration.

+## Set up access for migration

+3. Find the appropriate subscription entry, and then look at the MY ROLE field. For a coadministrator, the value should be Account admin. If you're not able to add a coadministrator, contact a service administrator or coadministrator for the subscription to get yourself added.

+4. Register your subscription for Microsoft.ClassicInfrastructureMigrate namespace using [Portal](../azure-resource-manager/management/resource-providers-and-types.md#azure-portal), [PowerShell](../azure-resource-manager/management/resource-providers-and-types.md#azure-powershell), or [CLI](../azure-resource-manager/management/resource-providers-and-types.md#azure-cli)

+1. **Validate Migration** - Validates that common unsupported scenarios won't prevent migration.

+2. **Prepare Migration** ΓÇô Duplicates the resource metadata in Azure Resource Manager. All resources are locked for create/update/delete operations to ensure resource metadata is in sync across Azure Server Manager and Azure Resource Manager. All read operations work using both Cloud Services (classic) and Cloud Services (extended support) APIs.

+4. **Commit Migration** - Removes resource metadata from Azure Service Manager. Unlocks the resource for create/update/delete operations. Abort is no longer allowed after commit attempts.

+The following list contains top scenarios involving combinations of resources, features, and Cloud Services. This list isn't exhaustive.

+| Cloud Service | Cloud Service with a deployment in a single slot only. | Cloud Services containing a prod slot deployment can be migrated. It isn't recommended to migrate staging slot as this process can result in issues with retaining service FQDN. To migrate staging slot, first promote staging deployment to production and then migrate to Azure Resource Manager. |

+| Cloud Service | Deployment not in a publicly visible virtual network (default virtual network deployment) | A Cloud Service can be in a publicly visible virtual network, in a hidden virtual network or not in any virtual network. Cloud Services in a hidden virtual network and publicly visible virtual networks are supported for migration. Customer can use the Validate API to tell if a deployment is inside a default virtual network or not and thus determine if it can be migrated. |

+| Virtual Network | Virtual network containing multiple Cloud Services. | Virtual network contain multiple cloud services is supported for migration. The virtual network and all the Cloud Services within it migrate together to Azure Resource Manager. |

+| Virtual Network | Migration of virtual networks created via Portal (Requires using ΓÇ£Group Resource-group-name VNet-NameΓÇ¥ in .cscfg file) | As part of migration, the virtual network name in cscfg changes to use Azure Resource Manager ID of the virtual network. (subscription/subscription-id/resource-group/resource-group-name/resource/vnet-name) <br><br>To manage the deployment after migration, update the local copy of .cscfg file to start using Azure Resource Manager ID instead of virtual network name. <br><br>A .cscfg file that uses the old naming scheme fails validation.

+If you're not able to add a coadministrator, contact a service administrator or [coadministrator](../role-based-access-control/classic-administrators.md) for the subscription to get yourself added.

+1. Wait five minutes for the registration to complete, then check the status of the approval.

+ If validation fails, a list of unsupported scenarios displays. They need to be fixed before migration can continue.

+ If the preparation is successful, the migration is ready for commit.

+ If the preparation fails, review the error, address any issues, and retry the preparation.

+ Type in "yes" to confirm and commit to the migration. The migration is now complete. The migrated Cloud Services (extended support) deployment is unlocked for all operations.

+Review the [Post migration changes](post-migration-changes.md) section to see changes in deployment files, automation, and other attributes of your new Cloud Services (extended support) deployment.

+## Plan for migration

+Planning is the most important step for a successful migration experience. Review the [Cloud Services (extended support) overview](overview.md) and [Planning for migration of IaaS resources from classic to Azure Resource Manager](../virtual-machines/migration-classic-resource-manager-plan.md) before beginning any migration steps.

+## Install the latest version of PowerShell

+## Ensure Admin permissions

+If you're not able to add a coadministrator, contact a service administrator or coadministrator for the subscription to get yourself added.

+## Register the classic provider and CloudService feature

+Check the status of registration using the following command:

+## Migrate your Cloud Services

+* [Migrate a Cloud Service not in a virtual network](#option-1migrate-a-cloud-service-not-in-a-virtual-network)

+* [Migrate a Cloud Service in a virtual network](#option-2migrate-a-cloud-service-in-a-virtual-network)

+### Option 1 - Migrate a Cloud Service not in a virtual network

+### Option 2 - Migrate a Cloud Service in a virtual network

+Review the [Post migration changes](post-migration-changes.md) section to see changes in deployment files, automation, and other attributes of your new Cloud Services (extended support) deployment.

+- All enabled and supported extensions are migrated.

+- Plugins are a legacy concept and should be removed before migration. They're supported for migration, but after migration, if extension needs to be enabled, the plugin needs to be removed before installing the extension. This limitation affects remote desktop plugins and extensions the most.

+- The names of resources like virtual network and virtual machine (VM) SKU are different. See [Translation of resources and naming convention post migration](#translation-of-resources-and-naming-convention-post-migration)

+- Each Cloud Services (extended support) deployment is an independent Cloud Service. Deployments are no longer grouped into a cloud service using slots.

+- As part of the migration, this default virtual network is exposed to customers once in Azure Resource Manager. To manage or update the deployment in Azure Resource Manager, customers need to add this virtual network information in the NetworkConfiguration section of the .cscfg file.

+- To check if a deployment is eligible to migrate, run the validate API on the deployment. The result of Validate API contains error message explicitly mentioning if this deployment is eligible to migrate.

+- As part of migration, Azure automatically creates a new Key Vault and migrates all the certificates to it. The tool doesn't allow you to use an existing Key Vault.

+This list contains the top scenarios involving combinations of resources, features, and Cloud Services. This list isn't exhaustive.

+| Quota | Quota isn't migrated. [Request new quota](../azure-resource-manager/templates/error-resource-quota.md#solution) on Azure Resource Manager prior to migration for the validation to be successful. |

+| Migration of some older deployments not in a virtual network | Some Cloud Service deployments not in a virtual network aren't supported for migration. <br><br> 1. Use the validate API to check if the deployment is eligible to migrate. <br> 2. If eligible, the deployments move to Azure Resource Manager under a virtual network with prefix of ΓÇ£DefaultRdfeVnetΓÇ¥ |

+| Migration of deployment containing the remote desktop plugin and the remote desktop extensions | Option 1: Remove the remote desktop plugin before migration. This requires changes to deployment files. The migration then goes through. <br><br> Option 2: Remove remote desktop extension and migrate the deployment. Post-migration, remove the plugin and install the extension. This requires changes to deployment files. <br><br> Remove the plugin and extension before migration. [Plugins aren't recommended](./deploy-prerequisite.md#required-definition-file-updates) for use on Cloud Services (extended support).|

+| Virtual networks with both PaaS and IaaS deployment |Not Supported <br><br> Move either the PaaS or IaaS deployments into a different virtual network. This causes downtime. |

+| Migration of Cloud Service to different virtual network | Not supported <br><br> 1. Move the deployment to a different classic virtual network before migration. This causes downtime. <br> 2. Migrate the new virtual network to Azure Resource Manager. <br><br> Or <br><br> 1. Migrate the virtual network to Azure Resource Manager <br>2. Move the Cloud Service to a new virtual network. This causes downtime. |

+| Deployment (portal created) <br><br> Deployment (nonportal created) | `deploymentname` | Cloud Services (extended support) | `cloudservicename` |

+| Reserved IP Name | `reservedipname` | Reserved IP (nonportal created) <br><br> Reserved IP (portal created) | `reservedipname` <br><br> `group-resourcegroupname-reservedipname` |

+- If validation failed, it is because the deployment or virtual network contains an unsupported scenario/feature/resource. Use the list of unsupported scenarios to find the work-around in the documents.

+- If the commit failed, retry the operation. If retry fail, then contact support. Even in commit failure, there should be no data plane issue to your deployment. Your deployment should be able to handle customer traffic without any issue.

+Validate is designed to be quick. Prepare is longest running and takes some time depending on total number of role instances being migrated. Abort and commit can also take time but takes less time compared to prepare. All operations will time out after 24 hrs.

+description: How to migrate nonvnet cloud services to a virtual network

+Some legacy cloud services are still running without virtual network support. While there's a process for migrating directly through the portal, there are certain considerations that should be made before migration. This article walks you through the process of migrating a non virtual network supporting Cloud Service to a virtual network supporting Cloud Service.

+1. Create a non virtual network classic cloud service in the same region as the virtual network you want to migrate to. In the Azure portal, select the 'Staging' drop-down.

+1. Create a deployment with same configuration as existing deployment by selecting 'Upload' next to the staging drop-down. The platform creates a Default virtual network deployment in staging slot.

+* When **allowModelOverride** is set to `true`, an API call updates the role size and instance count for the cloud service without validating the values with the .csdef and .cscfg files.

+Setting the **allowModelOverride** property to `true` here updates the cloud service with the role properties defined in the `roleProfile` section:

+Setting the `AllowModelOverride` switch on the new `New-AzCloudService` cmdlet updates the cloud service with the SKU properties defined in the role profile:

+Setting the `AllowModelOverride` variable to `true` updates the cloud service with the SKU properties defined in the role profile:

+Cloud Services (extended support) is a new [Azure Resource Manager](../azure-resource-manager/management/overview.md) based deployment model for [Azure Cloud Services](https://azure.microsoft.com/services/cloud-services/) product and is now generally available. Cloud Services (extended support) has the primary benefit of providing regional resiliency along with feature parity with Azure Cloud Services deployed using Azure Service Manager. It also offers some Azure Resource Manager capabilities such as role-based access and control (RBAC), tags, policy, and supports deployment templates.

+With this change, the Azure Service Manager based deployment model for Cloud Services is renamed to [Cloud Services (classic)](../cloud-services/cloud-services-choose-me.md). You retain the ability to build and rapidly deploy your web and cloud applications and services. You're able to scale your cloud services infrastructure based on current demand and ensure that the performance of your applications can keep up while simultaneously reducing costs.

+## What doesn't change

+- The three components of a cloud service, the service definition (.csdef), the service config (.cscfg), and the service package (.cspkg) are carried forward and there's no change in the [formats](cloud-services-model-and-package.md).

+Minimal changes are required to Service Configuration (.cscfg) and Service Definition (.csdef) files to deploy Cloud Services (extended support). No changes are required to runtime code. However, deployment scripts need to be updated to call the new Azure Resource Manager based APIs.

+- Azure Resource Manager deployments use [ARM templates](../azure-resource-manager/templates/overview.md), which is a JavaScript Object Notation (JSON) file that defines the infrastructure and configuration for your project. The template uses declarative syntax, which lets you state what you intend to deploy without having to write the sequence of programming commands to create it. Service Configuration and Service definition file needs to be consistent with the [ARM Template](../azure-resource-manager/templates/overview.md) while deploying Cloud Services (extended support). This can be achieved either by [manually creating the ARM template](deploy-template.md) or using [PowerShell](deploy-powershell.md), [Portal](deploy-portal.md), and [Visual Studio](deploy-visual-studio.md).

+- Customers must use [Azure Key Vault](../key-vault/general/overview.md) to [manage certificates in Cloud Services (extended support)](certificates-and-key-vault.md). Azure Key Vault lets you securely store and manage application credentials such as secrets, keys, and certificates in a central and secure cloud repository. Your applications can authenticate to Key Vault at run time to retrieve credentials.

+- All resources deployed through the [Azure Resource Manager](../azure-resource-manager/templates/overview.md) must be inside a virtual network. Virtual networks and subnets are created in Azure Resource Manager using existing Azure Resource Manager APIs. They need to be referenced within the NetworkConfiguration section of the .cscfg when deploying Cloud Services (extended support).

+- Each cloud service (extended support) is a single independent deployment. Cloud Services (extended support) doesn't support multiple slots within a single cloud service.

+When evaluating migration plans from Cloud Services (classic) to Cloud Services (extended support), you may want to investigate other Azure services such as: [Virtual Machine Scale Sets](../virtual-machine-scale-sets/overview.md), [App Service](../app-service/overview.md), [Azure Kubernetes Service](../aks/intro-kubernetes.md), and [Azure Service Fabric](../service-fabric/service-fabric-overview.md). These services continue to feature additional capabilities, while Cloud Services (extended support) maintains feature parity with Cloud Services (classic.)

+Depending on the application, Cloud Services (extended support) may require substantially less effort to move to Azure Resource Manager compared to other options. If your application isn't evolving, Cloud Services (extended support) is a viable option to consider as it provides a quick migration path. Conversely, if your application is continuously evolving and needs a more modern feature set, do explore other Azure services to better address your current and future requirements.

+ Title: Azure Cloud Services (extended support) post-migration changes

+Minor changes are made to customerΓÇÖs .csdef and .cscfg file to make the deployment files conform to the Azure Resource Manager and Cloud Services (extended support) requirements. Post migration retrieves your new deployment files or updates the existing files, which are needed for update/delete operations.

+ - The Key Vault is created without any access policies. To view or manage your certificates, [create appropriate policies](../key-vault/general/assign-access-policy-portal.md) on the Key Vault. Certificates are visible under settings on the tab called secrets.

+As a standard practice to manage your certificates, all the valid .pfx certificate files should be added to certificate store in Key Vault and update would work perfectly fine via any client - Portal, PowerShell, or REST API.

+If you published updates via Visual Studio directly, then you would need to first download the latest CSCFG file from your deployment post migration. Use this file as reference to add Network Configuration details to your current CSCFG file in Visual Studio project. Then build the solution and publish it. You might have to choose the Key Vault and Resource Group for this update.

+This command reimages two role instances ContosoFrontEnd_IN_0 and ContosoBackEnd_IN_1 of cloud service named ContosoCS that belongs to the resource group named ContosOrg.

+This command rebuilds two role instances ContosoFrontEnd_IN_0 and ContosoBackEnd_IN_1 of cloud service named ContosoCS that belongs to the resource group named ContosOrg.

+This command restarts two role instances ContosoFrontEnd_IN_0 and ContosoBackEnd_IN_1 of cloud service named ContosoCS that belongs to the resource group named ContosOrg.

+The following set of commands adds a Remote Desktop Protocol (RDP) extension to already existing cloud service named ContosoCS that belongs to the resource group named ContosOrg.

+The following set of commands removes all extensions from existing cloud service named ContosoCS that belongs to the resource group named ContosOrg.

+The following set of commands removes RDP extension from existing cloud service named ContosoCS that belongs to the resource group named ContosOrg.

+The following set of commands shows how to scale-out and scale-in role instance count for cloud service named ContosoCS that belongs to the resource group named ContosOrg.

+The service configuration file specifies the number of role instances to deploy for each role in the service, the values of any configuration settings, and the thumbprints for any certificates associated with a role. If the service is part of a Virtual Network, configuration information for the network must be provided in the service configuration file and the virtual networking configuration file. The default extension for the service configuration file is cscfg.

+The [Cloud Service (extended support) definition schema](schema-csdef-file.md) describes the service model.

+The following articles describe the schema for the `ServiceConfiguration` element:

+|osFamily|Optional. Specifies the Guest OS that runs on role instances in the Cloud Service. For information about supported Guest OS releases, see [Azure Guest OS Releases and SDK Compatibility Matrix](../cloud-services/cloud-services-guestos-update-matrix.md).<br /><br /> If you don't include an `osFamily` value and you have not set the `osVersion` attribute to a specific Guest OS version, a default value of 1 is used.|

+|osVersion|Optional. Specifies the version of the Guest OS that runs on role instances in the Cloud Service. For more information about Guest OS versions, see [Azure Guest OS Releases and SDK Compatibility Matrix](../cloud-services/cloud-services-guestos-update-matrix.md).<br /><br /> You can specify that the Guest OS should be automatically upgraded to the latest version. To do this, set the value of the `osVersion` attribute to `*`. When set to `*`, the role instances are deployed using the latest version of the Guest OS for the specified OS family and automatically upgrades when new versions of the Guest OS are released.<br /><br /> To specify a specific version manually, use the `Configuration String` from the table in the **Future, Current, and Transitional Guest OS Versions** section of [Azure Guest OS Releases and SDK Compatibility Matrix](../cloud-services/cloud-services-guestos-update-matrix.md).<br /><br /> The default value for the `osVersion` attribute is `*`.|

+The `NetworkConfiguration` element of the service configuration file specifies Virtual Network and Domain Name System (DNS) values. These settings are optional for Cloud Services (classic).

+| VirtualNetworkSite | Mandatory. Specifies the name of the Virtual Network site in which you want to deploy your Cloud Service. This setting doesn't create a Virtual Network Site. It references a site previously defined in the network file for your Virtual Network. A Cloud Service (extended support) can only be a member of one Virtual Network. The name of the Virtual Network site is defined by a string for the `name` attribute.|

+| InstanceAddress | Mandatory. Specifies the association of a role to a subnet or set of subnets in the Virtual Network. When you associate a role name to an instance address, you can specify the subnets to which you want this role to be associated. The `InstanceAddress` contains a Subnets element. The name of the role that is associated with the subnet or subnets is defined by a string for the `roleName` attribute. You need to specify one instance address for each role defined for your cloud service|

+| ReservedIP | Optional. Specifies the reserved IP address that should be associated with the deployment. The allocation method for a reserved IP needs to be specified as `Static` for template and PowerShell deployments. Each deployment in a Cloud Service can be associated with only one reserved IP address. The name of the reserved IP address is defined by a string for the `name` attribute.|

+## <a name="Role"></a> Role element

+The service definition file must contain one `ServiceDefinition` element. The service definition must contain at least one role (`WebRole` or `WorkerRole`) element. It can contain up to 25 roles defined in a single definition and you can mix role types. The service definition also contains the optional `NetworkTrafficRules` element, which restricts which roles can communicate to specified internal endpoints. The service definition also contains the optional `LoadBalancerProbes` element, which contains customer defined health probes of endpoints.

+The following articles describe the schema:

+| topologyChangeDiscovery | Optional. Specifies the type of topology change notification. Possible values are:<br /><br /> - `Blast` - Sends the update as soon as possible to all role instances. If you choose option, the role should be able to handle the topology update without being restarted.<br />- `UpgradeDomainWalk` ΓÇô Sends the update to each role instance in a sequential manner after the previous instance successfully accepts the update.|

+The load balancer probe is a customer defined health probe of UDP endpoints and endpoints in role instances. The `LoadBalancerProbe` isn't a standalone element; it's combined with the web role or worker role in a service definition file. More than one role can use a `LoadBalancerProbe`.

+The default load balancer probe utilizes the Guest Agent inside the virtual machine, which listens and responds with an HTTP 200 OK response only when the instance is in the Ready state (like when the instance isn't in the Busy, Recycling, Stopping, etc. states). If the Guest Agent fails to respond with HTTP 200 OK, the Azure Load Balancer marks the instance as unresponsive and stops sending traffic to that instance. The Azure Load Balancer continues to ping the instance, and if the Guest Agent responds with an HTTP 200, the Azure Load Balancer sends traffic to that instance again. When using a web role your website code typically runs in w3wp.exe, which isn't monitored by the Azure fabric or guest agent, which means failures in w3wp.exe (for example, HTTP 500 responses) isn't be reported to the guest agent and the load balancer doesn't know to take that instance out of rotation.

+The custom load balancer probe overrides the default guest agent probe and allows you to create your own custom logic to determine the health of the role instance. The load balancer regularly probes your endpoint (every 15 seconds, by default), and the instance is considered in rotation if it responds with a TCP ACK or HTTP 200 within the timeout period (default of 31 seconds). This can be useful to implement your own logic to remove instances from load balancer rotation, for example returning a non-200 status if the instance is above 90% CPU. For web roles using w3wp.exe, this also means you get automatic monitoring of your website, since failures in your website code return a non-200 status to the load balancer probe. If you don't define a LoadBalancerProbe in the csdef file, then the default load balancer behavior (as previously described) is used.

+If you use a custom load balancer probe, you must ensure that your logic takes into consideration the RoleEnvironment.OnStop method. When you use the default load balancer probe, the instance is taken out of rotation before OnStop is called, but a custom load balancer probe can continue to return a 200 OK during the OnStop event. If you use the OnStop event to clean up cache, stop service, or otherwise making changes that can affect the runtime behavior of your service, then you need to ensure that your custom load balancer probe logic removes the instance from rotation.

+| `path` | `string` | The URI used for requesting health status from the VM. `path` is required if `protocol` is set to `http`. Otherwise, it isn't allowed.<br /><br /> There's no default value.|

+| `port` | `integer` | Optional. The port for communicating the probe. This attribute is optional for any endpoint, as the same port is used for the probe. You can configure a different port for their probing, as well. Possible values range from 1 to 65535, inclusive.<br /><br /> The default value set by the endpoint.|

+| `intervalInSeconds` | `integer` | Optional. The interval, in seconds, for how frequently to probe the endpoint for health status. Typically, the interval is slightly less than half the allocated timeout period (in seconds) which allows two full probes before taking the instance out of rotation.<br /><br /> The default value is 15. The minimum value is 5.|

+| `timeoutInSeconds` | `integer` | Optional. The timeout period, in seconds, applied to the probe where no response results in stopping further traffic from being delivered to the endpoint. This value allows endpoints to be taken out of rotation faster or slower than the typical times used in Azure (which are the defaults).<br /><br /> The default value is 31. The minimum value is 11.|

+The `NetworkTrafficRules` node is an optional element in the service definition file that specifies how roles communicate with each other. It limits which roles can access the internal endpoints of the specific role. The `NetworkTrafficRules` isn't a standalone element; it's combined with two or more roles in a service definition file.

+The `NetworkTrafficRules` node of the service definition file includes these elements, described in detail in subsequent sections in this article:

+The `Destinations` element describes a collection of RoleEndpoints that can be communicated with.

+The `WhenSource` element describes a collection of roles that can communicate with the endpoints defined in the `Destinations` node.

+The service definition file includes these elements, described in detail in subsequent sections in this article:

+Input and Internal endpoints are allocated separately. A service can have a total of 25 input, internal, and instance input endpoints, which can be allocated across the 25 roles allowed in a service. For example, if you have five roles, you can allocate five input endpoints per role, or you can allocate 25 input endpoints to a single role or you can allocate one input endpoint each to 25 roles.

+|localPort|int|Optional. Specifies a port used for internal connections on the endpoint. The `localPort` attribute maps the external port on the endpoint to an internal port on a role. This attribute is useful in scenarios where a role must communicate to an internal component on a port that different from the one that is exposed externally.<br /><br /> If not specified, the value of `localPort` is the same as the `port` attribute. Set the value of `localPort` to ΓÇ£*ΓÇ¥ to automatically assign an unallocated port that is discoverable using the runtime API.<br /><br /> Possible values range between 1 and 65535, inclusive (Azure SDK version 1.7 or higher).<br /><br /> The `localPort` attribute is only available using the Azure SDK version 1.3 or higher.|

+|ignoreRoleInstanceStatus|boolean|Optional. When the value of this attribute is set to `true`, the status of a service is ignored, and the load balancer won't remove the endpoint. Setting this value to `true` useful for debugging busy instances of a service. The default value is `false`. **Note:** An endpoint can still receive traffic even when the role isn't in a Ready state.|

+The `InternalEndpoint` element describes an internal endpoint to a web role. An internal endpoint is available only to other role instances running within the service; it isn't available to clients outside the service. Web roles that don't include the `Sites` element can only have a single HTTP, UDP, or TCP internal endpoint.

+|port|int|Optional. The port used for internal load-balanced connections on the endpoint. A load-balanced endpoint uses two ports. The port used for the public IP address, and the port used on the private IP address. Typically, these values are set to the same, but you can choose to use different ports.<br /><br /> Possible values range between 1 and 65535, inclusive (Azure SDK version 1.7 or higher).<br /><br /> The `Port` attribute is only available using the Azure SDK version 1.3 or higher.|

+|localPort|int|Required. Specifies the internal port that all role instances listen to in order to receive incoming traffic forwarded from the load balancer. Possible values range between 1 and 65535, inclusive.|

+The `AllocatePublicPortFrom` element describes the public port range that external customers can use to access each instance input endpoint. The public (VIP) port number is allocated from this range and assigned to each individual role instance endpoint during tenant deployment and update. This element is the parent of the `FixedPortRange` element.

+|port|int|Required. The port for the internal endpoint. This attribute has the same effect as setting the `FixedPortRange` min and max to the same port.<br /><br /> Possible values range between 1 and 65535, inclusive (Azure SDK version 1.7 or higher).|

+|name|string|Required. A name for this certificate, which is used to refer to it when it's associated with an HTTPS `InputEndpoint` element.|

+|moduleName|string|Required. The name of the module to import. Valid import modules are:<br /><br /> - RemoteAccess<br />- RemoteForwarder<br />- Diagnostics<br /><br /> The RemoteAccess and RemoteForwarder modules allow you to configure your role instance for remote desktop connections. For more information, see [Extensions](extensions.md).<br /><br /> The Diagnostics module allows you to collect diagnostic data for a role instance.|

+|assemblyName|string|Required. The path and file name of the assembly containing the entry point. The path is relative to the folder **\\%ROLEROOT%\Approot** (don't specify **\\%ROLEROOT%\Approot** in command line; it's assumed). **%ROLEROOT%** is an environment variable maintained by Azure and it represents the root folder location for your role. The **\\%ROLEROOT%\Approot** folder represents the application folder for your role.<br /><br /> For HWC roles the path is always relative to the **\\%ROLEROOT%\Approot\bin** folder.<br /><br /> For full IIS and IIS Express web roles, if the assembly can't be found relative to **\\%ROLEROOT%\Approot** folder, the **\\%ROLEROOT%\Approot\bin** is searched.<br /><br /> This fall back behavior for full IIS isn't a recommend best practice and maybe removed in future versions.|

+The `Sites` element describes a collection of websites and web applications that are hosted in a web role. This element is the parent of the `Site` element. If you don't specify a `Sites` element, your web role is hosted as legacy web role, and you can only have one website hosted in your web role. This element is optional and a role can have only one sites block.

+|physicalDirectory|string|Required. Specifies the path on the development machine that contains the virtual application. In the compute emulator, IIS is configured to retrieve content from this location. When deployed to Azure, the contents of the physical directory are packaged along with the rest of the service. When the service package is deployed to Azure, IIS is configured with the location of the unpacked contents.|

+|value|physicalDirectory|Required. Specifies the path on the development machine that contains the website or Virtual directory contents. In the compute emulator, IIS is configured to retrieve content from this location. When deployed to Azure, the contents of the physical directory are packaged along with the rest of the service. When the service package is deployed to Azure, IIS is configured with the location of the unpacked contents.|

+The `Bindings` element describes a collection of bindings for a website. It's the parent element of the `Binding` element. The element is required for every `Site` element. For more information about configuring endpoints, see [Enable Communication for Role Instances](../cloud-services/cloud-services-enable-communication-role-instances.md).

+|commandLine|string|Required. A script, such as a CMD file, containing the commands to run. Startup command and batch files must be saved in ANSI format. File formats that set a byte-order marker at the start of the file processes incorrectly.|

+|taskType|string|Specifies the execution behavior of the command.<br /><br /> - `simple` [Default] ΓÇô System waits for the task to exit before any other tasks are launched.<br />- `background` ΓÇô System doesn't wait for the task to exit.<br />- `foreground` ΓÇô Similar to background, except role isn't restarted until all foreground tasks exit.|

+The `Content` element defines the source location of content to be copied to the Azure virtual machine and the destination path to which it copies.

+|path|string|Required. Relative or absolute path of a local directory whose contents copy to the Azure virtual machine. Expansion of environment variables in the directory path is supported.|

+## Next steps

+The service definition file includes these elements, described in detail in subsequent sections in this article:

+Input and Internal endpoints are allocated separately. A service can have a total of 25 input, internal, and instance input endpoints, which can be allocated across the 25 roles allowed in a service. For example, if you have five roles, you can allocate five input endpoints per role, or you can allocate 25 input endpoints to a single role or you can allocate one input endpoint each to 25 roles.

+|localPort|int|Optional. Specifies a port used for internal connections on the endpoint. The `localPort` attribute maps the external port on the endpoint to an internal port on a role. This attribute is useful in scenarios where a role must communicate to an internal component on a port that different from the one that is exposed externally.<br /><br /> If not specified, the value of `localPort` is the same as the `port` attribute. Set the value of `localPort` to ΓÇ£*ΓÇ¥ to automatically assign an unallocated port that is discoverable using the runtime API.<br /><br /> Possible values range between 1 and 65535, inclusive (Azure SDK version 1.7 or higher).<br /><br /> The `localPort` attribute is only available using the Azure SDK version 1.3 or higher.|

+|ignoreRoleInstanceStatus|boolean|Optional. When the value of this attribute is set to `true`, the status of a service is ignored and the endpoint won't be removed by the load balancer. Setting this value to `true` useful for debugging busy instances of a service. The default value is `false`. **Note:** An endpoint can still receive traffic even when the role isn't in a Ready state.|

+The `InternalEndpoint` element describes an internal endpoint to a worker role. An internal endpoint is available only to other role instances running within the service; it isn't available to clients outside the service. A worker role may have up to five HTTP, UDP, or TCP internal endpoints.

+|port|int|Optional. The port used for internal load-balanced connections on the endpoint. A load-balanced endpoint uses two ports. The port used for the public IP address, and the port used on the private IP address. Typically, these values are set to the same, but you can choose to use different ports.<br /><br /> Possible values range between 1 and 65535, inclusive (Azure SDK version 1.7 or higher).<br /><br /> The `Port` attribute is only available using the Azure SDK version 1.3 or higher.|

+|localPort|int|Required. Specifies the internal port that all role instances listen to in order to receive incoming traffic forwarded from the load balancer. Possible values range between 1 and 65535, inclusive.|

+The `AllocatePublicPortFrom` element describes the public port range that external customers can use to access each instance input endpoint. The public (VIP) port number is allocated from this range and assigned to each individual role instance endpoint during tenant deployment and update. This element is the parent of the `FixedPortRange` element.

+|port|int|Required. The port for the internal endpoint. This attribute has the same effect as setting the `FixedPortRange` min and max to the same port.<br /><br /> Possible values range between 1 and 65535, inclusive (Azure SDK version 1.7 or higher).|

+|name|string|Required. A name for this certificate, which is used to refer to it when it's associated with an HTTPS `InputEndpoint` element.|

+|moduleName|string|Required. The name of the module to import. Valid import modules are:<br /><br /> - RemoteAccess<br />- RemoteForwarder<br />- Diagnostics<br /><br /> The RemoteAccess and RemoteForwarder modules allow you to configure your role instance for remote desktop connections. For more information, see [Extensions](extensions.md).<br /><br /> The Diagnostics module allows you to collect diagnostic data for a role instance|

+|assemblyName|string|Required. The path and file name of the assembly containing the entry point. The path is relative to the folder **\\%ROLEROOT%\Approot** (don't specify **\\%ROLEROOT%\Approot** in the command line; it's assumed). **%ROLEROOT%** is an environment variable maintained by Azure and it represents the root folder location for your role. The **\\%ROLEROOT%\Approot** folder represents the application folder for your role.|

+The `ProgramEntryPoint` element specifies the program to run for a role. The `ProgramEntryPoint` element allows you to specify a program entry point that isn't based on a .NET assembly.

+|commandLine|string|Required. The path, file name, and any command line arguments of the program to execute. The path is relative to the folder **%ROLEROOT%\Approot** (don't specify **%ROLEROOT%\Approot** in the command line; it's assumed). **%ROLEROOT%** is an environment variable maintained by Azure and it represents the root folder location for your role. The **%ROLEROOT%\Approot** folder represents the application folder for your role.<br /><br /> If the program ends, the role is recycled, so generally set the program to continue to run, instead of being a program that just starts up and runs a finite task.|

+|setReadyOnProcessStart|boolean|Required. Specifies whether the role instance waits for the command line program to signal when it starts. This value must be set to `true` at this time. Setting the value to `false` is reserved for future use.|

+|commandLine|string|Required. A script, such as a CMD file, containing the commands to run. Startup command and batch files must be saved in ANSI format. File formats that set a byte-order marker at the start of the file processes incorrectly.|

+|taskType|string|Specifies the execution behavior of the command.<br /><br /> - `simple` [Default] ΓÇô System waits for the task to exit before any other tasks are launched.<br />- `background` ΓÇô System doesn't wait for the task to exit.<br />- `foreground` ΓÇô Similar to background, except role isn't restarted until all foreground tasks exit.|

+The `Content` element defines the source location of content to be copied to the Azure virtual machine and the destination path to which it copies.

+|path|string|Required. Relative or absolute path of a local directory whose contents copy to the Azure virtual machine. Expansion of environment variables in the directory path is supported.|

+|Unknown|The Role Instance is either in the process of creating or isn't ready to service the traffic|

+|Busy|The Role Instance isn't responding|

+After you swap the deployments, you can stage and test your new release by using the new cloud service deployment. In effect, swapping promotes a new cloud service staged to production release.

+You must make a cloud service swappable with another cloud service when you deploy the second of a pair of cloud services for the first time. Once the second pair of cloud service is deployed, it canΓÇÖt be made swappable with an existing cloud service in subsequent updates.

+Upon deployment of the second cloud service, both the cloud services have their SwappableCloudService property set to point to each other. Any subsequent update to these cloud services needs to specify this property, failing which an error is returned indicating that the SwappableCloudService property can't delete or update.

+Once set, the SwappableCloudService property is treated as readonly. It can't delete or change to another value. Deleting one of the cloud services (of the swappable pair) results in the SwappableCloudService property of the remaining cloud service being cleared.

+Deployments swap quickly because the only thing that changes is the virtual IP address for the cloud service deployed.

+Here's an example of a worker role that creates a startup task with an environment variable named `TestIsEmulated` set to the [@emulated xpath value](#app-running-in-emulator).

+description: How to configure your Azure cloud service application to allow remote desktop connections through the Azure portal.

+Remote Desktop enables you to access the desktop of a role running in Azure. You can use a Remote Desktop connection to troubleshoot and diagnose problems with your application while it runs.

+You can enable a Remote Desktop connection in your role during development by including the Remote Desktop modules in your service definition. Alternatively, you can choose to enable Remote Desktop through the Remote Desktop extension. The preferred approach is to use the Remote Desktop extension, as you can enable Remote Desktop even after the application is deployed without having to redeploy your application.

+The Azure portal uses the Remote Desktop Extension approach so you can enable Remote Desktop even after the application is deployed. The **Remote Desktop** setting for your cloud service allows you to enable Remote Desktop, change the local Administrator account used to connect to the virtual machines, the certificate used in authentication and set the expiration date.

+1. Select **Cloud Services**, select the name of the cloud service, and then select **Remote Desktop**.

+5. When you finish your configuration updates, select **Save**. It takes a few moments before your role instances are ready to receive connections.

+1. Select **Instances** to open the **Instances** settings.

+2. Choose a role instance that has Remote Desktop configured.

+3. Select **Connect** to download a Remote Desktop Protocol (RDP) file for the role instance.

+4. Choose **Open** and then **Connect** to start the Remote Desktop connection.

+## Next steps

+* [How to Configure Cloud Services](cloud-services-how-to-configure-portal.md)

+description: How to configure your Azure cloud service application using PowerShell to allow remote desktop connections through PowerShell.

+Remote Desktop enables you to access the desktop of a role running in Azure. You can use a Remote Desktop connection to troubleshoot and diagnose problems with your application while it runs.

+If you use PowerShell interactively, you can easily set the PSCredential object by calling the [Get-Credentials](/powershell/module/microsoft.powershell.security/get-credential) cmdlet.

+You can also optionally specify the deployment slot and roles that you want to enable remote desktop on. If these parameters aren't specified, the cmdlet enables remote desktop on all roles in the **Production** deployment slot.

+The [Get-AzureRemoteDesktopFile](/powershell/module/servicemanagement/azure/get-azureremotedesktopfile) cmdlet is used to remote desktop into a specific role instance of your cloud service. You can use the *LocalPath* parameter to download the Remote Desktop Protocol (RDP) file locally. Or you can use the *Launch* parameter to directly launch the Remote Desktop Connection dialog to access the cloud service role instance.

+The [Get-AzureServiceRemoteDesktopExtension](/powershell/module/servicemanagement/azure/get-azureremotedesktopfile) cmdlet displays that remote desktop is enabled or disabled on a service deployment. The cmdlet returns the username for the remote desktop user and the roles that the remote desktop extension is enabled for. By default, the deployment slot is used, but you can choose to use the staging slot instead.

+If you already enabled the remote desktop extension on a deployment and need to update the remote desktop settings, first remove the extension. Then, enable it again with the new settings. For example, if you want to set a new password for the remote user account or the account expired. Doing this step is required on existing deployments that have the remote desktop extension enabled. For new deployments, you can apply the extension directly.

+## Next steps

+* [How to Configure Cloud Services](cloud-services-how-to-configure-portal.md)

+description: How to configure your Azure cloud service application to allow remote desktop connections through Visual Studio.

+Remote Desktop enables you to access the desktop of a role running in Azure, using Remote Desktop Protocol (RDP). You can use a Remote Desktop connection to troubleshoot and diagnose problems with your application while it runs.

+With Visual Studio 2017 version 15.5 and later, we recommend you avoid enabling Remote Desktop through the publish wizard unless you're working as a single developer. For any situation in which multiple developers open the project, you should instead enable Remote Desktop through the Azure portal, through PowerShell, or from a release pipeline in a continuous deployment workflow. This recommendation is due to a change in how Visual Studio communicates with Remote Desktop on the cloud service virtual machine (VM), as is explained in this article.

+7. Choose a date on which the account will expire. An expired account automatically blocks further Remote Desktop connections.

+8. After you provide all the required information, select **OK**. Visual Studio adds the Remote Desktop settings to your project's `.cscfg` and `.csdef` files, including the password that's encrypted using the chosen certificate.

+This recommendation is due to a change in how Visual Studio 2017 version 15.5 and later communicates with the cloud service VM. When you enable Remote Desktop through the publish wizard, earlier versions of Visual Studio communicate with the VM through the "RDP plugin." Visual Studio 2017 version 15.5 and later communicates instead using the "RDP extension" that is more secure and more flexible. This change also aligns with the fact that the Azure portal and PowerShell methods to enable Remote Desktop also use the RDP extension.

+When Visual Studio communicates with the RDP extension, it transmits a plain text password over Transport Layer Security (TLS). However, the project's configuration files store only an encrypted password, which can be decrypted into plain text only with the local certificate that was originally used to encrypt it.

+However, if you or other developers want to deploy the cloud service project from different computers, then those other computers lack the necessary certificate to decrypt the password. As a result, you see the following error message:

+Applying remote desktop protocol extension.

+If you're sharing the project with a team, then it's best to clear the option in the publish wizard and instead enable Remote Desktop directly through the [Azure portal](cloud-services-role-enable-remote-desktop-new-portal.md) or by using [PowerShell](cloud-services-role-enable-remote-desktop-powershell.md).

+1. Set **Script Type** to "Inline" and paste the following below into the **Inline Script** field. (You can also create a `.ps1` file in your project with this script, set **Script Type** to "Script File Path", and set **Script Path** to point to the file.)

+After you publish your cloud service on Azure and enable Remote Desktop, you can use Visual Studio Server Explorer to log into the cloud service VM:

+3. Enter the user name and password that you created previously. You're now signed into your remote session.

+## Next steps

+* [How to Configure Cloud Services](cloud-services-how-to-configure-portal.md)

+When you create a worker role, you extend the [RoleEntryPoint](/previous-versions/azure/reference/ee758619(v=azure.100)) class, which provides methods for you to override that let you respond to lifecycle events. For web roles, this class is optional, so you must use it to respond to lifecycle events.

+The [RoleEntryPoint](/previous-versions/azure/reference/ee758619(v=azure.100)) class includes methods that are called by Azure when it **starts**, **runs**, or **stops** a web or worker role. You can optionally override these methods to manage role initialization, role shut down sequences, or the execution thread of the role.

+* The [OnStart](/previous-versions/azure/reference/ee772851(v=azure.100)) method returns a boolean value, so it's possible to return **false** from this method.

+ If an exception occurs within one of the lifecycle methods, Azure raises the [UnhandledException](/dotnet/api/system.appdomain.unhandledexception) event, and then the process is terminated. After your role goes offline, Azure restarts it. When an unhandled exception occurs, the [Stopping](/previous-versions/azure/reference/ee758136(v=azure.100)) event isn't raised, and the **OnStop** method isn't called.

+If your role doesn't start, or is recycling between the initializing, busy, and stopping states, your code may be throwing an unhandled exception within one of the lifecycle events each time the role restarts. In this case, use the [UnhandledException](/dotnet/api/system.appdomain.unhandledexception) event to determine the cause of the exception and handle it appropriately. Your role may also be returning from the [Run](/previous-versions/azure/reference/ee772746(v=azure.100)) method, which causes the role to restart. For more information about deployment states, see [Common Issues Which Cause Roles to Recycle](cloud-services-troubleshoot-common-issues-which-cause-roles-recycle.md).

+The **OnStart** method is called when your role instance is brought online by Azure. While the OnStart code is executing, the role instance is marked as **Busy** and the load balancer doesn't direct any external traffic to it. You can override this method to perform initialization work, such as implementing event handlers and starting [Azure Diagnostics](cloud-services-how-to-monitor.md).

+The **OnStop** method is called after Azures takes a role instance offline and before the process exits. You can override this method to call code required for your role instance to cleanly shut down.

+Overriding the **Run** method isn't required; the default implementation starts a thread that sleeps forever. If you do override the **Run** method, your code should block indefinitely. If the **Run** method returns, the role is automatically recycled; in other words, Azure raises the **Stopping** event and calls the **OnStop** method so that your shutdown sequences may be executed before the role is taken offline.

+You can use the ASP.NET lifecycle methods, in addition to the methods provided by the **RoleEntryPoint** class, to manage initialization and shutdown sequences for a web role. This approach may be useful for compatibility purposes if you're porting an existing ASP.NET application to Azure. The ASP.NET lifecycle methods are called from within the **RoleEntryPoint** methods. The **Application\_Start** method is called after the **RoleEntryPoint.OnStart** method finishes. The **Application\_End** method is called before the **RoleEntryPoint.OnStop** method is called.

+This article describes the available sizes and options for Cloud Service role instances (web roles and worker roles). It also provides deployment considerations to be aware of when planning to use these resources. Each size has an ID that you put in your [service definition file](cloud-services-model-and-package.md#csdef). Prices for each size are available on the [Cloud Services Pricing](https://azure.microsoft.com/pricing/details/cloud-services/) page.

+> To see related Azure limits, visit [Azure Subscription and Service Limits, Quotas, and Constraints](../azure-resource-manager/management/azure-subscription-service-limits.md)

+* Dv3-series, Dv2-series, a follow-on to the original D-series, features a more powerful CPU. The Dv2-series CPU is about 35% faster than the D-series CPU. It bases itself on the latest generation 2.4 GHz Intel Xeon® E5-2673 v3 (Haswell) processor, and with the Intel Turbo Boost Technology 2.0, can go up to 3.1 GHz. The Dv2-series has the same memory and disk configurations as the D-series.

+* The A-series VMs can be deployed on various hardware types and processors. The size is throttled based on the hardware to offer consistent processor performance for the running instance, regardless of the deployment scenario hardware. To determine the physical hardware on which this size is deployed, query the virtual hardware from within the Virtual Machine.

+* The A0 size is over-subscribed on the physical hardware. For this specific size only, other customer deployments may affect the performance of your running workload. We outline the expected baseline of relative performance, subject to an approximate variability of 15 percent, later in the article.

+* The A8-A11 and H-series sizes are also known as *compute-intensive instances*. The hardware that runs these sizes is designed and optimized for compute-intensive and network-intensive applications, including high-performance computing (HPC) cluster applications, modeling, and simulations. The A8-A11 series uses Intel Xeon E5-2670 @ 2.6 GHz and the H-series uses Intel Xeon E5-2667 v3 @ 3.2 GHz. For detailed information and considerations about using these sizes, see [High performance compute virtual machine (VM) sizes](../virtual-machines/sizes-hpc.md?toc=%2fazure%2fvirtual-machines%2fwindows%2ftoc.json).

+We created the concept of the Azure Compute Unit (ACU) to provide a way of comparing compute (CPU) performance across Azure SKUs and to identify which SKU is most likely to satisfy your performance needs. ACU is currently standardized on a Small (Standard_A1) VM being 100. Following that sandard, all other SKUs represent approximately how much faster that SKU can run a standard benchmark.

+* Storage capacity is shown in units of GiB or 1024^3 bytes. When comparing disks measured in GB (1000^3 bytes) to disks measured in GiB (1024^3), remember that capacity numbers given in GiB may appear smaller. For example, 1023 GiB = 1098.4 GB

+* Maximum network bandwidth is the maximum aggregated bandwidth allocated and assigned per VM type. The maximum bandwidth provides guidance for selecting the right VM type to ensure adequate network capacity is available. When moving between Low, Moderate, High and Very High, the throughput increases accordingly. Actual network performance depends on many factors including network and application loads, and application network settings.

+Here's an example for setting the role size to be Standard_D2 for a Web Role instance:

+As the nature of your workload changes or new VM sizes become available, you may want to change the size of your role. To do so, you must change the VM size in your service definition file (as previously shown), repackage your Cloud Service, and deploy it.

+You can use PowerShell or the REST API to get a list of sizes. The REST API is documented [here](/previous-versions/azure/reference/dn469422(v=azure.100)). The following code is a PowerShell command that lists all the sizes available for Cloud Services.

+* Learn about [Azure subscription and service limits, quotas, and constraints](../azure-resource-manager/management/azure-subscription-service-limits.md).

+This article provides some examples of common startup tasks you may want to perform in your cloud service. You can use startup tasks to perform operations before a role starts. Operations that you might want to perform include installing a component, registering Component Object Model (COM) components, setting registry keys, or starting a long running process.

+The [AppCmd.exe](/previous-versions/windows/it-pro/windows-server-2012-R2-and-2012/jj635852(v=ws.11)) command-line tool can be used to manage Internet Information Service (IIS) settings at startup on Azure. *AppCmd.exe* provides convenient, command-line access to configuration settings for use in startup tasks on Azure. When you use *AppCmd.exe*, Website settings can be added, modified, or removed for applications and sites.

+* Startup tasks fail if they return a nonzero exit code or **errorlevel**. For example, when *AppCmd.exe* generates an error.

+It's a good practice to check the **errorlevel** after calling *AppCmd.exe*, which is easy to do if you wrap the call to *AppCmd.exe* with a *.cmd* file. If you detect a known **errorlevel** response, you can ignore it, or pass it back.

+The errorlevel values returned by *AppCmd.exe* are listed in the winerror.h file and can also be seen on the [Microsoft Developer Network (MSDN)](/windows/desktop/Debug/system-error-codes--0-499-).

+In Azure, there are effectively two firewalls. The first firewall controls connections between the virtual machine and the outside world. The [EndPoints] element in the [ServiceDefinition.csdef] file controls this firewall.

+The second firewall controls connections between the virtual machine and the processes within that virtual machine. You can control this firewall from the `netsh advfirewall firewall` command-line tool.

+Azure creates firewall rules for the processes started within your roles. For example, when you start a service or program, Azure automatically creates the necessary firewall rules to allow that service to communicate with the Internet. However, if you create a service started by a process outside your role (like a COM+ service or a Windows Scheduled Task), you need to manually create a firewall rule to allow access to that service. These firewall rules can be created by using a startup task.

+To add the firewall rule, you must use the appropriate `netsh advfirewall firewall` commands in your startup batch file. In this example, the startup task requires security and encryption for Transmission Control Protocol (TCP) port 80.

+You can restrict an Azure web role access to a set of specified IP addresses by modifying your IIS **web.config** file. You also need to use a command file that unlocks the **ipSecurity** section of the **ApplicationHost.config** file.

+To do unlock the **ipSecurity** section of the **ApplicationHost.config** file, create a command file that runs at role start. Create a folder at the root level of your web role called **startup** and, within this folder, create a batch file called **startup.cmd**. Add this file to your Visual Studio project and set the properties to **Copy Always** to ensure you include it in your package.

+Windows PowerShell scripts can't be called directly from the [ServiceDefinition.csdef] file, but they can be invoked from within a startup batch file.

+PowerShell (by default) doesn't run unsigned scripts. Unless you sign your script, you need to configure PowerShell to run unsigned scripts. To run unsigned scripts, the **ExecutionPolicy** must be set to **Unrestricted**. The **ExecutionPolicy** setting that you use is based on the version of Windows PowerShell.

+You can use a local storage resource to store files created by your startup task that your application later accesses.

+You can have your startup task perform different steps when it's operating in the cloud compared to when it is in the compute emulator. For example, you may want to use a fresh copy of your SQL data only when running in the emulator. Or you may want to do some performance optimizations for the cloud that you don't need to do when running in the emulator.

+The task can now check the **%ComputeEmulatorRunning%** environment variable to perform different actions based on whether the role is running in the cloud or the emulator. Here's a .cmd shell script that checks for that environment variable.

+The role may recycle without a reboot causing your startup tasks to run again. There's no flag to indicate that a task already ran on the host virtual machine (VM). You may have some tasks where it doesn't matter that they run multiple times. However, you may run into a situation where you need to prevent a task from running more than once.

+The simplest way to detect that a task has already run is to create a file in the **%TEMP%** folder when the task is successful and look for it at the start of the task. Here's a sample cmd shell script that does that for you.

+Visual Studio doesn't provide a debugger to step through batch files, so it's good to get as much data on the operation of batch files as possible. Logging the output of batch files, both **stdout** and **stderr**, can give you important information when trying to debug and fix batch files. To log both **stdout** and **stderr** to the StartupLog.txt file in the directory pointed to by the **%TEMP%** environment variable, add the text `>> "%TEMP%\\StartupLog.txt" 2>&1` to the end of specific lines you want to log. For example, to execute setup.exe in the **%PathToApp1Install%** directory: `"%PathToApp1Install%\setup.exe" >> "%TEMP%\StartupLog.txt" 2>&1`

+You may find it annoying though to use `>> "%TEMP%\StartupLog.txt" 2>&1` on the end of each startup task. You can enforce task logging by creating a wrapper that handles logging for you. This wrapper calls the real batch file you want to run. Any output from the target batch file redirects to the *Startuplog.txt* file.

+With **simple** startup tasks, you can set the order in which the tasks run by the order in which the tasks are listed in the ServiceDefinition.csdef file. If a **simple** task ends with a nonzero exit code, then the startup procedure stops and the role doesn't start.

+The difference between **background** startup tasks and **foreground** startup tasks is that **foreground** tasks keep the role running until the **foreground** task ends. This structure means that if the **foreground** task hangs or crashes, the role remains unrecycled until the **foreground** task is forced closed. For this reason, **background** tasks are recommended for asynchronous startup tasks unless you need that feature of the **foreground** task.

+The role only starts if the **errorlevel** from each of your simple startup task is zero. Not all programs set the **errorlevel** (exit code) correctly, so the batch file should end with an `EXIT /B 0` if everything ran correctly.

+A missing `EXIT /B 0` at the end of a startup batch file is a common cause of roles that don't start.

+Not all role recycles include a reboot, but all role recycles include running all startup tasks. This design means that startup tasks must be able to run multiple times between reboots without any problems, which is discussed in the [preceding section](#detect-that-your-task-has-already-run).

+description: Startup tasks help prepare your cloud service environment for your app. This article teaches you how startup tasks work and how to make them

+You can use startup tasks to perform operations before a role starts. Operations that you might want to perform include installing a component, registering Component Object Model (COM) components, setting registry keys, or starting a long running process.

+Startup tasks are actions taken before your roles begin. The [ServiceDefinition.csdef] file defines startup tasks by using the [Task] element within the [Startup] element. Frequently startup tasks are batch files, but they can also be console applications, or batch files that start PowerShell scripts.

+Environment variables pass information into a startup task, and local storage can be used to pass information out of a startup task. For example, an environment variable can specify the path to a program you want to install, and files can be written to local storage. From there, your roles can read the files.

+Startup tasks can also be executed several times between reboots. For example, the startup task runs each time the role recycles, and role recycles may not always include a reboot. Startup tasks should be written in a way that allows them to run several times without problems.

+Startup tasks must end with an **errorlevel** (or exit code) of zero for the startup process to complete. If a startup task ends with a nonzero **errorlevel**, the role fails to start.

+1. The instance is marked as **Starting** and doesn't receive traffic.

+3. The role host process is started and the site is created in Internet Information Services (IIS).

+Startup tasks are defined in the [ServiceDefinition.csdef] file, in the **Task** element. The **commandLine** attribute specifies the name and parameters of the startup batch file or console command, the **executionContext** attribute specifies the privilege level of the startup task, and the **taskType** attribute specifies how the task executes.

+* Frequently this attribute is the filename of a .cmd or .bat batch file.

+* The task is relative to the AppRoot\\Bin folder for the deployment. Environment variables aren't expanded in determining the path and file of the task. If environment expansion is required, you can create a small .cmd script that calls your startup task.

+ The startup task runs with administrator privileges. These privileges allow startup tasks to install programs, make IIS configuration changes, perform registry changes, and other administrator level tasks, without increasing the privilege level of the role itself.

+ Tasks are executed synchronously, one at a time, in the order specified in the [ServiceDefinition.csdef] file. When one **simple** startup task ends with an **errorlevel** of zero, the next **simple** startup task is executed. If there are no more **simple** startup tasks to execute, then the role itself starts.

+ Tasks are executed asynchronously, in parallel with the startup of the role. The key difference between a **foreground** and a **background** task is that a **foreground** task prevents the role from recycling or shutting down until the task ends. The **background** tasks don't have this restriction.

+Environment variables are a way to pass information to a startup task. For example, you can put the path to a blob that contains a program to install, or port numbers that your role uses, or settings to control features of your startup task.

+Static environment variables use the **value** attribute of the [Variable] element. The preceding example creates the environment variable **MyVersionNumber** which has a static value of "**1.0.0.0**". Another example would be to create a **StagingOrProduction** environment variable, which you can manually set to values of "**staging**" or "**production**" to perform different startup actions based on the value of the **StagingOrProduction** environment variable.

+Environment variables based on members of the RoleEnvironment class don't use the **value** attribute of the [Variable] element. Instead, the [RoleInstanceValue] child element, with the appropriate **XPath** attribute value, are used to create an environment variable based on a specific member of the [RoleEnvironment] class. Values for the **XPath** attribute to access various [RoleEnvironment] values can be found [here](cloud-services-role-config-xpath.md).

+If a role in your application relies on any assembly that isn't part of the .NET Framework or the Azure managed library, you must explicitly include that assembly in the application package. Keep in mind that other Microsoft frameworks aren't available on Azure by default. If your role relies on such a framework, you must add those assemblies to the application package.

+Before you build and package your application, verify the following statements are true:

+* If using Visual studio, make sure the **Copy Local** property is set to **True** for each referenced assembly in your project that isn't part of the Azure SDK or the .NET Framework.

+* Make sure the web.config file doesn't reference any unused assemblies in the compilation element.

+* The **Build Action** of every .cshtml file is set to **Content**. This setting ensures that the files appear correctly in the package and enables other referenced files to appear in the package.

+Azure is a 64-bit environment. Therefore, .NET assemblies compiled for a 32-bit target aren't compatible with Azure.

+Any exceptions thrown by the methods of the [RoleEntryPoint] class, which includes the [OnStart], [OnStop], and [Run] methods, are unhandled exceptions. If an unhandled exception occurs in one of these methods, the role recycles. If the role is recycling repeatedly, it may be throwing an unhandled exception each time it tries to start.

+To ensure that your `DiagnosticsConnectionString` setting is correct before you deploy your application package to Azure, verify the following statements are true:

+ By default, this setting points to the emulated storage account, so you must explicitly change this setting before you deploy your application package. If you don't change this setting, an exception is thrown when the role instance attempts to start the diagnostic monitor. This event may cause the role instance to recycle indefinitely.

+ If you're developing your application by using Azure Tools for Microsoft Visual Studio, you can use the property pages to set this value.

+## Exported certificate doesn't include private key

+To run a web role under Transport Layer Security (TLS), you must ensure that your exported management certificate includes the private key. If you use the *Windows Certificate Manager* to export the certificate, be sure to select **Yes** for the **Export the private key** option. The certificate must be exported in the .pfx format, which is the only format currently supported.

+In this article, you troubleshoot allocation failures where Azure Cloud services (classic) can't deploy because of allocation constraints.

+When you inspect the logs of your Cloud service (classic), you see the following exception:

+|ConstrainedAllocationFailed |Azure operation '`{Operation ID}`' failed with code Compute.ConstrainedAllocationFailed. Details: Allocation failed; unable to satisfy constraints in request. The requested new service deployment is bound to an Affinity Group, or it targets a Virtual Network, or there's an existing deployment under this hosted service. Any of these conditions constrains the new deployment to specific Azure resources. Retry later or try reducing the virtual machine (VM) size or number of role instances. Alternatively, if possible, remove the constraints or try deploying to a different region.|

+Over time, the resources in this cluster may become fully utilized. If a Cloud service (classic) makes an allocation request for more resources when insufficient resources are available in the pinned cluster, the request results in an allocation failure. For more information, see the [allocation failure common issues](cloud-services-allocation-failures.md#common-issues).

+Existing cloud services are *pinned* to a cluster. Any further deployments for the Cloud service (classic) happen in the same cluster.

+If your Azure issue isn't addressed in this article, visit the Azure forums on [the Microsoft Developer Network (MSDN) and Stack Overflow](https://azure.microsoft.com/support/forums/). You can post your issue in these forums, or post to [@AzureSupport on Twitter](https://twitter.com/AzureSupport). You also can submit an Azure support request. To submit a support request, on the [Azure support](https://azure.microsoft.com/support/options/) page, select *Get support*.

+The standard Windows environment variables TEMP and TMP are available to code that is running in your application. Both TEMP and TMP point to a single directory that has a maximum size of 100 MB. Any data stored in this directory isn't persisted across the lifecycle of the cloud service. If the role instances in a cloud service are recycled, the directory is cleaned.

+* In the Azure portal, choose the deployment of your cloud service, select **All settings**, and then select **Properties**.

+## Problem: I can't access my website, but my deployment is started and all role instances are ready

+The website URL link shown in the portal doesn't include the port. The default port for websites is 80. If your application is configured to run in a different port, you must add the correct port number to the URL when accessing the website.

+1. In the Azure portal, choose the deployment of your cloud service.

+3. If the port isn't 80, add the correct port value to the URL when you access the application. To specify a nondefault port, type the URL, followed by a colon (:), followed by the port number, with no spaces.

+Service healing occurs automatically when Azure detects problem nodes and therefore moves role instances to new nodes. When these moves occur, you might see your role instances recycling automatically. To find out if service healing occurred:

+1. In the Azure portal, choose the deployment of your cloud service.

+Roles recycle roughly once per month during host-OS and guest-OS updates.

+## Problem: I can't do a VIP swap and receive an error

+A VIP swap isn't allowed if a deployment update is in progress. Deployment updates can occur automatically when:

+* A new guest operating system is available and you configured for automatic updates.

+1. In the Azure portal, choose the deployment of your cloud service.

+2. In the **Properties** pane of the Azure portal, look at the value of **Status**. If it's **Ready**, then check **Last operation** to see if one recently happened that might prevent the VIP swap.

+This condition could indicate a problem with your application code, package, or configuration file. In that case, you should be able to see the status changing every few minutes and the Azure portal may say something like **Recycling**, **Busy**, or **Initializing**. This fluctuation of status indicates that there's something wrong with the application that is keeping the role instance from running.

+1. In the Azure portal, choose the role instance.

+ * If the role instance recently stopped (you can check the value of **Abort count**), the deployment could be updating. Wait to see if the role instance resumes functioning on its own.

+In this article, you troubleshoot allocation failures where the fabric controller can't allocate when deploying an Azure Cloud service (classic).

+When you inspect the logs of your Cloud service (classic), you see the following exception:

+The first time you deploy a Cloud service (classic), the cluster is unselected, so the cloud service isn't *pinned*. Azure may have a deployment failure because:

+- You selected a particular size that isn't available in the region.

+Existing cloud services are *pinned* to a cluster. Any further deployments for the Cloud service (classic) happen in the same cluster.

+If your Azure issue isn't addressed in this article, visit the Azure forums on [the Microsoft Developer Network (MSDN) and Stack Overflow](https://azure.microsoft.com/support/forums/). You can post your issue in these forums, or post to [@AzureSupport on Twitter](https://twitter.com/AzureSupport). You also can submit an Azure support request. To submit a support request, on the [Azure support](https://azure.microsoft.com/support/options/) page, select *Get support*.

+When you inspect the logs of your Cloud service (classic), you see the following exception:

+There's a capacity issue with the region or cluster that you're deploying to. The `LocationNotFoundForRoleSize` exception occurs when the resource SKU you selected, the virtual machine size, isn't available for the region specified.

+In this scenario, you should select a different region or SKU for your Cloud service (classic) deployment. Before you deploy or upgrade your Cloud service (classic), determine which SKUs are available in a region or availability zone. Use the following the [Azure CLI](#list-skus-in-region-using-azure-cli), [PowerShell](#list-skus-in-region-using-powershell), or [REST API](#list-skus-in-region-using-rest-api) processes.

+For more allocation failure solutions and to better understand how allocation failures occur:

+In this article, you troubleshoot over constrained allocation failures that prevent deployment of Azure Cloud Services (classic).

+|OverconstrainedAllocationRequest |The virtual machine (VM) size (or combination of VM sizes) required by this deployment can't be provisioned due to deployment request constraints. If possible, try relaxing constraints such as virtual network bindings. Also try deploying to a hosted service with no other deployment in it and to a different affinity group or with no affinity group. You can try deploying to a different region altogether.|

+The first time you deploy a Cloud service (classic), the cluster is unselected, so the cloud service isn't *pinned*. Azure may have a deployment failure because:

+- You selected a particular size that isn't available in the region.

+Existing cloud services are *pinned* to a cluster. Any further deployments for the Cloud service (classic) happen in the same cluster.

+If your Azure issue isn't addressed in this article, visit the Azure forums on [the Microsoft Developer Network (MSDN) and Stack Overflow](https://azure.microsoft.com/support/forums/). You can post your issue in these forums, or post to [@AzureSupport on Twitter](https://twitter.com/AzureSupport). You also can submit an Azure support request. To submit a support request, on the [Azure support](https://azure.microsoft.com/support/options/) page, select *Get support*.

+Unresponsive roles and roles that are cycling between **Initializing**, **Busy**, and **Stopping** states can be caused by missing dynamic link libraries (DLLs) or assemblies.

+* Your role instance moved to **Ready** but if you navigate to your web application, the page doesn't appear.

+When you navigate to a website deployed in a web role, and the browser displays a server error similar to the following, it may indicate a DLL is missing.

+Once the service redeploys, you see an error message with the name of the missing assembly or DLL.

+Navigating to the website now returns more explicit error messages:

+4. Copy the .csx folder and .cscfg file to the computer you're using to debug the issues.

+7. When the role starts, you see detailed error information in Internet Explorer. You can also use standard Windows troubleshooting tools to further diagnose the problem.

+6. Choose **View IntelliTrace logs**. The **IntelliTrace Summary** opens.

+7. Locate the exceptions section of the summary. If there are exceptions, the section is labeled **Exception Data**.

+3. Select the assembly identified in the error.

+Once you verify all errors are corrected, you can deploy the service without checking the **Enable IntelliTrace for .NET 4 roles** check box.

+The process to update a cloud service, including both its roles and guest OS, takes three steps. First, the binaries and configuration files for the new cloud service or OS version must be uploaded. Next, Azure reserves compute and network resources for the cloud service based on the requirements of the new cloud service version. Finally, Azure performs a rolling upgrade to incrementally update the tenant to the new version or guest OS, while preserving your availability. This article discusses the details of this last step ΓÇô the rolling upgrade.

+Azure organizes your role instances into logical groupings called upgrade domains (UD). Upgrade domains (UD) are logical sets of role instances that are updated as a group. Azure updates a cloud service one UD at a time, which allows instances in other UDs to continue serving traffic.

+Your service must define at least two instances of a role for that role to be updated in-place without downtime. If the service consists of only one instance of one role, your service is unavailable until the in-place update finishes.

+This article covers the following information about Azure updates:

+| Changes permitted to hosting, services, and roles | In-place update | Staged (VIP swap) | Delete and redeploy |

+The following items aren't supported during an update:

+If you make other updates to your service's definition, such as decreasing the size of local resource, you must perform a VIP swap update instead. For more information, see [Swap Deployment](/previous-versions/azure/reference/ee460814(v=azure.100)).

+You can decide whether you want to update all of the roles in your service or a single role in the service. In either case, all instances of each role that is being upgraded and belong to the first upgrade domain are stopped, upgraded, and brought back online. Once they're back online, the instances in the second upgrade domain are stopped, upgraded, and brought back online. A cloud service can have at most one upgrade active at a time. The upgrade is always performed against the latest version of the cloud service.

+The following diagram illustrates how the upgrade proceeds if you upgrade all of the roles in the service:

+This next diagram illustrates how the update proceeds if you upgrade only a single role:

+During an automatic update, the Azure Fabric Controller periodically evaluates the health of the cloud service to determine when itΓÇÖs safe to walk the next UD. This health evaluation is performed on a per-role basis and considers only instances in the latest version (that is, instances from UDs that already walked). It verifies that, for each role, a minimum number of role instances achieved a satisfactory terminal state.

+The Fabric Controller waits 30 minutes for each role instance to reach a Started state. If the timeout duration elapses, the Fabric Controller will continue walking to the next role instance.

+When you upgrade a service from a single instance to multiple instances, Azure brings your services down while the upgrade is performed. The service level agreement guaranteeing service availability only applies to services that are deployed with more than one instance. The following list describes how each Azure service upgrade scenario affects the data on each drive:

+|Virtual machine (VM) reboot|Preserved|Preserved|Preserved|

+In the preceding list, the E: drive represents the roleΓÇÖs root drive, and shouldn't be hard-coded. Instead, use the **%RoleRoot%** environment variable to represent the drive.

+Azure provides flexibility in managing services during an update by letting you initiate more operations on a service, after the Azure Fabric Controller accepts the initial update request. A rollback can only be performed when an update (configuration change) or upgrade is in the **in progress** state on the deployment. An update or upgrade is considered to be in-progress as long as there is at least one instance of the service that remains unupdated to the new version. To test whether a rollback is allowed, check the value of the RollbackAllowed flag is set to true. [Get Deployment](/previous-versions/azure/reference/ee460804(v=azure.100)) and [Get Cloud Service Properties](/previous-versions/azure/reference/ee460806(v=azure.100)) operations return the RollbackAllowed flag for your reference.

+* Any role instances that remain unupdated or unupgraded to the new version aren't updated or upgraded, because those instances are already running the target version of the service.

+* Any role instances that already updated or upgraded to the new version of the service package (\*.cspkg) file or the service configuration (\*.cscfg) file (or both files) are reverted to the preupgrade version of these files.

+The following features provide this functionality:

+* The [Rollback Update Or Upgrade](/previous-versions/azure/reference/hh403977(v=azure.100)) operation, which can be called on a configuration update (triggered by calling [Change Deployment Configuration](/previous-versions/azure/reference/ee460809(v=azure.100))) or an upgrade (triggered by calling [Upgrade Deployment](/previous-versions/azure/reference/ee460793(v=azure.100))) as long as there is at least one instance in the service that remains unupdated to the new version.

+ In order to perform a rollback, you don't have to check both the Locked and the RollbackAllowed elements. It suffices to confirm that RollbackAllowed is set to true. These elements are only returned if these methods are invoked by using the request header set to ΓÇ£x-ms-version: 2011-10-01ΓÇ¥ or a later version. For more information about versioning headers, see [the versioning of the classic deployment model](/previous-versions/azure/gg592580(v=azure.100)).

+There are some situations where a rollback of an update or upgrade isn't supported, these situations are as follows:

+* Reduction in local resources - If the update increases the local resources for a role the Azure platform doesn't allow rolling back.

+* Quota limitations - If the update was a scale down operation you may no longer have sufficient compute quota to complete the rollback operation. Each Azure subscription has a quota associated with it. The quota specifies the maximum number of cores that all hosted services belonging to that subscription can consume. If performing a rollback of a given update would put your subscription over quota, then that rollback won't be enabled.

+* Race condition - If the initial update completes, a rollback isn't possible.

+An example of when the rollback of an update might be useful is if you use the [Upgrade Deployment](/previous-versions/azure/reference/ee460793(v=azure.100)) operation in manual mode to control the rate at which a major in-place upgrade rolls out to your Azure hosted service.

+During the rollout of the upgrade, you call [Upgrade Deployment](/previous-versions/azure/reference/ee460793(v=azure.100)) in manual mode and begin to walk upgrade domains. If at some point, as you monitor the upgrade, you note some role instances in the first upgrade domains are unresponsive, you can call the [Rollback Update Or Upgrade](/previous-versions/azure/reference/hh403977(v=azure.100)) operation on the deployment. This operation leaves untouched the instances that remain unupgraded and rolls back upgraded instances to the previous service package and configuration.

+In some cases, you may want to initiate multiple simultaneous mutating operations on an ongoing deployment. For example, you may perform a service update and, while the update rolls out across your service, you want to make some change, like rolling back the update, applying a different update, or even deleting the deployment. A case in which this scenario might arise is if a service upgrade contains buggy code that causes an upgraded role instance to repeatedly crash. In this case, the Azure Fabric Controller is unable to make progress in applying that upgrade because an insufficient number of instances in the upgraded domain are healthy. This state is referred to as a *stuck deployment*. You can unstick the deployment by rolling back the update or applying a fresh update over top of the failing one.

+Once the Azure Fabric Controller receives the initial request to update or upgrade the service, you can start subsequent mutating operations. That is, you don't have to wait for the initial operation to complete before you can start another mutating operation.

+Initiating a second update operation while the first update is ongoing plays out similarly to the rollback operation. If the second update is in automatic mode, the first upgrade domain upgrades immediately, possibly leading to instances from multiple upgrade domains being offline at the same time.

+Two operations, [Get Deployment](/previous-versions/azure/reference/ee460804(v=azure.100)) and [Get Cloud Service Properties](/previous-versions/azure/reference/ee460806(v=azure.100)), return the Locked flag. You can examine the Locked flag to determine whether you can invoke a mutating operation on a given deployment.

+In order to call the version of these methods that returns the Locked flag, you must set request header to ΓÇ£x-ms-version: 2011-10-01ΓÇ¥ or a later. For more information about versioning headers, see [the versioning of the classic deployment model](/previous-versions/azure/gg592580(v=azure.100)).

+For example, if your role has 10 instances, by default each upgrade domain contains two instances. If your role has 14 instances, then four of the upgrade domains contain three instances, and a fifth domain contains two.

+The following diagram illustrates how the roles in a service containing two roles are distributed when the service defines two upgrade domains. The service is running eight instances of the web role and nine instances of the worker role.

+ Title: Workflow of Microsoft Azure Virtual Machine (VM) Architecture | Microsoft Docs

+# Workflow of Microsoft Azure classic Virtual Machine (VM) Architecture

+**A**. RDFE / FFE is the communication path from the user to the fabric. RDFE (RedDog Front End) is the publicly exposed API that is the front end to the Management Portal and the classic deployment model API, such as Visual Studio, Azure MMC, and so on. All requests from the user go through RDFE. FFE (Fabric Front End) is the layer that translates requests from RDFE into fabric commands. All requests from RDFE go through the FFE to reach the fabric controllers.

+**C**. The Host Agent lives on the Host OS and is responsible for setting up Guest OS. It also handles communicating with Guest Agent (WindowsAzureGuestAgent) to update the role toward an intended goal state and do heartbeat checks with the Guest Agent. If Host Agent doesn't receive heartbeat response for 10 minutes, Host Agent restarts the Guest OS.

+**D**. WindowsAzureGuestAgent is responsible for the following tasks:

+* Configuring the Guest OS including firewall, ACLs, LocalStorage resources, service package and configuration, and certificates.

+* Setting up the SID for the user account that the role runs under.

+* Communicating the role status to the fabric.

+* Starting WaHostBootstrapper and monitoring it to make sure that the role is in goal state.

+* Reading the role configuration, and starting all the appropriate tasks and processes to configure and run the role.

+* Monitoring all its child processes.

+* Raising the StatusCheck event on the role host process.

+**F**. IISConfigurator runs if the role is configured as a Full IIS web role. It's responsible for:

+* Starting the standard IIS services

+* Configuring the rewrite module in the web configuration

+* Setting up the AppPool for the configured role in the service model

+* Setting up IIS logging to point to the DiagnosticStore LocalStorage folder

+* Configuring permissions and ACLs

+* The website resides in %roleroot%:\sitesroot\0, and the AppPool points to this location to run IIS.

+**G**. The role model defines startup tasks, and WaHostBootstrapper starts them. Startup tasks can be configured to run in the background asynchronously, and the host bootstrapper starts the startup task and then continue on to other startup tasks. Startup tasks can also be configured to run in Simple (default) mode. In Simple mode, the host bootstrapper waits for the startup task to finish running and return a success (0) exit code before continuing to the next startup task.

+**H**. These tasks are part of the SDK and are defined as plugins in the roleΓÇÖs service definition (.csdef). When expanded into startup tasks, the **DiagnosticsAgent** and **RemoteAccessAgent** are unique in that they each define two startup tasks, one regular and one that has a **/blockStartup** parameter. The normal startup task is defined as a Background startup task so that it can run in the background while the role itself is running. The **/blockStartup** startup task is defined as a Simple startup task so that WaHostBootstrapper waits for it to exit before continuing. The **/blockStartup** task waits for the regular task to finish initializing, and then it exits and allow the host bootstrapper to continue. This process is done so that diagnostics and RDP access can be configured before the role processes start, which is done through the /blockStartup task. This process also allows diagnostics and RDP access to continue running after the host bootstrapper finishes the startup tasks, which is done through the Normal task.

+**I**. WaWorkerHost is the standard host process for normal worker roles. This host process hosts all the roleΓÇÖs DLLs and entry point code, such as OnStart and Run.

+**K**. W3WP is the standard IIS worker process used if the role is configured to use Full IIS. This process runs the AppPool configured from IISConfigurator. Any RoleEnvironment events (such as StatusCheck and Changed) that are created here are raised in this process. RoleEnvironment events fire in both locations (WaIISHost and w3wp.exe) if you subscribe to events in both processes.

+1. A user makes a request, such as uploading ".cspkg" and ".cscfg" files, telling a resource to stop or making a configuration change, and so on. Requests can be made through the Azure portal or tools that use the classic deployment model API, such as the Visual Studio Publish feature. This request goes to RDFE to do all the subscription-related work and then communicate the request to FFE. The rest of these workflow steps are to deploy a new package and start it.

+7. WaHostBootstrapper reads the **Startup** tasks from E:\RoleModel.xml and begins executing startup tasks. WaHostBootstrapper waits until all Simple startup tasks finish and return a success message.

+9. WaHostBootstrapper starts the host process depending on the role type:

+ 1. **Worker Role**: WaWorkerHost.exe is started. WaHostBootstrapper executes the OnStart() method. After it returns, WaHostBootstrapper starts to execute the Run() method, and then simultaneously marks the role as Ready and puts it into the load balancer rotation (if InputEndpoints are defined). WaHostBootsrapper then goes into a loop of checking the role status.

+10. Incoming web requests to a Full IIS web role trigger IIS to start the W3WP process and serve the request, the same as it would in an on-premises IIS environment.

+This log contains changes to the service including starts, stops, and new configurations. If the service doesn't change, you can expect to see large gaps of time in this log file.

+This log contains status updates and heartbeat notifications and is updated every 2-3 seconds. This log contains a historic view of the status of the instance and tells you when the instance wasn't in the Ready state.

+Diagnostic data isn't permanently stored unless you transfer it to the Microsoft Azure Storage Emulator or to Azure Storage. Once in storage, it can be viewed with one of several available tools.

+For SDK 2.4 and earlier, you can request to transfer the diagnostic data programmatically and through the configuration file. The programmatic approach also allows you to do on-demand transfers.

+* **WADDirectoriesTable** ΓÇô Directories that the diagnostic monitor is monitoring. These directories include IIS logs, IIS failed request logs, and custom directories. The location of the blob log file is specified in the Container field and the name of the blob is in the RelativePath field. The AbsolutePath field indicates the location and name of the file as it existed on the Azure virtual machine.

+* **wad-control-container** ΓÇô (Only for SDK 2.4 and previous) Contains the XML configuration files that control the Azure diagnostics.

+* **"custom"** ΓÇô A custom container based on configuring directories that are monitored by the diagnostic monitor. WADDirectoriesTable specifies the name of this blob container.

+Several tools are available to view the data after it transfers to storage. For example:

+* Server Explorer in Visual Studio - If you installed the Azure Tools for Microsoft Visual Studio, you can use the Azure Storage node in Server Explorer to view read-only blob and table data from your Azure storage accounts. You can display data from your local storage emulator account and also from storage accounts you created for Azure. For more information, see [Browsing and Managing Storage Resources with Server Explorer](/visualstudio/azure/vs-azure-tools-storage-resources-server-explorer-browse-manage).

+* [Azure Management Studio](https://cerebrata.com/blog/introducing-azure-management-studio-and-azure-explorer) includes Azure Diagnostics Manager, which allows you to view, download, and manage the diagnostics data collected by the applications running on Azure.

+Open the **ApplicationInsights.config** file and find the **ApplicationInsights** > **TelemetryModules** element. Each `<Add>` child-element defines a type of telemetry to collect, along with its configuration. The performance counter telemetry module type is `Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.PerformanceCollectorModule, Microsoft.AI.PerfCounterCollector`. If this element is already defined, don't add it a second time. Each performance counter to collect is defined under a node named `<Counters>`. Here's an example that collects drive performance counters:

+Each performance counter is represented as an `<Add>` element under `<Counters>`. The `PerformanceCounter` attribute defines which performance counter to collect. The `ReportAs` attribute is the title to display in the Azure portal for the performance counter. Any performance counter you collect is put into a category named **Custom** in the portal. Unlike Azure Diagnostics, you can't set the interval these performance counters are collected and sent to Azure. With Application Insights, performance counters are collected and sent every minute.

+The performance counters you want to collect are defined in the **diagnostics.wadcfgx** file. Open this file in Visual Studio and find the **DiagnosticsConfiguration** > **PublicConfig** > **WadCfg** > **DiagnosticMonitorConfiguration** > **PerformanceCounters** element. Add a new **PerformanceCounterConfiguration** element as a child. This element has two attributes: `counterSpecifier` and `sampleRate`. The `counterSpecifier` attribute defines which system performance counter set (outlined in the previous section) to collect. The `sampleRate` value indicates how often that value is polled. As a whole, all performance counters are transferred to Azure according to the parent `PerformanceCounters` element's `scheduledTransferPeriod` attribute value.

+The period defined by the `sampleRate` attribute uses the XML duration data type to indicate how often the performance counter is polled. In the following example, the rate is set to `PT3M`, which means `[P]eriod[T]ime[3][M]inutes`: every three minutes.

+A new performance counter can be created and used by your code. Your code that creates a new performance counter must be running elevated, otherwise it fails. Your cloud service `OnStart` startup code can create the performance counter, requiring you to run the role in an elevated context. Or you can create a startup task that runs elevated and creates the performance counter. For more information about startup tasks, see [How to configure and run startup tasks for a cloud service](cloud-services-startup-tasks.md).

+As previously stated, the performance counters you want to collect are defined in the **diagnostics.wadcfgx** file. Open this file in Visual Studio and find the **DiagnosticsConfiguration** > **PublicConfig** > **WadCfg** > **DiagnosticMonitorConfiguration** > **PerformanceCounters** element. Add a new **PerformanceCounterConfiguration** element as a child. Set the `counterSpecifier` attribute to the category and name of the performance counter you created in your code.

+## Next steps

+Azure status reports on problems that affect a broad set of Azure customers. Resource Health gives you a personalized dashboard of the health of your resources. Resource Health shows all the times that your resources were unavailable because of Azure service problems. This data makes it easy for you to see if a Service Level Agreement (SLA) was violated.

+Resource health is reported at a deployment or role level. The health check happens at role instance level. We aggregate the status and report it on Role level. For example, if all role instances are available, then the role status is available. Similarly, we aggregate the health status of all roles and report it on deployment level. For example, if all roles are available, then deployment status becomes available.

+## Why I can't see health status for my staging slot deployment?

+Resource health checks only work for production slot deployment. Staging slot deployment isn't yet supported.

+No, health check only happens for role instances and it doesn't monitor Application health. For example, even if one out of three role instances are unhealthy, the application can still be available. RHC doesn't use [load balancer probes](../load-balancer/load-balancer-custom-probe-overview.md) or Guest agent probe. Therefore,

+Unavailable means the role instance isn't emitting a healthy signal to the platform. Check the role instance status for detailed explanation of why healthy signal isn't being emitted.

+Unknown means the aggregated health of the Cloud Service deployment can't be determined. Usually, unknown indicates one of the following scenarios:

+* There's no production deployment created for the Cloud Service

+* The deployment was newly created (and that Azure is starting to collect health events)

+* The platform is having issues collecting health events for this deployment.

+## Why does Role Instance Annotations mention VMs instead of Role Instances?

+Since Role Instances are, in essence, virtual machines (VMs), and the health check for VMs is reused for Role Instances, the VM term is used to represent Role Instances.

+| Unknown | We're currently unable to determine the health of this Cloud Service deployment |

+| Setting up Resource Health | Setting up Resource health for this resource. Resource health watches your Azure resources to provide details about ongoing and past events that affected them|

+| Degraded | Your Cloud Service deployment is degraded. We're working to automatically recover your Cloud Service deployment and to determine the source of the problem. No further action is required from you at this time |

+| Available and maybe impacted | Your Cloud Service deployment is running, however an ongoing Azure service outage may prevent you from connecting to it. Connectivity restores once the outage is resolved |

+| Unavailable and maybe impacted | An Azure service outage possibly affected the health of this Cloud Service deployment. Your Cloud Service deployment recovers automatically when the outage is resolved |

+| Unknown and maybe impacted | We're currently unable to determine the health of this Cloud Service deployment. This status could be a result of an ongoing Azure service outage that may be impacting this virtual machine, which recovers automatically when the outage is resolved |

+| Unknown | We're currently unable to determine the health of this virtual machine |

+| Setting up Resource Health | Setting up Resource health for this resource. Resource health watches your Azure resources to provide details about ongoing and past events that affected them |

+| Unavailable | Your virtual machine is unavailable. We're working to automatically recover your virtual machine and to determine the source of the problem. No further action is required from you at this time |

+| Degraded | Your virtual machine is degraded. We're working to automatically recover your virtual machine and to determine the source of the problem. No further action is required from you at this time |

+| Host server hardware failure | A fatal {HardwareCategory} failure on the host server affected this virtual machine. Azure redeploys your virtual machine to a healthy host server |

+| Migration scheduled due to degraded hardware | Azure identified that the host server has a degraded {0} that is predicted to fail soon. If feasible, we Live Migrate your virtual machine as soon as possible, or otherwise redeploy it after {1} UTC time. To minimize risk to your service, and in case the hardware fails before the system initiated migration occurs, we recommend you self-redeploy your virtual machine as soon as possible |

+| Available and maybe impacted | Your virtual machine is running, however an ongoing Azure service outage may prevent you from connecting to it. Connectivity restores once the outage is resolved |

+| Unavailable and maybe impacted | An Azure service outage possibly affected the health of this virtual machine. Your virtual machine recovers automatically when the outage is resolved |