+| `Active Tokens` | Usage | Total tokens minus cached tokens over a period of time. Applies to PTU and PTU-managed deployments. Use this metric to understand your TPS or TPM based utilization for PTUs and compare to your benchmarks for target TPS or TPM for your scenarios. | `ModelDeploymentName`,`ModelName`,`ModelVersion` |

+The batch transcription API (and [fast transcription API](./fast-transcription-create.md)) supports many different formats and codecs, such as:

+ Title: Use the fast transcription API - Speech service

+description: Learn how to use Azure AI Speech for fast transcriptions, where you submit audio get the transcription results much faster than real-time audio.

+# Customer intent: As a user who implements audio transcription, I want create transcriptions as quickly as possible.

+# Use the fast transcription API (preview) with Azure AI Speech

+> [!NOTE]

+> This feature is currently in public preview. This preview is provided without a service-level agreement, and is not recommended for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).

+>

+> Fast transcription API is only available via the speech to text REST API version 2024-05-15-preview. This preview version is subject to change and is not recommended for production use. It will be retired without notice 90 days after a successor preview version or the general availability (GA) of the API.

+Fast transcription API is used to transcribe audio files with returning results synchronously and much 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, subtitles, and edit.

+- Video dubbing

+> [!TIP]

+> Try out fast transcription in [Azure AI Studio](https://aka.ms/fasttranscription/studio).

+## Prerequisites

+- An Azure AI Speech resource in one of the regions where the fast transcription API is available. The supported regions are: Central India, East US, Southeast Asia, and West Europe. For more information about regions supported for other Speech service features, see [Speech service regions](./regions.md).

+- An audio file (less than 2 hours long and less than 200 MB in size) in one of the formats and codecs supported by the batch transcription API. For more information about supported audio formats, see [supported audio formats](./batch-transcription-audio-data.md#supported-audio-formats-and-codecs).

+## Use the fast transcription API

+The fast transcription API is a REST API that uses multipart/form-data to submit audio files for transcription. The API returns the transcription results synchronously.

+Construct the request body according to the following instructions:

+- Set the required `locales` property. This value should match the expected locale of the audio data to transcribe. The supported locales are: en-US, es-ES, es-MX, fr-FR, hi-IN, it-IT, ja-JP, ko-KR, pt-BR, and zh-CN. You can only specify one locale per transcription request.

+- Optionally, set the `profanityFilterMode` property to specify how to handle profanity in recognition results. Accepted values are `None` to disable profanity filtering, `Masked` to replace profanity with asterisks, `Removed` to remove all profanity from the result, or `Tags` to add profanity tags. The default value is `Masked`. The `profanityFilterMode` property works the same way as via the [batch transcription API](./batch-transcription.md).

+- Optionally, set the `channels` property to specify the zero-based indices of the channels to be transcribed separately. If not specified, multiple channels are merged and transcribed jointly. Only up to two channels are supported. If you want to transcribe the channels from a stereo audio file separately, you need to specify `[0,1]` here. Otherwise, stereo audio will be merged to mono, mono audio will be left as is, and only a single channel will be transcribed. In either of the latter cases, the output has no channel indices for the transcribed text, since only a single audio stream is transcribed.

+Make a multipart/form-data POST request to the `transcriptions` endpoint with the audio file and the request body properties. The following example shows how to create a transcription using the fast transcription API.

+- Replace `YourSubscriptionKey` with your Speech resource key.

+- Replace `YourServiceRegion` with your Speech resource region.

+- Replace `YourAudioFile` with the path to your audio file.

+- Set the form definition properties as previously described.

+```azurecli-interactive

+curl --location 'https://YourServiceRegion.api.cognitive.microsoft.com/speechtotext/transcriptions:transcribe?api-version=2024-05-15-preview' \

+--header 'Content-Type: multipart/form-data' \

+--header 'Accept: application/json' \

+--header 'Ocp-Apim-Subscription-Key: YourSubscriptionKey' \

+--form 'audio=@"YourAudioFile"' \

+--form 'definition="{

+ \"locales\":[\"en-US\"],

+ \"profanityFilterMode\": \"Masked\",

+ \"channels\": [0,1]}"'

+```

+The response will include `duration`, `channel`, and more. The `combinedPhrases` property contains the full transcriptions for each channel separately. For example, everything the first speaker said is in the first element of the `combinedPhrases` array, and everything the second speaker said is in the second element of the array.

+```json

+{

+ "duration": 185079,

+ "combinedPhrases": [

+ {

+ "channel": 0,

+ "text": "Hello. Thank you for calling Contoso. Who am I speaking with today? Hi, Mary. Are you calling because you need health insurance? Great. If you can answer a few questions, we can get you signed up in the Jiffy. So what's your full name? Got it. And what's the best callback number in case we get disconnected? Yep, that'll be fine. Got it. So to confirm, it's 234-554-9312. Excellent. Let's get some additional information for your application. Do you have a job? OK, so then you have a Social Security number as well. OK, and what is your Social Security number please? Sorry, what was that, a 25 or a 225? You cut out for a bit. Alright, thank you so much. And could I have your e-mail address please? Great. Uh That is the last question. So let me take your information and I'll be able to get you signed up right away. Thank you for calling Contoso and I'll be able to get you signed up immediately. One of our agents will call you back in about 24 hours or so to confirm your application. Absolutely. If you need anything else, please give us a call at 1-800-555-5564, extension 123. Thank you very much for calling Contoso. Uh Yes, of course. So the default is a digital membership card, but we can send you a physical card if you prefer. Uh, yeah. Absolutely. I've made a note on your file. You're very welcome. Thank you for calling Contoso and have a great day."

+ },

+ {

+ "channel": 1,

+ "text": "Hi, my name is Mary Rondo. I'm trying to enroll myself with Contuso. Yes, yeah, I'm calling to sign up for insurance. Okay. So Mary Beth Rondo, last name is R like Romeo, O like Ocean, N like Nancy D, D like Dog, and O like Ocean again. Rondo. I only have a cell phone so I can give you that. Sure, so it's 234-554 and then 9312. Yep, that's right. Uh Yes, I am self-employed. Yes, I do. Uh Sure, so it's 412256789. It's double two, so 412, then another two, then five. Yeah, it's maryrondo@gmail.com. So my first and last name at gmail.com. No periods, no dashes. That was quick. Thank you. Actually, so I have one more question. I'm curious, will I be getting a physical card as proof of coverage? uh Yes. Could you please mail it to me when it's ready? I'd like to have it shipped to, are you ready for my address? So it's 2660 Unit A on Maple Avenue SE, Lansing, and then zip code is 48823. Awesome. Thanks so much."

+ }

+ ],

+ "phrases": [

+ {

+ "channel": 0,

+ "offset": 720,

+ "duration": 480,

+ "text": "Hello.",

+ "words": [

+ {

+ "text": "Hello.",

+ "offset": 720,

+ "duration": 480

+ }

+ ],

+ "locale": "en-US",

+ "confidence": 0.9177142

+ },

+ {

+ "channel": 0,

+ "offset": 1200,

+ "duration": 1120,

+ "text": "Thank you for calling Contoso.",

+ "words": [

+ {

+ "text": "Thank",

+ "offset": 1200,

+ "duration": 200

+ },

+ {

+ "text": "you",

+ "offset": 1400,

+ "duration": 80

+ },

+ {

+ "text": "for",

+ "offset": 1480,

+ "duration": 120

+ },

+ {

+ "text": "calling",

+ "offset": 1600,

+ "duration": 240

+ },

+ {

+ "text": "Contoso.",

+ "offset": 1840,

+ "duration": 480

+ }

+ ],

+ "locale": "en-US",

+ "confidence": 0.9177142

+ },

+ {

+ "channel": 0,

+ "offset": 2320,

+ "duration": 1120,

+ "text": "Who am I speaking with today?",

+ "words": [

+ {

+ "text": "Who",

+ "offset": 2320,

+ "duration": 160

+ },

+ {

+ "text": "am",

+ "offset": 2480,

+ "duration": 80

+ },

+ {

+ "text": "I",

+ "offset": 2560,

+ "duration": 80

+ },

+ {

+ "text": "speaking",

+ "offset": 2640,

+ "duration": 320

+ },

+ {

+ "text": "with",

+ "offset": 2960,

+ "duration": 160

+ },

+ {

+ "text": "today?",

+ "offset": 3120,

+ "duration": 320

+ }

+ ],

+ "locale": "en-US",

+ "confidence": 0.9177142

+ },

+ // More transcription results removed for brevity

+ // {...},

+ {

+ "channel": 1,

+ "offset": 4480,

+ "duration": 1600,

+ "text": "Hi, my name is Mary Rondo.",

+ "words": [

+ {

+ "text": "Hi,",

+ "offset": 4480,

+ "duration": 400

+ },

+ {

+ "text": "my",

+ "offset": 4880,

+ "duration": 120

+ },

+ {

+ "text": "name",

+ "offset": 5000,

+ "duration": 120

+ },

+ {

+ "text": "is",

+ "offset": 5120,

+ "duration": 160

+ },

+ {

+ "text": "Mary",

+ "offset": 5280,

+ "duration": 240

+ },

+ {

+ "text": "Rondo.",

+ "offset": 5520,

+ "duration": 560

+ }

+ ],

+ "locale": "en-US",

+ "confidence": 0.8989456

+ },

+ {

+ "channel": 1,

+ "offset": 6080,

+ "duration": 1920,

+ "text": "I'm trying to enroll myself with Contuso.",

+ "words": [

+ {

+ "text": "I'm",

+ "offset": 6080,

+ "duration": 160

+ },

+ {

+ "text": "trying",

+ "offset": 6240,

+ "duration": 200

+ },

+ {

+ "text": "to",

+ "offset": 6440,

+ "duration": 80

+ },

+ {

+ "text": "enroll",

+ "offset": 6520,

+ "duration": 200

+ },

+ {

+ "text": "myself",

+ "offset": 6720,

+ "duration": 360

+ },

+ {

+ "text": "with",

+ "offset": 7080,

+ "duration": 120

+ },

+ {

+ "text": "Contuso.",

+ "offset": 7200,

+ "duration": 800

+ }

+ ],

+ "locale": "en-US",

+ "confidence": 0.8989456

+ },

+ // More transcription results removed for brevity

+ // {...},

+ ]

+}

+```

+## Related content

+- [Speech to text quickstart](./get-started-speech-to-text.md)

+- [Batch transcription API](./batch-transcription.md)

+## Fast transcription API (Preview)

+Fast transcription API is used to transcribe audio files with returning results synchronously and much 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, subtitles, and edit.

+- Video dubbing

+> [!NOTE]

+> Fast transcription API is only available via the speech to text REST API version 3.3.

+To get started with fast transcription, see [use the fast transcription API (preview)](fast-transcription-create.md).

+#### Fast transcription

+| Quota | Free (F0) | Standard (S0) |

+|--|--|--|

+| Maximum audio input file size | N/A | 200 MB |

+| Maximum audio length | N/A | 120 minutes per file |

+| Maximum requests per minute | N/A | 300 |

+In this overview, you learn about the benefits and capabilities of the speech to text feature of the Speech service, which is part of Azure AI services. Speech to text can be used for [real-time](#real-time-speech-to-text), [batch transcription](#batch-transcription-api), or [fast transcription](./fast-transcription-create.md) of audio streams into text.

+> To compare pricing of [real-time](#real-time-speech-to-text) to [batch transcription](#batch-transcription-api), see [Speech service pricing](https://azure.microsoft.com/pricing/details/cognitive-services/speech-services/).

+## Fast transcription (Preview)

+Fast transcription API is used to transcribe audio files with returning results synchronously and much 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, subtitles, and edit.

+- Video dubbing

+> [!NOTE]

+> Fast transcription API is only available via the speech to text REST API version 2024-05-15-preview and later.

+To get started with fast transcription, see [use the fast transcription API (preview)](fast-transcription-create.md).

+## Batch transcription API

+If you are using an endpoint with support for Entra ID, you can create your client as follows:

+```python

+import os

+from azure.ai.inference import ChatCompletionsClient

+from azure.identity import AzureDefaultCredential

+model = ChatCompletionsClient(

+ endpoint=os.environ["AZUREAI_ENDPOINT_URL"],

+ credential=AzureDefaultCredential(),

+)

+```

+For endpoint with support for Microsoft Entra ID, you can create your client as follows:

+```javascript

+import ModelClient from "@azure-rest/ai-inference";

+import { isUnexpected } from "@azure-rest/ai-inference";

+import { AzureDefaultCredential } from "@azure/identity";

+const client = new ModelClient(

+ process.env.AZUREAI_ENDPOINT_URL,

+ new AzureDefaultCredential()

+);

+```

+The following example shows a request passing the parameter `safe_prompt` supported by Mistral-Large, which isn't specified in the Azure AI Model Inference API.

+from azure.ai.inference.models import SystemMessage, UserMessage

+print(response.choices[0].message.content)

+> [!TIP]

+> When using Azure AI Inference SDK, using passing extra parameters using `model_extras` configures the request with `extra-parameters: pass-through` automatically for you.

+console.log(response.choices[0].message.content)

+> [!NOTE]

+> The default value for `extra-parameters` is `error` which returns an error if an extra parameter is indicated in the payload. Alternatively, you can set `extra-parameters: drop` to drop any unknown parameter in the request. Use this capability in case you happen to be sending requests with extra parameters that you know the model won't support but you want the request to completes anyway. A typical example of this is indicating `seed` parameter.

+from azure.ai.inference.models import SystemMessage, UserMessage, ChatCompletionsResponseFormat

+ Title: 'Create infrastructure for deploying a highly available PostgreSQL database on AKS'

+description: Create the infrastructure needed to deploy a highly available PostgreSQL database on AKS using the CloudNativePG operator.

+# Create infrastructure for deploying a highly available PostgreSQL database on AKS

+In this article, you create the infrastructure needed to deploy a highly available PostgreSQL database on AKS using the [CloudNativePG (CNPG)](https://cloudnative-pg.io/) operator.

+## Before you begin

+* Review the deployment overview and make sure you meet all the prerequisites in [How to deploy a highly available PostgreSQL database on AKS with Azure CLI][postgresql-ha-deployment-overview].

+* [Set environment variables](#set-environment-variables) for use throughout this guide.

+* [Install the required extensions](#install-required-extensions).

+## Set environment variables

+Set the following environment variables for use throughout this guide:

+```bash

+export SUFFIX=$(cat /dev/urandom | LC_ALL=C tr -dc 'a-z0-9' | fold -w 8 | head -n 1)

+export LOCAL_NAME="cnpg"

+export TAGS="owner=user"

+export RESOURCE_GROUP_NAME="rg-${LOCAL_NAME}-${SUFFIX}"

+export PRIMARY_CLUSTER_REGION="westus3"

+export AKS_PRIMARY_CLUSTER_NAME="aks-primary-${LOCAL_NAME}-${SUFFIX}"

+export AKS_PRIMARY_MANAGED_RG_NAME="rg-${LOCAL_NAME}-primary-aksmanaged-${SUFFIX}"

+export AKS_PRIMARY_CLUSTER_FED_CREDENTIAL_NAME="pg-primary-fedcred1-${LOCAL_NAME}-${SUFFIX}"

+export AKS_PRIMARY_CLUSTER_PG_DNSPREFIX=$(echo $(echo "a$(openssl rand -hex 5 | cut -c1-11)"))

+export AKS_UAMI_CLUSTER_IDENTITY_NAME="mi-aks-${LOCAL_NAME}-${SUFFIX}"

+export AKS_CLUSTER_VERSION="1.29"

+export PG_NAMESPACE="cnpg-database"

+export PG_SYSTEM_NAMESPACE="cnpg-system"

+export PG_PRIMARY_CLUSTER_NAME="pg-primary-${LOCAL_NAME}-${SUFFIX}"

+export PG_PRIMARY_STORAGE_ACCOUNT_NAME="hacnpgpsa${SUFFIX}"

+export PG_STORAGE_BACKUP_CONTAINER_NAME="backups"

+export ENABLE_AZURE_PVC_UPDATES="true"

+export MY_PUBLIC_CLIENT_IP=$(dig +short myip.opendns.com @resolver3.opendns.com)

+```

+## Install required extensions

+The `aks-preview`, `k8s-extension` and `amg` extensions provide more functionality for managing Kubernetes clusters and querying Azure resources. Install these extensions using the following [`az extension add`][az-extension-add] commands:

+```bash

+az extension add --upgrade --name aks-preview --yes --allow-preview true

+az extension add --upgrade --name k8s-extension --yes --allow-preview false

+az extension add --upgrade --name amg --yes --allow-preview false

+```

+As a prerequisite for utilizing kubectl, it is essential to first install [Krew][install-krew], followed by the installation of the [CNPG plugin][cnpg-plugin]. This will enable the management of the PostgreSQL operator using the subsequent commands.

+```bash

+(

+ set -x; cd "$(mktemp -d)" &&

+ OS="$(uname | tr '[:upper:]' '[:lower:]')" &&

+ ARCH="$(uname -m | sed -e 's/x86_64/amd64/' -e 's/\(arm\)\(64\)\?.*/\1\2/' -e 's/aarch64$/arm64/')" &&

+ KREW="krew-${OS}_${ARCH}" &&

+ curl -fsSLO "https://github.com/kubernetes-sigs/krew/releases/latest/download/${KREW}.tar.gz" &&

+ tar zxvf "${KREW}.tar.gz" &&

+ ./"${KREW}" install krew

+)

+export PATH="${KREW_ROOT:-$HOME/.krew}/bin:$PATH"

+kubectl krew install cnpg

+```

+## Create a resource group

+Create a resource group to hold the resources you create in this guide using the [`az group create`][az-group-create] command.

+```bash

+az group create \

+ --name $RESOURCE_GROUP_NAME \

+ --location $PRIMARY_CLUSTER_REGION \

+ --tags $TAGS \

+ --query 'properties.provisioningState' \

+ --output tsv

+```

+## Create a user-assigned managed identity

+In this section, you create a user-assigned managed identity (UAMI) to allow the CNPG PostgreSQL to use an AKS workload identity to access Azure Blob Storage. This configuration allows the PostgreSQL cluster on AKS to connect to Azure Blob Storage without a secret.

+1. Create a user-assigned managed identity using the [`az identity create`][az-identity-create] command.

+ ```bash

+ AKS_UAMI_WI_IDENTITY=$(az identity create \

+ --name $AKS_UAMI_CLUSTER_IDENTITY_NAME \

+ --resource-group $RESOURCE_GROUP_NAME \

+ --location $PRIMARY_CLUSTER_REGION \

+ --output json)

+ ```

+1. Enable AKS workload identity and generate a service account to use later in this guide using the following commands:

+ ```bash

+ export AKS_UAMI_WORKLOAD_OBJECTID=$( \

+ echo "${AKS_UAMI_WI_IDENTITY}" | jq -r '.principalId')

+ export AKS_UAMI_WORKLOAD_RESOURCEID=$( \

+ echo "${AKS_UAMI_WI_IDENTITY}" | jq -r '.id')

+ export AKS_UAMI_WORKLOAD_CLIENTID=$( \

+ echo "${AKS_UAMI_WI_IDENTITY}" | jq -r '.clientId')

+ echo "ObjectId: $AKS_UAMI_WORKLOAD_OBJECTID"

+ echo "ResourceId: $AKS_UAMI_WORKLOAD_RESOURCEID"

+ echo "ClientId: $AKS_UAMI_WORKLOAD_CLIENTID"

+ ```

+The object ID is a unique identifier for the client ID (also known as the application ID) that uniquely identifies a security principal of type *Application* within the Entra ID tenant. The resource ID is a unique identifier to manage and locate a resource in Azure. These values are required to enabled AKS workload identity.

+The CNPG operator automatically generates a service account called *postgres* that you use later in the guide to create a federated credential that enables OAuth access from PostgreSQL to Azure Storage.

+## Create a storage account in the primary region

+1. Create an object storage account to store PostgreSQL backups in the primary region using the [`az storage account create`][az-storage-account-create] command.

+ ```bash

+ az storage account create \

+ --name $PG_PRIMARY_STORAGE_ACCOUNT_NAME \

+ --resource-group $RESOURCE_GROUP_NAME \

+ --location $PRIMARY_CLUSTER_REGION \

+ --sku Standard_ZRS \

+ --kind StorageV2 \

+ --query 'provisioningState' \

+ --output tsv

+ ```

+1. Create the storage container to store the Write Ahead Logs (WAL) and regular PostgreSQL on-demand and scheduled backups using the [`az storage container create`][az-storage-container-create] command.

+ ```bash

+ az storage container create \

+ --name $PG_STORAGE_BACKUP_CONTAINER_NAME \

+ --account-name $PG_PRIMARY_STORAGE_ACCOUNT_NAME \

+ --auth-mode login

+ ```

+ Example output:

+ ```output

+ {

+ "created": true

+ }

+ ```

+ > [!NOTE]

+ > If you encounter the error message: `The request may be blocked by network rules of storage account. Please check network rule set using 'az storage account show -n accountname --query networkRuleSet'. If you want to change the default action to apply when no rule matches, please use 'az storage account update'`. Please verify user permissions for Azure Blob Storage and, if **necessary**, elevate your role to `Storage Blob Data Owner` using the commands provided below and after retry the [`az storage container create`][az-storage-container-create] command.

+ ```bash

+ az role assignment list --scope $STORAGE_ACCOUNT_PRIMARY_RESOURCE_ID --output table

+ export USER_ID=$(az ad signed-in-user show --query id --output tsv)

+ export STORAGE_ACCOUNT_PRIMARY_RESOURCE_ID=$(az storage account show \

+ --name $PG_PRIMARY_STORAGE_ACCOUNT_NAME \

+ --resource-group $RESOURCE_GROUP_NAME \

+ --query "id" \

+ --output tsv)

+ az role assignment create \

+ --assignee-object-id $USER_ID \

+ --assignee-principal-type User \

+ --scope $STORAGE_ACCOUNT_PRIMARY_RESOURCE_ID \

+ --role "Storage Blob Data Owner" \

+ --output tsv

+ ```

+## Assign RBAC to storage accounts

+To enable backups, the PostgreSQL cluster needs to read and write to an object store. The PostgreSQL cluster running on AKS uses a workload identity to access the storage account via the CNPG operator configuration parameter [`inheritFromAzureAD`][inherit-from-azuread].

+1. Get the primary resource ID for the storage account using the [`az storage account show`][az-storage-account-show] command.

+ ```bash

+ export STORAGE_ACCOUNT_PRIMARY_RESOURCE_ID=$(az storage account show \

+ --name $PG_PRIMARY_STORAGE_ACCOUNT_NAME \

+ --resource-group $RESOURCE_GROUP_NAME \

+ --query "id" \

+ --output tsv)

+ echo $STORAGE_ACCOUNT_PRIMARY_RESOURCE_ID

+ ````

+1. Assign the "Storage Blob Data Contributor" Azure built-in role to the object ID with the storage account resource ID scope for the UAMI associated with the managed identity for each AKS cluster using the [`az role assignment create`][az-role-assignment-create] command.

+ ```bash

+ az role assignment create \

+ --role "Storage Blob Data Contributor" \

+ --assignee-object-id $AKS_UAMI_WORKLOAD_OBJECTID \

+ --assignee-principal-type ServicePrincipal \

+ --scope $STORAGE_ACCOUNT_PRIMARY_RESOURCE_ID \

+ --query "id" \

+ --output tsv

+ ```

+## Set up monitoring infrastructure

+In this section, you deploy an instance of Azure Managed Grafana, an Azure Monitor workspace, and an Azure Monitor Log Analytics workspace to enable monitoring of the PostgreSQL cluster. You also store references to the created monitoring infrastructure to use as input during the AKS cluster creation process later in the guide. This section might take some time to complete.

+> [!NOTE]

+> Azure Managed Grafana instances and AKS clusters are billed independently. For more pricing information, see [Azure Managed Grafana pricing][azure-managed-grafana-pricing].

+1. Create an Azure Managed Grafana instance using the [`az grafana create`][az-grafana-create] command.

+ ```bash

+ export GRAFANA_PRIMARY="grafana-${LOCAL_NAME}-${SUFFIX}"

+ export GRAFANA_RESOURCE_ID=$(az grafana create \

+ --resource-group $RESOURCE_GROUP_NAME \

+ --name $GRAFANA_PRIMARY \

+ --location $PRIMARY_CLUSTER_REGION \

+ --zone-redundancy Enabled \

+ --tags $TAGS \

+ --query "id" \

+ --output tsv)

+ echo $GRAFANA_RESOURCE_ID

+ ```

+1. Create an Azure Monitor workspace using the [`az monitor account create`][az-monitor-account-create] command.

+ ```bash

+ export AMW_PRIMARY="amw-${LOCAL_NAME}-${SUFFIX}"

+ export AMW_RESOURCE_ID=$(az monitor account create \

+ --name $AMW_PRIMARY \

+ --resource-group $RESOURCE_GROUP_NAME \

+ --location $PRIMARY_CLUSTER_REGION \

+ --tags $TAGS \

+ --query "id" \

+ --output tsv)

+ echo $AMW_RESOURCE_ID

+ ```

+1. Create an Azure Monitor Log Analytics workspace using the [`az monitor log-analytics workspace create`][az-monitor-log-analytics-workspace-create] command.

+ ```bash

+ export ALA_PRIMARY="ala-${LOCAL_NAME}-${SUFFIX}"

+ export ALA_RESOURCE_ID=$(az monitor log-analytics workspace create \

+ --resource-group $RESOURCE_GROUP_NAME \

+ --workspace-name $ALA_PRIMARY \

+ --location $PRIMARY_CLUSTER_REGION \

+ --query "id" \

+ --output tsv)

+ echo $ALA_RESOURCE_ID

+ ```

+## Create the AKS cluster to host the PostgreSQL cluster

+In this section, you create a multizone AKS cluster with a system node pool. The AKS cluster hosts the PostgreSQL cluster primary replica and two standby replicas, each aligned to a different availability zone to enable zonal redundancy.

+You also add a user node pool to the AKS cluster to host the PostgreSQL cluster. Using a separate node pool allows for control over the Azure VM SKUs used for PostgreSQL and enables the AKS system pool to optimize performance and costs. You apply a label to the user node pool that you can reference for node selection when deploying the CNPG operator later in this guide. This section might take some time to complete.

+1. Create an AKS cluster using the [`az aks create`][az-aks-create] command.

+ ```bash

+ export SYSTEM_NODE_POOL_VMSKU="standard_d2s_v3"

+ export USER_NODE_POOL_NAME="postgres"

+ export USER_NODE_POOL_VMSKU="standard_d4s_v3"

+

+ az aks create \

+ --name $AKS_PRIMARY_CLUSTER_NAME \

+ --tags $TAGS \

+ --resource-group $RESOURCE_GROUP_NAME \

+ --location $PRIMARY_CLUSTER_REGION \

+ --generate-ssh-keys \

+ --node-resource-group $AKS_PRIMARY_MANAGED_RG_NAME \

+ --enable-managed-identity \

+ --assign-identity $AKS_UAMI_WORKLOAD_RESOURCEID \

+ --network-plugin azure \

+ --network-plugin-mode overlay \

+ --network-dataplane cilium \

+ --nodepool-name systempool \

+ --enable-oidc-issuer \

+ --enable-workload-identity \

+ --enable-cluster-autoscaler \

+ --min-count 2 \

+ --max-count 3 \

+ --node-vm-size $SYSTEM_NODE_POOL_VMSKU \

+ --enable-azure-monitor-metrics \

+ --azure-monitor-workspace-resource-id $AMW_RESOURCE_ID \

+ --grafana-resource-id $GRAFANA_RESOURCE_ID \

+ --api-server-authorized-ip-ranges $MY_PUBLIC_CLIENT_IP \

+ --tier standard \

+ --kubernetes-version $AKS_CLUSTER_VERSION \

+ --zones 1 2 3 \

+ --output table

+ ```

+2. Add a user node pool to the AKS cluster using the [`az aks nodepool add`][az-aks-node-pool-add] command.

+ ```bash

+ az aks nodepool add \

+ --resource-group $RESOURCE_GROUP_NAME \

+ --cluster-name $AKS_PRIMARY_CLUSTER_NAME \

+ --name $USER_NODE_POOL_NAME \

+ --enable-cluster-autoscaler \

+ --min-count 3 \

+ --max-count 6 \

+ --node-vm-size $USER_NODE_POOL_VMSKU \

+ --zones 1 2 3 \

+ --labels workload=postgres \

+ --output table

+ ```

+> [!NOTE]

+> If you receive the error message `"(OperationNotAllowed) Operation is not allowed: Another operation (Updating) is in progress, please wait for it to finish before starting a new operation."` when adding the AKS node pool, please wait a few minutes for the AKS cluster operations to complete and then run the `az aks nodepool add` command.

+## Connect to the AKS cluster and create namespaces

+In this section, you get the AKS cluster credentials, which serve as the keys that allow you to authenticate and interact with the cluster. Once connected, you create two namespaces: one for the CNPG controller manager services and one for the PostgreSQL cluster and its related services.

+1. Get the AKS cluster credentials using the [`az aks get-credentials`][az-aks-get-credentials] command.

+ ```bash

+ az aks get-credentials \

+ --resource-group $RESOURCE_GROUP_NAME \

+ --name $AKS_PRIMARY_CLUSTER_NAME \

+ --output none

+ ```

+2. Create the namespace for the CNPG controller manager services, the PostgreSQL cluster, and its related services by using the [`kubectl create namespace`][kubectl-create-namespace] command.

+ ```bash

+ kubectl create namespace $PG_NAMESPACE --context $AKS_PRIMARY_CLUSTER_NAME

+ kubectl create namespace $PG_SYSTEM_NAMESPACE --context $AKS_PRIMARY_CLUSTER_NAME

+ ```

+## Update the monitoring infrastructure

+The Azure Monitor workspace for Managed Prometheus and Azure Managed Grafana are automatically linked to the AKS cluster for metrics and visualization during the cluster creation process. In this section, you enable log collection with AKS Container insights and validate that Managed Prometheus is scraping metrics and Container insights is ingesting logs.

+1. Enable Container insights monitoring on the AKS cluster using the [`az aks enable-addons`][az-aks-enable-addons] command.

+ ```bash

+ az aks enable-addons \

+ --addon monitoring \

+ --name $AKS_PRIMARY_CLUSTER_NAME \

+ --resource-group $RESOURCE_GROUP_NAME \

+ --workspace-resource-id $ALA_RESOURCE_ID \

+ --output table

+ ```

+2. Validate that Managed Prometheus is scraping metrics and Container insights is ingesting logs from the AKS cluster by inspecting the DaemonSet using the [`kubectl get`][kubectl-get] command and the [`az aks show`][az-aks-show] command.

+ ```bash

+ kubectl get ds ama-metrics-node \

+ --context $AKS_PRIMARY_CLUSTER_NAME \

+ --namespace=kube-system

+ kubectl get ds ama-logs \

+ --context $AKS_PRIMARY_CLUSTER_NAME \

+ --namespace=kube-system

+ az aks show \

+ --resource-group $RESOURCE_GROUP_NAME \

+ --name $AKS_PRIMARY_CLUSTER_NAME \

+ --query addonProfiles

+ ```

+ Your output should resemble the following example output, with *six* nodes total (three for the system node pool and three for the PostgreSQL node pool) and the Container insights showing `"enabled": true`:

+ ```output

+ NAME DESIRED CURRENT READY UP-TO-DATE AVAILABLE NODE SELECTOR

+ ama-metrics-node 6 6 6 6 6 <none>

+ NAME DESIRED CURRENT READY UP-TO-DATE AVAILABLE NODE SELECTOR

+ ama-logs 6 6 6 6 6 <none>

+ {

+ "omsagent": {

+ "config": {

+ "logAnalyticsWorkspaceResourceID": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-cnpg-9vbin3p8/providers/Microsoft.OperationalInsights/workspaces/ala-cnpg-9vbin3p8",

+ "useAADAuth": "true"

+ },

+ "enabled": true,

+ "identity": null

+ }

+ }

+ ```

+## Create a public static IP for PostgreSQL cluster ingress

+To validate deployment of the PostgreSQL cluster and use client PostgreSQL tooling, such as *psql* and *PgAdmin*, you need to expose the primary and read-only replicas to ingress. In this section, you create an Azure public IP resource that you later supply to an Azure load balancer to expose PostgreSQL endpoints for query.

+1. Get the name of the AKS cluster node resource group using the [`az aks show`][az-aks-show] command.

+ ```bash

+ export AKS_PRIMARY_CLUSTER_NODERG_NAME=$(az aks show \

+ --name $AKS_PRIMARY_CLUSTER_NAME \

+ --resource-group $RESOURCE_GROUP_NAME \

+ --query nodeResourceGroup \

+ --output tsv)

+ echo $AKS_PRIMARY_CLUSTER_NODERG_NAME

+ ```

+2. Create the public IP address using the [`az network public-ip create`][az-network-public-ip-create] command.

+ ```bash

+ export AKS_PRIMARY_CLUSTER_PUBLICIP_NAME="$AKS_PRIMARY_CLUSTER_NAME-pip"

+ az network public-ip create \

+ --resource-group $AKS_PRIMARY_CLUSTER_NODERG_NAME \

+ --name $AKS_PRIMARY_CLUSTER_PUBLICIP_NAME \

+ --location $PRIMARY_CLUSTER_REGION \

+ --sku Standard \

+ --zone 1 2 3 \

+ --allocation-method static \

+ --output table

+ ```

+3. Get the newly created public IP address using the [`az network public-ip show`][az-network-public-ip-show] command.

+ ```bash

+ export AKS_PRIMARY_CLUSTER_PUBLICIP_ADDRESS=$(az network public-ip show \

+ --resource-group $AKS_PRIMARY_CLUSTER_NODERG_NAME \

+ --name $AKS_PRIMARY_CLUSTER_PUBLICIP_NAME \

+ --query ipAddress \

+ --output tsv)

+ echo $AKS_PRIMARY_CLUSTER_PUBLICIP_ADDRESS

+ ```

+4. Get the resource ID of the node resource group using the [`az group show`][az-group-show] command.

+ ```bash

+ export AKS_PRIMARY_CLUSTER_NODERG_NAME_SCOPE=$(az group show --name \

+ $AKS_PRIMARY_CLUSTER_NODERG_NAME \

+ --query id \

+ --output tsv)

+ echo $AKS_PRIMARY_CLUSTER_NODERG_NAME_SCOPE

+ ```

+5. Assign the "Network Contributor" role to the UAMI object ID using the node resource group scope using the [`az role assignment create`][az-role-assignment-create] command.

+ ```bash

+ az role assignment create \

+ --assignee-object-id ${AKS_UAMI_WORKLOAD_OBJECTID} \

+ --assignee-principal-type ServicePrincipal \

+ --role "Network Contributor" \

+ --scope ${AKS_PRIMARY_CLUSTER_NODERG_NAME_SCOPE}

+ ```

+## Install the CNPG operator in the AKS cluster

+In this section, you install the CNPG operator in the AKS cluster using Helm or a YAML manifest.

+### [Helm](#tab/helm)

+1. Add the CNPG Helm repo using the [`helm repo add`][helm-repo-add] command.

+ ```bash

+ helm repo add cnpg https://cloudnative-pg.github.io/charts

+ ```

+2. Upgrade the CNPG Helm repo and install it on the AKS cluster using the [`helm upgrade`][helm-upgrade] command with the `--install` flag.

+ ```bash

+ helm upgrade --install cnpg \

+ --namespace $PG_SYSTEM_NAMESPACE \

+ --create-namespace \

+ --kube-context=$AKS_PRIMARY_CLUSTER_NAME \

+ cnpg/cloudnative-pg

+ ```

+3. Verify the operator installation on the AKS cluster using the [`kubectl get`][kubectl-get] command.

+ ```bash

+ kubectl get deployment \

+ --context $AKS_PRIMARY_CLUSTER_NAME \

+ --namespace $PG_SYSTEM_NAMESPACE cnpg-cloudnative-pg

+ ```

+### [YAML](#tab/yaml)

+1. Install the CNPG operator on the AKS cluster using the [`kubectl apply`][kubectl-apply] command.

+ ```bash

+ kubectl apply --context $AKS_PRIMARY_CLUSTER_NAME \

+ --namespace $PG_SYSTEM_NAMESPACE \

+ --server-side -f \

+ https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/release-1.23/releases/cnpg-1.23.1.yaml

+ ```

+2. Verify the operator installation on the AKS cluster using the [`kubectl get`][kubectl-get] command.

+ ```bash

+ kubectl get deployment \

+ --namespace $PG_SYSTEM_NAMESPACE cnpg-controller-manager \

+ --context $AKS_PRIMARY_CLUSTER_NAME

+ ```

+## Next steps

+> [!div class="nextstepaction"]

+> [Deploy a highly available PostgreSQL database on the AKS cluster][deploy-postgresql]

+## Contributors

+*This article is maintained by Microsoft. It was originally written by the following contributors*:

+* Ken Kilty | Principal TPM

+* Russell de Pina | Principal TPM

+* Adrian Joian | Senior Customer Engineer

+* Jenny Hayes | Senior Content Developer

+* Carol Smith | Senior Content Developer

+* Erin Schaffer | Content Developer 2

+<!-- LINKS -->

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

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

+[postgresql-ha-deployment-overview]: ./postgresql-ha-overview.md

+[az-extension-add]: /cli/azure/extension#az_extension_add

+[az-group-create]: /cli/azure/group#az_group_create

+[az-storage-account-create]: /cli/azure/storage/account#az_storage_account_create

+[az-storage-container-create]: /cli/azure/storage/container#az_storage_container_create

+[inherit-from-azuread]: https://cloudnative-pg.io/documentation/1.23/appendixes/object_stores/#azure-blob-storage

+[az-storage-account-show]: /cli/azure/storage/account#az_storage_account_show

+[az-role-assignment-create]: /cli/azure/role/assignment#az_role_assignment_create

+[az-monitor-account-create]: /cli/azure/monitor/account#az_monitor_account_create

+[az-monitor-log-analytics-workspace-create]: /cli/azure/monitor/log-analytics/workspace#az_monitor_log_analytics_workspace_create

+[azure-managed-grafana-pricing]: https://azure.microsoft.com/pricing/details/managed-grafana/

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

+[az-aks-node-pool-add]: /cli/azure/aks/nodepool#az_aks_nodepool_add

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

+[kubectl-create-namespace]: https://kubernetes.io/docs/reference/kubectl/generated/kubectl_create/kubectl_create_namespace/

+[az-aks-enable-addons]: /cli/azure/aks#az_aks_enable_addons

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

+[az-aks-show]: /cli/azure/aks#az_aks_show

+[az-network-public-ip-create]: /cli/azure/network/public-ip#az_network_public_ip_create

+[az-network-public-ip-show]: /cli/azure/network/public-ip#az_network_public_ip_show

+[az-group-show]: /cli/azure/group#az_group_show

+[helm-repo-add]: https://helm.sh/docs/helm/helm_repo_add/

+[helm-upgrade]: https://helm.sh/docs/helm/helm_upgrade/

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

+[deploy-postgresql]: ./deploy-postgresql-ha.md

+[install-krew]: https://krew.sigs.k8s.io/

+[cnpg-plugin]: https://cloudnative-pg.io/documentation/current/kubectl-plugin/#using-krew

+ Title: 'Deploy a highly available PostgreSQL database on AKS with Azure CLI'

+description: In this article, you deploy a highly available PostgreSQL database on AKS using the CloudNativePG operator.

+# Deploy a highly available PostgreSQL database on AKS

+In this article, you deploy a highly available PostgreSQL database on AKS.

+* If you haven't already created the required infrastructure for this deployment, follow the steps in [Create infrastructure for deploying a highly available PostgreSQL database on AKS][create-infrastructure] to get set up, and then you can return to this article.

+## Create secret for bootstrap app user

+1. Generate a secret to validate the PostgreSQL deployment by interactive login for a bootstrap app user using the [`kubectl create secret`][kubectl-create-secret] command.

+ ```bash

+ PG_DATABASE_APPUSER_SECRET=$(echo -n | openssl rand -base64 16)

+ kubectl create secret generic db-user-pass \

+ --from-literal=username=app \

+ --from-literal=password="${PG_DATABASE_APPUSER_SECRET}" \

+ --namespace $PG_NAMESPACE \

+ --context $AKS_PRIMARY_CLUSTER_NAME

+ ```

+1. Validate that the secret was successfully created using the [`kubectl get`][kubectl-get] command.

+ ```bash

+ kubectl get secret db-user-pass --namespace $PG_NAMESPACE --context $AKS_PRIMARY_CLUSTER_NAME

+ ```

+## Set environment variables for the PostgreSQL cluster

+* Deploy a ConfigMap to set environment variables for the PostgreSQL cluster using the following [`kubectl apply`][kubectl-apply] command:

+ ```bash

+ cat <<EOF | kubectl apply --context $AKS_PRIMARY_CLUSTER_NAME -n $PG_NAMESPACE -f -

+ apiVersion: v1

+ kind: ConfigMap

+ metadata:

+ name: cnpg-controller-manager-config

+ data:

+ ENABLE_AZURE_PVC_UPDATES: 'true'

+ EOF

+ ```

+## Install the Prometheus PodMonitors

+Prometheus creates PodMonitors for the CNPG instances using a set of default recording rules stored on the CNPG GitHub samples repo. In a production environment, these rules would be modified as needed.

+1. Add the Prometheus Community Helm repo using the [`helm repo add`][helm-repo-add] command.

+ ```bash

+ helm repo add prometheus-community \

+ https://prometheus-community.github.io/helm-charts

+ ```

+2. Upgrade the Prometheus Community Helm repo and install it on the primary cluster using the [`helm upgrade`][helm-upgrade] command with the `--install` flag.

+ ```bash

+ helm upgrade --install \

+ --namespace $PG_NAMESPACE \

+ -f https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/main/docs/src/samples/monitoring/kube-stack-config.yaml \

+ prometheus-community \

+ prometheus-community/kube-prometheus-stack \

+ --kube-context=$AKS_PRIMARY_CLUSTER_NAME

+ ```

+Verify that the pod monitor is created.

+```bash

+kubectl --namespace $PG_NAMESPACE \

+ --context $AKS_PRIMARY_CLUSTER_NAME \

+ get podmonitors.monitoring.coreos.com \

+ $PG_PRIMARY_CLUSTER_NAME \

+ -o yaml

+```

+## Create a federated credential

+In this section, you create a federated identity credential for PostgreSQL backup to allow CNPG to use AKS workload identity to authenticate to the storage account destination for backups. The CNPG operator creates a Kubernetes service account with the same name as the cluster named used in the CNPG Cluster deployment manifest.

+1. Get the OIDC issuer URL of the cluster using the [`az aks show`][az-aks-show] command.

+ ```bash

+ export AKS_PRIMARY_CLUSTER_OIDC_ISSUER="$(az aks show \

+ --name $AKS_PRIMARY_CLUSTER_NAME \

+ --resource-group $RESOURCE_GROUP_NAME \

+ --query "oidcIssuerProfile.issuerUrl" \

+ --output tsv)"

+ ```

+2. Create a federated identity credential using the [`az identity federated-credential create`][az-identity-federated-credential-create] command.

+ ```bash

+ az identity federated-credential create \

+ --name $AKS_PRIMARY_CLUSTER_FED_CREDENTIAL_NAME \

+ --identity-name $AKS_UAMI_CLUSTER_IDENTITY_NAME \

+ --resource-group $RESOURCE_GROUP_NAME --issuer "${AKS_PRIMARY_CLUSTER_OIDC_ISSUER}" \

+ --subject system:serviceaccount:"${PG_NAMESPACE}":"${PG_PRIMARY_CLUSTER_NAME}" \

+ --audience api://AzureADTokenExchange

+ ```

+## Deploy a highly available PostgreSQL cluster

+In this section, you deploy a highly available PostgreSQL cluster using the [CNPG Cluster custom resource definition (CRD)][cluster-crd].

+The following table outlines the key properties set in the YAML deployment manifest for the Cluster CRD:

+| Property | Definition |

+| | |

+| `inheritedMetadata` | Specific to the CNPG operator. Metadata is inherited by all objects related to the cluster. |

+| `annotations: service.beta.kubernetes.io/azure-dns-label-name` | DNS label for use when exposing the read-write and read-only Postgres cluster endpoints. |

+| `labels: azure.workload.identity/use: "true"` | Indicates that AKS should inject workload identity dependencies into the pods hosting the PostgreSQL cluster instances. |

+| `topologySpreadConstraints` | Require different zones and different nodes with label `"workload=postgres"`. |

+| `resources` | Configures a Quality of Service (QoS) class of *Guaranteed*. In a production environment, these values are key for maximizing usage of the underlying node VM and vary based on the Azure VM SKU used. |

+| `bootstrap` | Specific to the CNPG operator. Initializes with an empty app database. |

+| `storage` / `walStorage` | Specific to the CNPG operator. Defines storage templates for the PersistentVolumeClaims (PVCs) for data and log storage. It's also possible to specify storage for tablespaces to shard out for increased IOPs. |

+| `replicationSlots` | Specific to the CNPG operator. Enables replication slots for high availability. |

+| `postgresql` | Specific to the CNPG operator. Maps settings for `postgresql.conf`, `pg_hba.conf`, and `pg_ident.conf config`. |

+| `serviceAccountTemplate` | Contains the template needed to generate the service accounts and maps the AKS federated identity credential to the UAMI to enable AKS workload identity authentication from the pods hosting the PostgreSQL instances to external Azure resources. |

+| `barmanObjectStore` | Specific to the CNPG operator. Configures the barman-cloud tool suite using AKS workload identity for authentication to the Azure Blob Storage object store. |

+1. Deploy the PostgreSQL cluster with the Cluster CRD using the [`kubectl apply`][kubectl-apply] command.

+ ```bash

+ cat <<EOF | kubectl apply --context $AKS_PRIMARY_CLUSTER_NAME -n $PG_NAMESPACE -v 9 -f -

+ apiVersion: postgresql.cnpg.io/v1

+ kind: Cluster

+ metadata:

+ name: $PG_PRIMARY_CLUSTER_NAME

+ spec:

+ inheritedMetadata:

+ annotations:

+ service.beta.kubernetes.io/azure-dns-label-name: $AKS_PRIMARY_CLUSTER_PG_DNSPREFIX

+ labels:

+ azure.workload.identity/use: "true"

+

+ instances: 3

+ startDelay: 30

+ stopDelay: 30

+ minSyncReplicas: 1

+ maxSyncReplicas: 1

+ replicationSlots:

+ highAvailability:

+ enabled: true

+ updateInterval: 30

+

+ topologySpreadConstraints:

+ - maxSkew: 1

+ topologyKey: topology.kubernetes.io/zone

+ whenUnsatisfiable: DoNotSchedule

+ labelSelector:

+ matchLabels:

+ cnpg.io/cluster: $PG_PRIMARY_CLUSTER_NAME

+

+ affinity:

+ nodeSelector:

+ workload: postgres

+

+ resources:

+ requests:

+ memory: '8Gi'

+ cpu: 2

+ limits:

+ memory: '8Gi'

+ cpu: 2

+

+ bootstrap:

+ initdb:

+ database: appdb

+ owner: app

+ secret:

+ name: db-user-pass

+ dataChecksums: true

+

+ storage:

+ size: 2Gi

+ pvcTemplate:

+ accessModes:

+ - ReadWriteOnce

+ resources:

+ requests:

+ storage: 2Gi

+ storageClassName: managed-csi-premium

+

+ walStorage:

+ size: 2Gi

+ pvcTemplate:

+ accessModes:

+ - ReadWriteOnce

+ resources:

+ requests:

+ storage: 2Gi

+ storageClassName: managed-csi-premium

+

+ monitoring:

+ enablePodMonitor: true

+

+ postgresql:

+ parameters:

+ archive_timeout: '5min'

+ auto_explain.log_min_duration: '10s'

+ checkpoint_completion_target: '0.9'

+ checkpoint_timeout: '15min'

+ shared_buffers: '256MB'

+ effective_cache_size: '512MB'

+ pg_stat_statements.max: '1000'

+ pg_stat_statements.track: 'all'

+ max_connections: '400'

+ max_prepared_transactions: '400'

+ max_parallel_workers: '32'

+ max_parallel_maintenance_workers: '8'

+ max_parallel_workers_per_gather: '8'

+ max_replication_slots: '32'

+ max_worker_processes: '32'

+ wal_keep_size: '512MB'

+ max_wal_size: '1GB'

+ pg_hba:

+ - host all all all scram-sha-256

+

+ serviceAccountTemplate:

+ metadata:

+ annotations:

+ azure.workload.identity/client-id: "$AKS_UAMI_WORKLOAD_CLIENTID"

+ labels:

+ azure.workload.identity/use: "true"

+

+ backup:

+ barmanObjectStore:

+ destinationPath: "https://${PG_PRIMARY_STORAGE_ACCOUNT_NAME}.blob.core.windows.net/backups"

+ azureCredentials:

+ inheritFromAzureAD: true

+

+ retentionPolicy: '7d'

+ EOF

+ ```

+1. Validate that the primary PostgreSQL cluster was successfully created using the [`kubectl get`][kubectl-get] command. The CNPG Cluster CRD specified three instances, which can be validated by viewing running pods once each instance is brought up and joined for replication. Be patient as it can take some time for all three instances to come online and join the cluster.

+ ```bash

+ kubectl get pods --context $AKS_PRIMARY_CLUSTER_NAME --namespace $PG_NAMESPACE -l cnpg.io/cluster=$PG_PRIMARY_CLUSTER_NAME

+ ```

+ Example output

+ ```output

+ NAME READY STATUS RESTARTS AGE

+ pg-primary-cnpg-r8c7unrw-1 1/1 Running 0 4m25s

+ pg-primary-cnpg-r8c7unrw-2 1/1 Running 0 3m33s

+ pg-primary-cnpg-r8c7unrw-3 1/1 Running 0 2m49s

+ ```

+### Validate the Prometheus PodMonitor is running

+The CNPG operator automatically creates a PodMonitor for the primary instance using the recording rules created during the [Prometheus Community installation](#install-the-prometheus-podmonitors).

+1. Validate the PodMonitor is running using the [`kubectl get`][kubectl-get] command.

+ ```bash

+ kubectl --namespace $PG_NAMESPACE \

+ --context $AKS_PRIMARY_CLUSTER_NAME \

+ get podmonitors.monitoring.coreos.com \

+ $PG_PRIMARY_CLUSTER_NAME \

+ --output yaml

+ ```

+ Example output

+ ```output

+ kind: PodMonitor

+ metadata:

+ annotations:

+ cnpg.io/operatorVersion: 1.23.1

+ ...

+ ```

+If you are using Azure Monitor for Managed Prometheus, you will need to add another pod monitor using the custom group name. Managed Prometheus does not pick up the custom resource definitions (CRDs) from the Prometheus community. Aside from the group name, the CRDs are the same. This allows pod monitors for Managed Prometheus to exist side-by-side those that use the community pod monitor. If you are not using Managed Prometheus, you can skip this. Create a new pod monitor:

+```bash

+cat <<EOF | kubectl apply --context $AKS_PRIMARY_CLUSTER_NAME --namespace $PG_NAMESPACE -f -

+apiVersion: azmonitoring.coreos.com/v1

+kind: PodMonitor

+metadata:

+ name: cnpg-cluster-metrics-managed-prometheus

+ namespace: ${PG_NAMESPACE}

+ labels:

+ azure.workload.identity/use: "true"

+ cnpg.io/cluster: ${PG_PRIMARY_CLUSTER_NAME}

+spec:

+ selector:

+ matchLabels:

+ azure.workload.identity/use: "true"

+ cnpg.io/cluster: ${PG_PRIMARY_CLUSTER_NAME}

+ podMetricsEndpoints:

+ - port: metrics

+EOF

+```

+Verify that the pod monitor is created (note the difference in the group name).

+```bash

+kubectl --namespace $PG_NAMESPACE \

+ --context $AKS_PRIMARY_CLUSTER_NAME \

+ get podmonitors.azmonitoring.coreos.com \

+ -l cnpg.io/cluster=$PG_PRIMARY_CLUSTER_NAME \

+ -o yaml

+```

+#### Option A - Azure Monitor Workspace

+Once you have deployed the Postgres cluster and the pod monitor, you can view the metrics using the Azure portal in an Azure Monitor workspace.

+#### Option B - Managed Grafana

+Alternatively, Once you have deployed the Postgres cluster and pod monitors, you can create a metrics dashboard on the Managed Grafana instance created by the deployment script to visualize the metrics exported to the Azure Monitor workspace. You can access the Managed Grafana via the Azure portal. Navigate to the Managed Grafana instance created by the deployment script and click on the Endpoint link as shown here:

+Clicking on the Endpoint link will cause a new browser window to open where you can create dashboards on the Managed Grafana instance. Following the instructions to [configure an Azure Monitor data source](../azure-monitor/visualize/grafana-plugin.md#configure-an-azure-monitor-data-source-plug-in), you can then add visualizations to create a dashboard of metrics from the Postgres cluster. After setting up the data source connection, from the main menu, click the Data sources option and you should see a set of data source options for the data source connection as shown here:

+On the Managed Prometheus option, click the option to build a dashboard to open the dashboard editor. Once the editor window opens, click the Add visualization option then click the Managed Prometheus option to browse the metrics from the Postgres cluster. Once you have selected the metric you want to visualize, click the Run queries button to fetch the data for the visualization as shown here:

+Click the Save button to add the panel to your dashboard. You can add other panels by clicking the Add button in the dashboard editor and repeating this process to visualize other metrics. Adding the metrics visualizations, you should have something that looks like this:

+Click the Save icon to save your dashboard.

+## Inspect the deployed PostgreSQL cluster

+Validate that PostgreSQL is spread across multiple availability zones by retrieving the AKS node details using the [`kubectl get`][kubectl-get] command.

+```bash

+kubectl get nodes \

+ --context $AKS_PRIMARY_CLUSTER_NAME \

+ --namespace $PG_NAMESPACE \

+ --output json | jq '.items[] | {node: .metadata.name, zone: .metadata.labels."failure-domain.beta.kubernetes.io/zone"}'

+```

+Your output should resemble the following example output with the availability zone shown for each node:

+```output

+{

+ "node": "aks-postgres-15810965-vmss000000",

+ "zone": "westus3-1"

+}

+{

+ "node": "aks-postgres-15810965-vmss000001",

+ "zone": "westus3-2"

+}

+{

+ "node": "aks-postgres-15810965-vmss000002",

+ "zone": "westus3-3"

+}

+{

+ "node": "aks-systempool-26112968-vmss000000",

+ "zone": "westus3-1"

+}

+{

+ "node": "aks-systempool-26112968-vmss000001",

+ "zone": "westus3-2"

+}

+```

+## Connect to PostgreSQL and create a sample dataset

+In this section, you create a table and insert some data into the app database that was created in the CNPG Cluster CRD you deployed earlier. You use this data to validate the backup and restore operations for the PostgreSQL cluster.

+* Create a table and insert data into the app database using the following commands:

+ ```bash

+ kubectl cnpg psql $PG_PRIMARY_CLUSTER_NAME --namespace $PG_NAMESPACE

+ ```

+ ```sql

+ # Run the following PSQL commands to create a small dataset

+ # postgres=#

+ CREATE TABLE datasample (id INTEGER,name VARCHAR(255));

+ INSERT INTO datasample (id, name) VALUES (1, 'John');

+ INSERT INTO datasample (id, name) VALUES (2, 'Jane');

+ INSERT INTO datasample (id, name) VALUES (3, 'Alice');

+ SELECT COUNT(*) FROM datasample;

+

+ # Type \q to exit psql

+ ```

+ Your output should resemble the following example output:

+ ```output

+ CREATE TABLE

+ INSERT 0 1

+ INSERT 0 1

+ INSERT 0 1

+ count

+ -

+ 3

+ (1 row)

+ ```

+## Connect to PostgreSQL read-only replicas

+* Connect to the PostgreSQL read-only replicas and validate the sample dataset using the following commands:

+ ```bash

+ kubectl cnpg psql --replica $PG_PRIMARY_CLUSTER_NAME --namespace $PG_NAMESPACE

+ ```

+ ```sql

+ #postgres=#

+ SELECT pg_is_in_recovery();

+ ```

+ Example output

+ ```output

+ # pg_is_in_recovery

+ #-

+ # t

+ #(1 row)

+ ```

+ ```sql

+ #postgres=#

+ SELECT COUNT(*) FROM datasample;

+ ```

+ Example output

+ ```output

+ # count

+ #-

+ # 3

+ #(1 row)

+ # Type \q to exit psql

+ ```

+## Set up on-demand and scheduled PostgreSQL backups using Barman

+1. Validate that the PostgreSQL cluster can access the Azure storage account specified in the CNPG Cluster CRD and that `Working WAL archiving` reports as `OK` using the following command:

+ ```bash

+ kubectl cnpg status $PG_PRIMARY_CLUSTER_NAME 1 \

+ --context $AKS_PRIMARY_CLUSTER_NAME \

+ --namespace $PG_NAMESPACE

+ ```

+ Example output

+ ```output

+ Continuous Backup status

+ First Point of Recoverability: Not Available

+ Working WAL archiving: OK

+ WALs waiting to be archived: 0

+ Last Archived WAL: 00000001000000000000000A @ 2024-07-09T17:18:13.982859Z

+ Last Failed WAL: -

+ ```

+1. Deploy an on-demand backup to Azure Storage, which uses the AKS workload identity integration, using the YAML file with the [`kubectl apply`][kubectl-apply] command.

+ ```bash

+ export BACKUP_ONDEMAND_NAME="on-demand-backup-1"

+ cat <<EOF | kubectl apply --context $AKS_PRIMARY_CLUSTER_NAME --namespace $PG_NAMESPACE -v 9 -f -

+ apiVersion: postgresql.cnpg.io/v1

+ kind: Backup

+ metadata:

+ name: $BACKUP_ONDEMAND_NAME

+ spec:

+ method: barmanObjectStore

+ cluster:

+ name: $PG_PRIMARY_CLUSTER_NAME

+ EOF

+ ```

+1. Validate the status of the on-demand backup using the [`kubectl describe`][kubectl-describe] command.

+ ```bash

+ kubectl describe backup $BACKUP_ONDEMAND_NAME \

+ --context $AKS_PRIMARY_CLUSTER_NAME \

+ --namespace $PG_NAMESPACE

+ ```

+ Example output

+ ```output

+ Type Reason Age From Message

+ - - - -

+ Normal Starting 6s cloudnative-pg-backup Starting backup for cluster pg-primary-cnpg-r8c7unrw

+ Normal Starting 5s instance-manager Backup started

+ Normal Completed 1s instance-manager Backup completed

+ ```

+1. Validate that the cluster has a first point of recoverability using the following command:

+ ```bash

+ kubectl cnpg status $PG_PRIMARY_CLUSTER_NAME 1 \

+ --context $AKS_PRIMARY_CLUSTER_NAME \

+ --namespace $PG_NAMESPACE

+ ```

+ Example output

+ ```output

+ Continuous Backup status

+ First Point of Recoverability: 2024-06-05T13:47:18Z

+ Working WAL archiving: OK

+ ```

+1. Configure a scheduled backup for *every hour at 15 minutes past the hour* using the YAML file with the [`kubectl apply`][kubectl-apply] command.

+ ```bash

+ export BACKUP_SCHEDULED_NAME="scheduled-backup-1"

+ cat <<EOF | kubectl apply --context $AKS_PRIMARY_CLUSTER_NAME --namespace $PG_NAMESPACE -v 9 -f -

+ apiVersion: postgresql.cnpg.io/v1

+ kind: ScheduledBackup

+ metadata:

+ name: $BACKUP_SCHEDULED_NAME

+ spec:

+ # Backup once per hour

+ schedule: "0 15 * ? * *"

+ backupOwnerReference: self

+ cluster:

+ name: $PG_PRIMARY_CLUSTER_NAME

+ EOF

+ ```

+1. Validate the status of the scheduled backup using the [`kubectl describe`][kubectl-describe] command.

+ ```bash

+ kubectl describe scheduledbackup $BACKUP_SCHEDULED_NAME \

+ --context $AKS_PRIMARY_CLUSTER_NAME \

+ --namespace $PG_NAMESPACE

+ ```

+1. View the backup files stored on Azure blob storage for the primary cluster using the [`az storage blob list`][az-storage-blob-list] command.

+ ```bash

+ az storage blob list \

+ --account-name $PG_PRIMARY_STORAGE_ACCOUNT_NAME \

+ --container-name backups \

+ --query "[*].name" \

+ --only-show-errors

+ ```

+ Your output should resemble the following example output, validating the backup was successful:

+ ```output

+ [

+ "pg-primary-cnpg-r8c7unrw/base/20240605T134715/backup.info",

+ "pg-primary-cnpg-r8c7unrw/base/20240605T134715/data.tar",

+ "pg-primary-cnpg-r8c7unrw/wals/0000000100000000/000000010000000000000001",

+ "pg-primary-cnpg-r8c7unrw/wals/0000000100000000/000000010000000000000002",

+ "pg-primary-cnpg-r8c7unrw/wals/0000000100000000/000000010000000000000003",

+ "pg-primary-cnpg-r8c7unrw/wals/0000000100000000/000000010000000000000003.00000028.backup",

+ "pg-primary-cnpg-r8c7unrw/wals/0000000100000000/000000010000000000000004",

+ "pg-primary-cnpg-r8c7unrw/wals/0000000100000000/000000010000000000000005",

+ "pg-primary-cnpg-r8c7unrw/wals/0000000100000000/000000010000000000000005.00000028.backup",

+ "pg-primary-cnpg-r8c7unrw/wals/0000000100000000/000000010000000000000006",

+ "pg-primary-cnpg-r8c7unrw/wals/0000000100000000/000000010000000000000007",

+ "pg-primary-cnpg-r8c7unrw/wals/0000000100000000/000000010000000000000008",

+ "pg-primary-cnpg-r8c7unrw/wals/0000000100000000/000000010000000000000009"

+ ]

+ ```

+## Restore the on-demand backup to a new PostgreSQL cluster

+In this section, you restore the on-demand backup you created earlier using the CNPG operator into a new instance using the bootstrap Cluster CRD. A single instance cluster is used for simplicity. Remember that the AKS workload identity (via CNPG inheritFromAzureAD) accesses the backup files, and that the recovery cluster name is used to generate a new Kubernetes service account specific to the recovery cluster.

+You also create a second federated credential to map the new recovery cluster service account to the existing UAMI that has "Storage Blob Data Contributor" access to the backup files on blob storage.

+1. Create a second federated identity credential using the [`az identity federated-credential create`][az-identity-federated-credential-create] command.

+ ```bash

+ export PG_PRIMARY_CLUSTER_NAME_RECOVERED="$PG_PRIMARY_CLUSTER_NAME-recovered-db"

+ az identity federated-credential create \

+ --name $PG_PRIMARY_CLUSTER_NAME_RECOVERED \

+ --identity-name $AKS_UAMI_CLUSTER_IDENTITY_NAME \

+ --resource-group $RESOURCE_GROUP_NAME \

+ --issuer "${AKS_PRIMARY_CLUSTER_OIDC_ISSUER}" \

+ --subject system:serviceaccount:"${PG_NAMESPACE}":"${PG_PRIMARY_CLUSTER_NAME_RECOVERED}" \

+ --audience api://AzureADTokenExchange

+ ```

+1. Restore the on-demand backup using the Cluster CRD with the [`kubectl apply`][kubectl-apply] command.

+ ```bash

+ cat <<EOF | kubectl apply --context $AKS_PRIMARY_CLUSTER_NAME --namespace $PG_NAMESPACE -v 9 -f -

+ apiVersion: postgresql.cnpg.io/v1

+ kind: Cluster

+ metadata:

+ name: $PG_PRIMARY_CLUSTER_NAME_RECOVERED

+ spec:

+

+ inheritedMetadata:

+ annotations:

+ service.beta.kubernetes.io/azure-dns-label-name: $AKS_PRIMARY_CLUSTER_PG_DNSPREFIX

+ labels:

+ azure.workload.identity/use: "true"

+

+ instances: 1

+

+ affinity:

+ nodeSelector:

+ workload: postgres

+

+ # Point to cluster backup created earlier and stored on Azure Blob Storage

+ bootstrap:

+ recovery:

+ source: clusterBackup

+

+ storage:

+ size: 2Gi

+ pvcTemplate:

+ accessModes:

+ - ReadWriteOnce

+ resources:

+ requests:

+ storage: 2Gi

+ storageClassName: managed-csi-premium

+ volumeMode: Filesystem

+

+ walStorage:

+ size: 2Gi

+ pvcTemplate:

+ accessModes:

+ - ReadWriteOnce

+ resources:

+ requests:

+ storage: 2Gi

+ storageClassName: managed-csi-premium

+ volumeMode: Filesystem

+

+ serviceAccountTemplate:

+ metadata:

+ annotations:

+ azure.workload.identity/client-id: "$AKS_UAMI_WORKLOAD_CLIENTID"

+ labels:

+ azure.workload.identity/use: "true"

+

+ externalClusters:

+ - name: clusterBackup

+ barmanObjectStore:

+ destinationPath: https://${PG_PRIMARY_STORAGE_ACCOUNT_NAME}.blob.core.windows.net/backups

+ serverName: $PG_PRIMARY_CLUSTER_NAME

+ azureCredentials:

+ inheritFromAzureAD: true

+ wal:

+ maxParallel: 8

+ EOF

+ ```

+1. Connect to the recovered instance, then validate that the dataset created on the original cluster where the full backup was taken is present using the following command:

+ ```bash

+ kubectl cnpg psql $PG_PRIMARY_CLUSTER_NAME_RECOVERED --namespace $PG_NAMESPACE

+ ```

+ ```sql

+ postgres=# SELECT COUNT(*) FROM datasample;

+ ```

+ Example output

+ ```output

+ # count

+ #-

+ # 3

+ #(1 row)

+ # Type \q to exit psql

+ ```

+1. Delete the recovered cluster using the following command:

+ ```bash

+ kubectl cnpg destroy $PG_PRIMARY_CLUSTER_NAME_RECOVERED 1 \

+ --context $AKS_PRIMARY_CLUSTER_NAME \

+ --namespace $PG_NAMESPACE

+ ```

+1. Delete the federated identity credential using the [`az identity federated-credential delete`][az-identity-federated-credential-delete] command.

+ ```bash

+ az identity federated-credential delete \

+ --name $PG_PRIMARY_CLUSTER_NAME_RECOVERED \

+ --identity-name $AKS_UAMI_CLUSTER_IDENTITY_NAME \

+ --resource-group $RESOURCE_GROUP_NAME \

+ --yes

+ ```

+## Expose the PostgreSQL cluster using a public load balancer

+In this section, you configure the necessary infrastructure to publicly expose the PostgreSQL read-write and read-only endpoints with IP source restrictions to the public IP address of your client workstation.

+You also retrieve the following endpoints from the Cluster IP service:

+* *One* primary read-write endpoint that ends with `*-rw`.

+* *Zero to N* (depending on the number of replicas) read-only endpoints that end with `*-ro`.

+* *One* replication endpoint that ends with `*-r`.

+1. Get the Cluster IP service details using the [`kubectl get`][kubectl-get] command.

+ ```bash

+ kubectl get services \

+ --context $AKS_PRIMARY_CLUSTER_NAME \

+ --namespace $PG_NAMESPACE \

+ -l cnpg.io/cluster=$PG_PRIMARY_CLUSTER_NAME

+ ```

+ Example output

+ ```output

+ NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE

+ pg-primary-cnpg-sryti1qf-r ClusterIP 10.0.193.27 <none> 5432/TCP 3h57m

+ pg-primary-cnpg-sryti1qf-ro ClusterIP 10.0.237.19 <none> 5432/TCP 3h57m

+ pg-primary-cnpg-sryti1qf-rw ClusterIP 10.0.244.125 <none> 5432/TCP 3h57m

+ ```

+ > [!NOTE]

+ > There are three

+1. Get the service details using the [`kubectl get`][kubectl-get] command.

+ ```bash

+ export PG_PRIMARY_CLUSTER_RW_SERVICE=$(kubectl get services \

+ --namespace $PG_NAMESPACE \

+ --context $AKS_PRIMARY_CLUSTER_NAME \

+ -l "cnpg.io/cluster" \

+ --output json | jq -r '.items[] | select(.metadata.name | endswith("-rw")) | .metadata.name')

+ echo $PG_PRIMARY_CLUSTER_RW_SERVICE

+ export PG_PRIMARY_CLUSTER_RO_SERVICE=$(kubectl get services \

+ --namespace $PG_NAMESPACE \

+ --context $AKS_PRIMARY_CLUSTER_NAME \

+ -l "cnpg.io/cluster" \

+ --output json | jq -r '.items[] | select(.metadata.name | endswith("-ro")) | .metadata.name')

+ echo $PG_PRIMARY_CLUSTER_RO_SERVICE

+ ```

+1. Configure the load balancer service with the following YAML files using the [`kubectl apply`][kubectl-apply] command.

+ ```bash

+ cat <<EOF | kubectl apply --context $AKS_PRIMARY_CLUSTER_NAME -f -

+ apiVersion: v1

+ kind: Service

+ metadata:

+ annotations:

+ service.beta.kubernetes.io/azure-load-balancer-resource-group: $AKS_PRIMARY_CLUSTER_NODERG_NAME

+ service.beta.kubernetes.io/azure-pip-name: $AKS_PRIMARY_CLUSTER_PUBLICIP_NAME

+ service.beta.kubernetes.io/azure-dns-label-name: $AKS_PRIMARY_CLUSTER_PG_DNSPREFIX

+ name: cnpg-cluster-load-balancer-rw

+ namespace: "${PG_NAMESPACE}"

+ spec:

+ type: LoadBalancer

+ ports:

+ - protocol: TCP

+ port: 5432

+ targetPort: 5432

+ selector:

+ cnpg.io/instanceRole: primary

+ cnpg.io/podRole: instance

+ loadBalancerSourceRanges:

+ - "$MY_PUBLIC_CLIENT_IP/32"

+ EOF

+

+ cat <<EOF | kubectl apply --context $AKS_PRIMARY_CLUSTER_NAME -f -

+ apiVersion: v1

+ kind: Service

+ metadata:

+ annotations:

+ service.beta.kubernetes.io/azure-load-balancer-resource-group: $AKS_PRIMARY_CLUSTER_NODERG_NAME

+ service.beta.kubernetes.io/azure-pip-name: $AKS_PRIMARY_CLUSTER_PUBLICIP_NAME

+ service.beta.kubernetes.io/azure-dns-label-name: $AKS_PRIMARY_CLUSTER_PG_DNSPREFIX

+ name: cnpg-cluster-load-balancer-ro

+ namespace: "${PG_NAMESPACE}"

+ spec:

+ type: LoadBalancer

+ ports:

+ - protocol: TCP

+ port: 5433

+ targetPort: 5432

+ selector:

+ cnpg.io/instanceRole: replica

+ cnpg.io/podRole: instance

+ loadBalancerSourceRanges:

+ - "$MY_PUBLIC_CLIENT_IP/32"

+ EOF

+ ```

+1. Get the service details using the [`kubectl describe`][kubectl-describe] command.

+ ```bash

+ kubectl describe service cnpg-cluster-load-balancer-rw \

+ --context $AKS_PRIMARY_CLUSTER_NAME \

+ --namespace $PG_NAMESPACE

+ kubectl describe service cnpg-cluster-load-balancer-ro \

+ --context $AKS_PRIMARY_CLUSTER_NAME \

+ --namespace $PG_NAMESPACE

+ export AKS_PRIMARY_CLUSTER_ALB_DNSNAME="$(az network public-ip show \

+ --resource-group $AKS_PRIMARY_CLUSTER_NODERG_NAME \

+ --name $AKS_PRIMARY_CLUSTER_PUBLICIP_NAME \

+ --query "dnsSettings.fqdn" --output tsv)"

+ echo $AKS_PRIMARY_CLUSTER_ALB_DNSNAME

+ ```

+### Validate public PostgreSQL endpoints

+In this section, you validate that the Azure Load Balancer is properly set up using the static IP that you created earlier and routing connections to the primary read-write and read-only replicas and use the psql CLI to connect to both.

+Remember that the primary read-write endpoint maps to TCP port 5432 and the read-only replica endpoints map to port 5433 to allow the same PostgreSQL DNS name to be used for readers and writers.

+> [!NOTE]

+> You need the value of the app user password for PostgreSQL basic auth that was generated earlier and stored in the `$PG_DATABASE_APPUSER_SECRET` environment variable.

+* Validate the public PostgreSQL endpoints using the following `psql` commands:

+ ```bash

+ echo "Public endpoint for PostgreSQL cluster: $AKS_PRIMARY_CLUSTER_ALB_DNSNAME"

+ # Query the primary, pg_is_in_recovery = false

+

+ psql -h $AKS_PRIMARY_CLUSTER_ALB_DNSNAME \

+ -p 5432 -U app -d appdb -W -c "SELECT pg_is_in_recovery();"

+ ```

+ Example output

+ ```output

+ pg_is_in_recovery

+ -

+ f

+ (1 row)

+ ```

+ ```bash

+ echo "Query a replica, pg_is_in_recovery = true"

+

+ psql -h $AKS_PRIMARY_CLUSTER_ALB_DNSNAME \

+ -p 5433 -U app -d appdb -W -c "SELECT pg_is_in_recovery();"

+ ```

+ Example output

+ ```output

+ # Example output

+

+ pg_is_in_recovery

+ -

+ t

+ (1 row)

+ ```

+ When successfully connected to the primary read-write endpoint, the PostgreSQL function returns `f` for *false*, indicating that the current connection is writable.

+ When connected to a replica, the function returns `t` for *true*, indicating the database is in recovery and read-only.

+## Simulate an unplanned failover

+In this section, you trigger a sudden failure by deleting the pod running the primary, which simulates a sudden crash or loss of network connectivity to the node hosting the PostgreSQL primary.

+1. Check the status of the running pod instances using the following command:

+ ```bash

+ kubectl cnpg status $PG_PRIMARY_CLUSTER_NAME --namespace $PG_NAMESPACE

+ ```

+ Example output

+ ```output

+ Name Current LSN Rep role Status Node

+ -- -- - --

+ pg-primary-cnpg-sryti1qf-1 0/9000060 Primary OK aks-postgres-32388626-vmss000000

+ pg-primary-cnpg-sryti1qf-2 0/9000060 Standby (sync) OK aks-postgres-32388626-vmss000001

+ pg-primary-cnpg-sryti1qf-3 0/9000060 Standby (sync) OK aks-postgres-32388626-vmss000002

+ ```

+1. Delete the primary pod using the [`kubectl delete`][kubectl-delete] command.

+ ```bash

+ PRIMARY_POD=$(kubectl get pod \

+ --namespace $PG_NAMESPACE \

+ --no-headers \

+ -o custom-columns=":metadata.name" \

+ -l role=primary)

+

+ kubectl delete pod $PRIMARY_POD --grace-period=1 --namespace $PG_NAMESPACE

+ ```

+1. Validate that the `pg-primary-cnpg-sryti1qf-2` pod instance is now the primary using the following command:

+ ```bash

+ kubectl cnpg status $PG_PRIMARY_CLUSTER_NAME --namespace $PG_NAMESPACE

+ ```

+ Example output

+ ```output

+ pg-primary-cnpg-sryti1qf-2 0/9000060 Primary OK aks-postgres-32388626-vmss000001

+ pg-primary-cnpg-sryti1qf-1 0/9000060 Standby (sync) OK aks-postgres-32388626-vmss000000

+ pg-primary-cnpg-sryti1qf-3 0/9000060 Standby (sync) OK aks-postgres-32388626-vmss000002

+ ```

+1. Reset the `pg-primary-cnpg-sryti1qf-1` pod instance as the primary using the following command:

+ ```bash

+ kubectl cnpg promote $PG_PRIMARY_CLUSTER_NAME 1 --namespace $PG_NAMESPACE

+ ```

+1. Validate that the pod instances have returned to their original state before the unplanned failover test using the following command:

+ ```bash

+ kubectl cnpg status $PG_PRIMARY_CLUSTER_NAME --namespace $PG_NAMESPACE

+ ```

+ Example output

+ ```output

+ Name Current LSN Rep role Status Node

+ -- -- - --

+ pg-primary-cnpg-sryti1qf-1 0/9000060 Primary OK aks-postgres-32388626-vmss000000

+ pg-primary-cnpg-sryti1qf-2 0/9000060 Standby (sync) OK aks-postgres-32388626-vmss000001

+ pg-primary-cnpg-sryti1qf-3 0/9000060 Standby (sync) OK aks-postgres-32388626-vmss000002

+ ```

+## Clean up resources

+* Once you're finished reviewing your deployment, delete all the resources you created in this guide using the [`az group delete`][az-group-delete] command.

+ ```bash

+ az group delete --resource-group $RESOURCE_GROUP_NAME --no-wait --yes

+ ```

+## Next steps

+In this how-to guide, you learned how to:

+* Use Azure CLI to create a multi-zone AKS cluster.

+* Deploy a highly available PostgreSQL cluster and database using the CNPG operator.

+* Set up monitoring for PostgreSQL using Prometheus and Grafana.

+* Deploy a sample dataset to the PostgreSQL database.

+* Perform PostgreSQL and AKS cluster upgrades.

+* Simulate a cluster interruption and PostgreSQL replica failover.

+* Perform a backup and restore of the PostgreSQL database.

+To learn more about how you can leverage AKS for your workloads, see [What is Azure Kubernetes Service (AKS)?][what-is-aks]

+## Contributors

+*This article is maintained by Microsoft. It was originally written by the following contributors*:

+* Ken Kilty | Principal TPM

+* Russell de Pina | Principal TPM

+* Adrian Joian | Senior Customer Engineer

+* Jenny Hayes | Senior Content Developer

+* Carol Smith | Senior Content Developer

+* Erin Schaffer | Content Developer 2

+* Adam Sharif | Customer Engineer 2

+<!-- LINKS -->

+[helm-upgrade]: https://helm.sh/docs/helm/helm_upgrade/

+[create-infrastructure]: ./create-postgresql-ha.md

+[kubectl-create-secret]: https://kubernetes.io/docs/reference/kubectl/generated/kubectl_create/kubectl_create_secret/

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

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

+[helm-repo-add]: https://helm.sh/docs/helm/helm_repo_add/

+[az-aks-show]: /cli/azure/aks#az_aks_show

+[az-identity-federated-credential-create]: /cli/azure/identity/federated-credential#az_identity_federated_credential_create

+[cluster-crd]: https://cloudnative-pg.io/documentation/1.23/cloudnative-pg.v1/#postgresql-cnpg-io-v1-ClusterSpec

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

+[az-storage-blob-list]: /cli/azure/storage/blob/#az_storage_blob_list

+[az-identity-federated-credential-delete]: /cli/azure/identity/federated-credential#az_identity_federated_credential_delete

+[kubectl-delete]: https://kubernetes.io/docs/reference/kubectl/generated/kubectl_delete/

+[az-group-delete]: /cli/azure/group#az_group_delete

+[what-is-aks]: ./what-is-aks.md

+ Title: 'Overview of deploying a highly available PostgreSQL database on AKS with Azure CLI'

+description: Learn how to deploy a highly available PostgreSQL database on AKS using the CloudNativePG operator.

+#Customer intent: As a developer or cluster operator, I want to deploy a highly available PostgreSQL database on AKS so I can see how to run a stateful database workload using the managed Kubernetes service in Azure.

+# Deploy a highly available PostgreSQL database on AKS with Azure CLI

+In this guide, you deploy a highly available PostgreSQL cluster that spans multiple Azure availability zones on AKS with Azure CLI.

+This article walks through the prerequisites for setting up a PostgreSQL cluster on [Azure Kubernetes Service (AKS)][what-is-aks] and provides an overview of the full deployment process and architecture.

+## Prerequisites

+* This guide assumes a basic understanding of [core Kubernetes concepts][core-kubernetes-concepts] and [PostgreSQL][postgresql].

+* You need the **Owner** or **User Access Administrator** and the **Contributor** [Azure built-in roles][azure-roles] on a subscription in your Azure account.

+* You also need the following resources installed:

+ * [Azure CLI](/cli/azure/install-azure-cli) version 2.56 or later.

+ * [Azure Kubernetes Service (AKS) preview extension][aks-preview].

+ * [jq][jq], version 1.5 or later.

+ * [kubectl][install-kubectl] version 1.21.0 or later.

+ * [Helm][install-helm] version 3.0.0 or later.

+ * [openssl][install-openssl] version 3.3.0 or later.

+ * [Visual Studio Code][install-vscode] or equivalent.

+ * [Krew][install-krew] version 0.4.4 or later.

+ * [kubectl CloudNativePG (CNPG) Plugin][cnpg-plugin].

+## Deployment process

+In this guide, you learn how to:

+* Use Azure CLI to create a multi-zone AKS cluster.

+* Deploy a highly available PostgreSQL cluster and database using the [CNPG operator][cnpg-plugin].

+* Set up monitoring for PostgreSQL using Prometheus and Grafana.

+* Deploy a sample dataset to a PostgreSQL database.

+* Perform PostgreSQL and AKS cluster upgrades.

+* Simulate a cluster interruption and PostgreSQL replica failover.

+* Perform backup and restore of a PostgreSQL database.

+## Deployment architecture

+This diagram illustrates a PostgreSQL cluster setup with one primary replica and two read replicas managed by the [CloudNativePG (CNPG)](https://cloudnative-pg.io/) operator. The architecture provides a highly available PostgreSQL running on an AKS cluster that can withstand a zone outage by failing over across replicas.

+Backups are stored on [Azure Blob Storage](/azure/storage/blobs/), providing another way to restore the database in the event of an issue with streaming replication from the primary replica.

+> [!NOTE]

+> The CNPG operator supports only *one database per cluster*. Plan accordingly for applications that require data separation at the database level.

+## Next steps

+> [!div class="nextstepaction"]

+> [Create the infrastructure to deploy a highly available PostgreSQL database on AKS using the CNPG operator][create-infrastructure]

+## Contributors

+*This article is maintained by Microsoft. It was originally written by the following contributors*:

+* Ken Kilty | Principal TPM

+* Russell de Pina | Principal TPM

+* Adrian Joian | Senior Customer Engineer

+* Jenny Hayes | Senior Content Developer

+* Carol Smith | Senior Content Developer

+* Erin Schaffer | Content Developer 2

+* Adam Sharif | Customer Engineer 2

+<!-- LINKS -->

+[what-is-aks]: ./what-is-aks.md

+[postgresql]: https://www.postgresql.org/

+[core-kubernetes-concepts]: ./concepts-clusters-workloads.md

+[azure-roles]: ../role-based-access-control/built-in-roles.md

+[aks-preview]: ./draft.md#install-the-aks-preview-azure-cli-extension

+[jq]: https://jqlang.github.io/jq/

+[install-kubectl]: https://kubernetes.io/docs/tasks/tools/install-kubectl/

+[install-helm]: https://helm.sh/docs/intro/install/

+[install-openssl]: https://www.openssl.org/

+[install-vscode]: https://code.visualstudio.com/Download

+[install-krew]: https://krew.sigs.k8s.io/

+[cnpg-plugin]: https://cloudnative-pg.io/documentation/current/kubectl-plugin/#using-krew

+[create-infrastructure]: ./create-postgresql-ha.md

+ * Each supported minor version can support any number of patches at a given time. AKS reserves the right to deprecate patches if a critical CVE or security vulnerability is detected. For awareness on patch availability and any ad-hoc deprecation, please refer to version release notes and visit the [AKS release status webpage][aks-tracker].

+AKS may support any number of **patches** based on upstream community release availability for a given minor version. AKS reserves the right to deprecate any of these patches at any given time due to a CVE or potential bug concern. You're always encouraged to use the latest patch for a minor version.

+ Title: Tutorial - Discover shadow APIs using Dev Proxy

+description: In this tutorial, you learn how to discover shadow APIs in your apps using Dev Proxy and onboard them to API Center.

+# Tutorial - Discover shadow APIs using Dev Proxy

+Using Azure API Center you catalog APIs used in your organization. This allows you to tell which APIs you use, where the API is in its lifecycle, and who to contact if there are issues. In short, having an up-to-date catalog of APIs helps you improve the governance-, compliance-, and security posture.

+When building your app, especially if you're integrating new scenarios, you might be using APIs that aren't registered in Azure API Center. These APIs are called shadow APIs. Shadow APIs are APIs that aren't registered in your organization. They might be APIs that aren't yet registered, or they might be APIs that aren't meant to be used in your organization.

+One way to check for shadow APIs is by using [Dev Proxy](https://aka.ms/devproxy). Dev Proxy is an API simulator that intercepts and analyzes API requests from applications. One feature of Dev Proxy is checking if the intercepted API requests belong to APIs registered in API Center.

+## Before you start

+To detect shadow APIs, you need to have an [Azure API Center](/azure/api-center/) instance with information about the APIs that you use in your organization.

+### Copy API Center information

+From the Azure API Center instance Overview page, copy the **name** of the API Center instance, the name of the **resource group** and the **subscription ID**. You need this information to configure the Dev Proxy `ApiCenterOnboardingPlugin` so that it can connect to your Azure API Center instance.

+## Configure Dev Proxy

+To check if your app is using shadow APIs, you need to enable the `ApiCenterOnboardingPlugin` in the Dev Proxy configuration file. To create a report of APIs that your app uses, add a reporter.

+### Enable the `ApiCenterOnboardingPlugin`

+In the `devproxyrc.json` file, add the following configuration:

+```json

+{

+ "$schema": "https://raw.githubusercontent.com/microsoft/dev-proxy/main/schemas/v0.19.0/rc.schema.json",

+ "plugins": [

+ {

+ "name": "ApiCenterOnboardingPlugin",

+ "enabled": true,

+ "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll",

+ "configSection": "apiCenterOnboardingPlugin"

+ }

+ ],

+ "urlsToWatch": [

+ "https://jsonplaceholder.typicode.com/*"

+ ],

+ "apiCenterOnboardingPlugin": {

+ "subscriptionId": "00000000-0000-0000-0000-000000000000",

+ "resourceGroupName": "demo",

+ "serviceName": "contoso-api-center",

+ "workspaceName": "default",

+ "createApicEntryForNewApis": false

+ }

+}

+```

+In the `subscriptionId`, `resourceGroupName`, and `serviceName` properties, provide the information about your Azure API Center instance.

+In the `urlsToWatch` property, specify the URLs that your app uses.

+> [!TIP]

+> Use the [Dev Proxy Toolkit](https://aka.ms/devproxy/toolkit) Visual Studio Code extension to easily manage Dev Proxy configuration.

+### Add a reporter

+The `ApiCenterOnboardingPlugin` produces a report of APIs that your app is using. To view this report, add a reporter to your Dev Proxy configuration file. Dev Proxy offers several [reporters](/microsoft-cloud/dev/dev-proxy/technical-reference/overview#reporters). In this example, you use the [plain-text reporter](/microsoft-cloud/dev/dev-proxy/technical-reference/plaintextreporter).

+Update your `devproxyrc.json` file with a reference to the plain-text reporter:

+```json

+{

+ "$schema": "https://raw.githubusercontent.com/microsoft/dev-proxy/main/schemas/v0.19.0/rc.schema.json",

+ "plugins": [

+ {

+ "name": "ApiCenterOnboardingPlugin",

+ "enabled": true,

+ "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll",

+ "configSection": "apiCenterOnboardingPlugin"

+ },

+ {

+ "name": "PlainTextReporter",

+ "enabled": true,

+ "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll"

+ }

+ ],

+ "urlsToWatch": [

+ "https://jsonplaceholder.typicode.com/*"

+ ],

+ "apiCenterOnboardingPlugin": {

+ "subscriptionId": "00000000-0000-0000-0000-000000000000",

+ "resourceGroupName": "demo",

+ "serviceName": "contoso-api-center",

+ "workspaceName": "default",

+ "createApicEntryForNewApis": false

+ }

+}

+```

+## Check if your app is using shadow APIs

+To check if your app is using shadow APIs, connect to your Azure subscription, run Dev Proxy, and let it intercept API requests from your app. Dev Proxy then compares the information about the API requests with the information from Azure API Center and reports on any APIs that aren't registered in API Center.

+### Connect to your Azure subscription

+Dev Proxy uses information from Azure API Center to determine if your app is using shadow APIs. To get this information, it needs a connection to your Azure subscription. You can connect to your Azure subscription in [several ways](/microsoft-cloud/dev/dev-proxy/technical-reference/apicenterproductionversionplugin#remarks).

+### Run Dev Proxy

+After connecting to your Azure subscription, start Dev Proxy. If you start Dev Proxy from the same folder where your `devproxyrc.json` file is located, it automatically loads the configuration. Otherwise, specify the path to the configuration file using the `--config-file` option.

+When Dev Proxy starts, it checks that it can connect to your Azure subscription. When the connection is successful, you see a message similar to:

+```text

+ info Plugin ApiCenterOnboardingPlugin connecting to Azure...

+ info Listening on 127.0.0.1:8000...

+Hotkeys: issue (w)eb request, (r)ecord, (s)top recording, (c)lear screen

+Press CTRL+C to stop Dev Proxy

+```

+Press <kbd>r</kbd> to start recording API requests from your app.

+### Use your app

+Use your app as you would normally do. Dev Proxy intercepts the API requests and stores information about them in memory. In the command line where Dev Proxy runs, you should see information about API requests that your app makes.

+```text

+ info Plugin ApiCenterOnboardingPlugin connecting to Azure...

+ info Listening on 127.0.0.1:8000...

+Hotkeys: issue (w)eb request, (r)ecord, (s)top recording, (c)lear screen

+Press CTRL+C to stop Dev Proxy

+Γùë Recording...

+ req Γò¡ GET https://jsonplaceholder.typicode.com/posts

+ api Γò░ Passed through

+ req Γò¡ DELETE https://jsonplaceholder.typicode.com/posts/1

+ api Γò░ Passed through

+```

+### Check shadow APIs

+Stop the recording by pressing <kbd>s</kbd>. Dev Proxy connects to the API Center instance and compares the information about requests with the information from API Center.

+```text

+ info Plugin ApiCenterOnboardingPlugin connecting to Azure...

+ info Listening on 127.0.0.1:8000...

+Hotkeys: issue (w)eb request, (r)ecord, (s)top recording, (c)lear screen

+Press CTRL+C to stop Dev Proxy

+Γùë Recording...

+ req Γò¡ GET https://jsonplaceholder.typicode.com/posts

+ api Γò░ Passed through

+ req Γò¡ DELETE https://jsonplaceholder.typicode.com/posts/1

+ api Γò░ Passed through

+Γùï Stopped recording

+ info Checking if recorded API requests belong to APIs in API Center...

+ info Loading APIs from API Center...

+ info Loading API definitions from API Center...

+```

+When Dev Proxy finishes its analysis, it creates a report in a file named `ApiCenterOnboardingPlugin_PlainTextReporter.txt` with the following contents:

+```text

+New APIs that aren't registered in Azure API Center:

+https://jsonplaceholder.typicode.com:

+ DELETE https://jsonplaceholder.typicode.com/posts/1

+APIs that are already registered in Azure API Center:

+GET https://jsonplaceholder.typicode.com/posts

+```

+### Automatically onboard shadow APIs

+The `ApiCenterOnboardingPlugin` can not only detect shadow APIs, but also automatically onboard them to API Center. To automatically onboard shadow APIs, in the Dev Proxy configuration file, update the `createApicEntryForNewApis` to `true`.

+```json

+{

+ "$schema": "https://raw.githubusercontent.com/microsoft/dev-proxy/main/schemas/v0.19.0/rc.schema.json",

+ "plugins": [

+ {

+ "name": "ApiCenterOnboardingPlugin",

+ "enabled": true,

+ "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll",

+ "configSection": "apiCenterOnboardingPlugin"

+ },

+ {

+ "name": "PlainTextReporter",

+ "enabled": true,

+ "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll"

+ }

+ ],

+ "urlsToWatch": [

+ "https://jsonplaceholder.typicode.com/*"

+ ],

+ "apiCenterOnboardingPlugin": {

+ "subscriptionId": "00000000-0000-0000-0000-000000000000",

+ "resourceGroupName": "demo",

+ "serviceName": "contoso-api-center",

+ "workspaceName": "default",

+ "createApicEntryForNewApis": true

+ }

+}

+```

+When you run Dev Proxy with `createApicEntryForNewApis` set to `true`, it automatically creates new API entries in Azure API Center for the shadow APIs that it detects.

+### Automatically onboard shadow APIs with OpenAPI spec

+When you choose to automatically onboard, shadow APIs to API Center, you can have Dev Proxy generate the OpenAPI spec for the API. Onboarding APIs with OpenAPI specs speeds up onboarding of missing endpoints and provide you with the necessary information about the API. When the `ApiCenterOnboardingPlugin` detects, that Dev Proxy created a new OpenAPI spec, it associates it with the corresponding onboarded API in API Center.

+To automatically generate OpenAPI specs for onboarded APIs, update Dev Proxy configuration to include the [`OpenApiSpecGeneratorPlugin`](/microsoft-cloud/dev/dev-proxy/technical-reference/openapispecgeneratorplugin).

+```json

+{

+ "$schema": "https://raw.githubusercontent.com/microsoft/dev-proxy/main/schemas/v0.19.0/rc.schema.json",

+ "plugins": [

+ {

+ "name": "OpenApiSpecGeneratorPlugin",

+ "enabled": true,

+ "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll"

+ },

+ {

+ "name": "ApiCenterOnboardingPlugin",

+ "enabled": true,

+ "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll",

+ "configSection": "apiCenterOnboardingPlugin"

+ },

+ {

+ "name": "PlainTextReporter",

+ "enabled": true,

+ "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll"

+ }

+ ],

+ "urlsToWatch": [

+ "https://jsonplaceholder.typicode.com/*"

+ ],

+ "apiCenterOnboardingPlugin": {

+ "subscriptionId": "00000000-0000-0000-0000-000000000000",

+ "resourceGroupName": "demo",

+ "serviceName": "contoso-api-center",

+ "workspaceName": "default",

+ "createApicEntryForNewApis": true

+ }

+}

+```

+> [!IMPORTANT]

+> Dev Proxy executes plugins in the order they're registered in the configuration. You need to register the `OpenApiSpecGeneratorPlugin` first so that it can create OpenAPI specs before the `ApiCenterOnboardingPlugin` onboards new APIs.

+When you run Dev Proxy with this configuration, it automatically creates new API entries in Azure API Center for the shadow APIs that it detects. For each new API, Dev Proxy generates an OpenAPI spec and associates it with the corresponding onboarded API in API Center.

+```text

+ info Plugin ApiCenterOnboardingPlugin connecting to Azure...

+ info Listening on 127.0.0.1:8000...

+Hotkeys: issue (w)eb request, (r)ecord, (s)top recording, (c)lear screen

+Press CTRL+C to stop Dev Proxy

+Γùë Recording...

+ req Γò¡ GET https://jsonplaceholder.typicode.com/posts

+ api Γò░ Passed through

+ req Γò¡ DELETE https://jsonplaceholder.typicode.com/posts/1

+ api Γò░ Passed through

+Γùï Stopped recording

+ info Creating OpenAPI spec from recorded requests...

+ info Created OpenAPI spec file jsonplaceholder.typicode.com-20240614104931.json

+ info Checking if recorded API requests belong to APIs in API Center...

+ info Loading APIs from API Center...

+ info Loading API definitions from API Center...

+ info New APIs that aren't registered in Azure API Center:

+https://jsonplaceholder.typicode.com:

+ DELETE https://jsonplaceholder.typicode.com/posts/1

+ info Creating new API entries in API Center...

+ info Creating API new-jsonplaceholder-typicode-com-1718354977 for https://jsonplaceholder.typicode.com...

+ info DONE

+```

+## Summary

+Using Dev Proxy and its `ApiCenterOnboardingPlugin`, you can check if your app is using shadow APIs. The plugin analyzes API requests from your app and reports on any API requests that aren't registered in Azure API Center. The plugin allows you to easily onboard missing APIs to API Center. By combining the `ApiCenterOnboardingPlugin` plugin with the `OpenApiSpecGeneratorPlugin`, you can automatically generate OpenAPI specs for the newly onboarded APIs. You can run this check manually or integrate with your CI/CD pipeline to ensure that your app is using registered APIs before releasing it to production.

+## More information

+- [Learn more about Dev Proxy](/microsoft-cloud/dev/dev-proxy/overview)

+- [Learn more about Azure API Center](./key-concepts.md)

+ Title: 'Tutorial: Add Azure OpenAI text completions to your functions in Visual Studio Code'

+description: Learn how to connect Azure Functions to OpenAI by adding an output binding to your Visual Studio Code project.

+zone_pivot_groups: programming-languages-set-functions

+#customer intent: As an Azure developer, I want learn how to integrate Azure OpenAI capabilities in my function code to leverage AI benefits in my colud-based code executions.

+# Tutorial: Add Azure OpenAI text completion hints to your functions in Visual Studio Code

+This article shows you how to use Visual Studio Code to add an HTTP endpoint to the function app you created in the previous quickstart article. When triggered, this new HTTP endpoint uses an [Azure Open AI text completion input binding](functions-bindings-openai-textcompletion-input.md) to get text completion hints from your data model.

+During this tutorial, you learn how to accomplish these tasks:

+> [!div class="checklist"]

+> * Create resources in Azure OpenAI.

+> * Deploy a model in OpenAI the resource.

+> * Set access permissions to the model resource.

+> * Enable your function app to connect to OpenAI.

+> * Add OpenAI bindings to your HTTP triggered function.

+## 1. Check prerequisites

+* Complete the steps in [part 1 of the Visual Studio Code quickstart](create-first-function-vs-code-csharp.md).

+* Complete the steps in [part 1 of the Visual Studio Code quickstart](create-first-function-vs-code-java.md).

+* Complete the steps in [part 1 of the Visual Studio Code quickstart](create-first-function-vs-code-node.md).

+* Complete the steps in [part 1 of the Visual Studio Code quickstart](create-first-function-vs-code-typescript.md).

+* Complete the steps in [part 1 of the Visual Studio Code quickstart](create-first-function-vs-code-python.md).

+* Complete the steps in [part 1 of the Visual Studio Code quickstart](create-first-function-vs-code-powershell.md).

+* Obtain access to Azure OpenAI in your Azure subscription. If you haven't already been granted access, complete [this form](https://aka.ms/oai/access) to request access.

+* Install [.NET Core CLI tools](/dotnet/core/tools/?tabs=netcore2x).

+* The [Azurite storage emulator](../storage/common/storage-use-azurite.md?tabs=npm#install-azurite). While you can also use an actual Azure Storage account, the article assumes you're using this emulator.

+

+## 2. Create your Azure OpenAI resources

+The following steps show how to create an Azure OpenAI data model in the Azure portal.

+1. Sign in with your Azure subscription in the [Azure portal](https://portal.azure.com).

+1. Select **Create a resource** and search for the **Azure OpenAI**. When you locate the service, select **Create**.

+1. On the **Create Azure OpenAI** page, provide the following information for the fields on the **Basics** tab:

+ | Field | Description |

+ |||

+ | **Subscription** | Your subscription, which has been onboarded to use Azure OpenAI. |

+ | **Resource group** | The resource group you created for the function app in the previous article. You can find this resource group name by right-clicking the function app in the Azure Resources browser, selecting properties, and then searching for the `resourceGroup` setting in the returned JSON resource file. |

+ | **Region** | Ideally, the same location as the function app. |

+ | **Name** | A descriptive name for your Azure OpenAI Service resource, such as _mySampleOpenAI_. |

+ | **Pricing Tier** | The pricing tier for the resource. Currently, only the Standard tier is available for the Azure OpenAI Service. For more info on pricing visit the [Azure OpenAI pricing page](https://azure.microsoft.com/pricing/details/cognitive-services/openai-service/) |

+ :::image type="content" source="../ai-services/openai/media/create-resource/create-resource-basic-settings.png" alt-text="Screenshot that shows how to configure an Azure OpenAI resource in the Azure portal.":::

+1. Select **Next** twice to accept the default values for both the **Network** and **Tags** tabs. The service you create doesn't have any network restrictions, including from the internet.

+1. Select **Next** a final time to move to the final stage in the process: **Review + submit**.

+1. Confirm your configuration settings, and select **Create**.

+ The Azure portal displays a notification when the new resource is available. Select **Go to resource** in the notification or search for your new Azure OpenAI resource by name.

+1. In the Azure OpenAI resource page for your new resource, select **Click here to view endpoints** under **Essentials** > **Endpoints**. Copy the **endpoint** URL and the **keys**. Save these values, you need them later.

+Now that you have the credentials to connect to your model in Azure OpenAI, you need to set these access credentials in application settings.

+## 3. Deploy a model

+Now you can deploy a model. You can select from one of several available models in Azure OpenAI Studio.

+To deploy a model, follow these steps:

+1. Sign in to [Azure OpenAI Studio](https://oai.azure.com).

+1. Choose the subscription and the Azure OpenAI resource you created, and select **Use resource**.

+1. Under **Management** select **Deployments**.

+1. Select **Create new deployment** and configure the following fields:

+ | Field | Description |

+ |||

+ | **Deployment name** | Choose a name carefully. The deployment name is used in your code to call the model by using the client libraries and the REST APIs, so you must save for use later on. |

+ | **Select a model** | Model availability varies by region. For a list of available models per region, see [Model summary table and region availability](../ai-services/openai/concepts/models.md#model-summary-table-and-region-availability). |

+ > [!IMPORTANT]

+ > When you access the model via the API, you need to refer to the deployment name rather than the underlying model name in API calls, which is one of the key differences between OpenAI and Azure OpenAI. OpenAI only requires the model name. Azure OpenAI always requires deployment name, even when using the model parameter. In our docs, we often have examples where deployment names are represented as identical to model names to help indicate which model works with a particular API endpoint. Ultimately your deployment names can follow whatever naming convention is best for your use case.

+1. Accept the default values for the rest of the setting and select **Create**.

+ The deployments table shows a new entry that corresponds to your newly created model.

+You now have everything you need to add Azure OpenAI-based text completion to your function app.

+## 4. Update application settings

+1. In Visual Studio Code, open the local code project you created when you completed the [previous article](./create-first-function-vs-code-csharp.md).

+1. In the local.settings.json file in the project root folder, update the `AzureWebJobsStorage` setting to `UseDevelopmentStorage=true`. You can skip this step if the `AzureWebJobsStorage` setting in *local.settings.json* is set to the connection string for an existing Azure Storage account instead of `UseDevelopmentStorage=true`.

+1. In the local.settings.json file, add these settings values:

+ + **`AZURE_OPENAI_ENDPOINT`**: required by the binding extension. Set this value to the endpoint of the Azure OpenAI resource you created earlier.

+ + **`AZURE_OPENAI_KEY`**: required by the binding extension. Set this value to the key for the Azure OpenAI resource.

+ + **`CHAT_MODEL_DEPLOYMENT_NAME`**: used to define the input binding. Set this value to the name you chose for your model deployment.

+1. Save the file. When you deploy to Azure, you must also add these settings to your function app.

+## 5. Register binding extensions

+Because you're using an Azure OpenAI output binding, you must have the corresponding bindings extension installed before you run the project.

+Except for HTTP and timer triggers, bindings are implemented as extension packages. To add the Azure OpenAI extension package to your project, run this [dotnet add package](/dotnet/core/tools/dotnet-add-package) command in the **Terminal** window:

+```bash

+dotnet add package Microsoft.Azure.Functions.Worker.Extensions.OpenAI --prerelease

+```

+<!NOTE: Update this after preview to `## Verify the extension bundle`-->

+## 5. Update the extension bundle

+To access the preview Azure OpenAI bindings, you must use a preview version of the extension bundle that contains this extension.

+Replace the `extensionBundle` setting in your current `host.json` file with this JSON:

+```json

+ "extensionBundle": {

+ "id": "Microsoft.Azure.Functions.ExtensionBundle.Preview",

+ "version": "[4.*, 5.0.0)"

+ }

+```

+Now, you can use the Azure OpenAI output binding in your project.

+## 6. Return text completion from the model

+The code you add creates a `whois` HTTP function endpoint in your existing project. In this function, data passed in a URL `name` parameter of a GET request is used to dynamically create a completion prompt. This dynamic prompt is bound to a text completion input binding, which returns a response from the model based on the prompt. The completion from the model is returned in the HTTP response.

+1. In your existing `HttpExample` class file, add this `using` statement:

+ :::code language="csharp" source="~/functions-openai-extension/samples/textcompletion/csharp-ooproc/TextCompletions.cs" range="5" :::

+1. In the same file, add this code that defines a new HTTP trigger endpoint named `whois`:

+ ```csharp

+ [Function(nameof(WhoIs))]

+ public IActionResult WhoIs([HttpTrigger(AuthorizationLevel.Function, Route = "whois/{name}")] HttpRequest req,

+ [TextCompletionInput("Who is {name}?", Model = "%CHAT_MODEL_DEPLOYMENT_NAME%")] TextCompletionResponse response)

+ {

+ if(!String.IsNullOrEmpty(response.Content))

+ {

+ return new OkObjectResult(response.Content);

+ }

+ else

+ {

+ return new NotFoundObjectResult("Something went wrong.");

+ }

+ }

+ ```

+1. Update the `pom.xml` project file to add this reference to the `properties` collection:

+ :::code language="xml" source="~/functions-openai-extension/samples/textcompletion/java/pom.xml" range="18" :::

+1. In the same file, add this dependency to the `dependencies` collection:

+ :::code language="xml" source="~/functions-openai-extension/samples/textcompletion/java/pom.xml" range="29-33" :::

+1. In the existing `Function.java` project file, add these `import` statements:

+ :::code language="java" source="~/functions-openai-extension/samples/textcompletion/java/src/main/java/com/azfs/TextCompletions.java" range="19-20" :::

+1. In the same file, add this code that defines a new HTTP trigger endpoint named `whois`:

+ :::code language="java" source="~/functions-openai-extension/samples/textcompletion/java/src/main/java/com/azfs/TextCompletions.java" range="31-46" :::

+1. In Visual Studio Code, Press F1 and in the command palette type `Azure Functions: Create Function...`, select **HTTP trigger**, type the function name `whois`, and press Enter.

+1. In the new `whois.js` code file, replace the contents of the file with this code:

+ :::code language="javascript" source="~/functions-openai-extension/samples/textcompletion/javascript/src/functions/whois.js" :::

+

+1. In Visual Studio Code, Press F1 and in the command palette type `Azure Functions: Create Function...`, select **HTTP trigger**, type the function name `whois`, and press Enter.

+1. In the new `whois.ts` code file, replace the contents of the file with this code:

+ :::code language="typescript" source="~/functions-openai-extension/samples/textcompletion/typescript/src/functions/whois.ts" :::

+

+1. In the existing `function_app.py` project file, add this `import` statement:

+ :::code language="python" source="~/functions-openai-extension/samples/textcompletion/python/function_app.py" range="1" :::

+1. In the same file, add this code that defines a new HTTP trigger endpoint named `whois`:

+ :::code language="python" source="~/functions-openai-extension/samples/textcompletion/python/function_app.py" range="7-18" :::

+

+1. In Visual Studio Code, Press F1 and in the command palette type `Azure Functions: Create Function...`, select **HTTP trigger**, type the function name `whois`, select **Anonymous**, and press Enter.

+1. Open the new `whois/function.json` code file and replace its contents with this code, which adds a definition for the `TextCompletionResponse` input binding:

+ :::code language="json" source="~/functions-openai-extension/samples/textcompletion/powershell/WhoIs/function.json" :::

+

+1. Replace the content of the `whois/run.ps1` code file with this code, which returns the input binding response:

+ :::code language="powershell" source="~/functions-openai-extension/samples/textcompletion/powershell/WhoIs/run.ps1" :::

+

+## 7. Run the function

+1. In Visual Studio Code, Press F1 and in the command palette type `Azurite: Start` and press Enter to start the Azurite storage emulator.

+1. Press <kbd>F5</kbd> to start the function app project and Core Tools in debug mode.

+1. With the Core Tools running, send a GET request to the `whois` endpoint function, with a name in the path, like this URL:

+ `http://localhost:7071/api/whois/<NAME>`

+ Replace the `<NAME>` string with the value you want passed to the `"Who is {name}?"` prompt. The `<NAME>` must be the URL-encoded name of a public figure, like `Abraham%20Lincoln`.

+ The response you see is the text completion response from your Azure OpenAI model.

+1. After a response is returned, press <kbd>Ctrl + C</kbd> to stop Core Tools.

+<!-- enable managed identities

+## 8. Set access permissions

+{{move this info into the main article}}

+[create Azure OpenAI resources and to deploy models](../ai-services/openai/how-to/role-based-access-control.md).

+## 9. Deploy to Azure

+-->

+## 8. Clean up resources

+In Azure, *resources* refer to function apps, functions, storage accounts, and so forth. They're grouped into *resource groups*, and you can delete everything in a group by deleting the group.

+You created resources to complete these quickstarts. You could be billed for these resources, depending on your [account status](https://azure.microsoft.com/account/) and [service pricing](https://azure.microsoft.com/pricing/). If you don't need the resources anymore, here's how to delete them:

+## Related content

+## Application settings

+To use the Azure OpenAI binding extension, you need to add one or more of these settings, which are used to connect to your OpenAI resource. During local development, you also need to add these settings to your `local.settings.json` file.

+| Setting name | Description |

+| - | -- |

+| **`AZURE_OPENAI_ENDPOINT`** | Required. Sets the endpoint of the OpenAI resource used by your bindings. |

+| **`AZURE_OPENAI_KEY`** | Sets the key used to access an Azure OpenAI resource. |

+| **`OPENAI_API_KEY`** | Sets the key used to access a non-Azure OpenAI resource. |

+| **`AZURE_CLIENT_ID`** | Sets a user-assigned managed identity used to access the Azure OpenAI resource. |

+For more information, see [Work with application settings](functions-how-to-use-azure-function-app-settings.md#settings).

+

+Azure Functions on Container Apps runs your containerized function app resources in specially managed resource groups. These managed resource groups help protect the consistency of your apps by preventing unintended or unauthorized modification or deletion of resources in the managed group, even by service principals.

+Besides data processing, Azure Functions can be used to infer on models. The [Azure OpenAI binding extension](./functions-bindings-openai.md) lets easily integrate features and behaviors of the [Azure OpenAI service](../ai-services/openai/overview.md) into your function code executions.

+Functions can connect to an OpenAI resources to enable text and chat completions, use assistants, and leverage embeddings and semantic search.

+A function might also call a TensorFlow model or Azure AI services to process and classify a stream of images.

+| Pri index | Pri Name |

+| | |

+| 0 | None |

+| 1 | Kern |

+| 2 | user |

+| 3 | mail |

+| 4 | daemon |

+| 4 | auth |

+| 5 | syslog |

+| 6 | lpr |

+| 7 | news |

+| 8 | uucp |

+| 9 | ftp |

+| 10 | ntp |

+| 11 | audit |

+| 12 | alert |

+| 13 | mark |

+| 14 | local0 |

+| 15 | local1 |

+| 16 | local2 |

+| 17 | local3 |

+| 18 | local4 |

+| 19 | local5 |

+| 20 | local6 |

+| 21 | local7 |

+* [`Log4J`, Logback, or java.util.logging](./opentelemetry-add-modify.md?tabs=java#send-custom-telemetry-using-the-application-insights-classic-api)

+ Title: Application Insights availability tests

+description: Set up recurring web tests to monitor availability and responsiveness of your app or website.

+# Application Insights availability tests

+After you deploy your web app or website, you can set up recurring tests to monitor availability and responsiveness. [Application Insights](./app-insights-overview.md) sends web requests to your application at regular intervals from points around the world. It can alert you if your application isn't responding or responds too slowly. You can create up to 100 availability tests per Application Insights resource.

+Availability tests don't require any changes to the website you're testing and work for any HTTP or HTTPS endpoint that's accessible from the public internet. You can also test the availability of a REST API that your service depends on.

+> [!NOTE]

+> Availability tests are stored encrypted, according to [Azure data encryption at rest](../../security/fundamentals/encryption-atrest.md#encryption-at-rest-in-microsoft-cloud-services) policies.

+## Types of availability tests

+There are four types of availability tests:

+* Standard test: This is a type of availability test that checks the availability of a website by sending a single request, similar to the deprecated URL ping test. In addition to validating whether an endpoint is responding and measuring the performance, Standard tests also include TLS/SSL certificate validity, proactive lifetime check, HTTP request verb (for example, `GET`,`HEAD`, and `POST`), custom headers, and custom data associated with your HTTP request.

+* Custom TrackAvailability test: If you decide to create a custom application to run availability tests, you can use the [TrackAvailability()](/dotnet/api/microsoft.applicationinsights.telemetryclient.trackavailability) method to send the results to Application Insights.

+* [(Deprecated) Multi-step web test](availability-multistep.md): You can play back this recording of a sequence of web requests to test more complex scenarios. Multi-step web tests are created in Visual Studio Enterprise and uploaded to the portal, where you can run them.

+* [(Deprecated) URL ping test](monitor-web-app-availability.md): You can create this test through the Azure portal to validate whether an endpoint is responding and measure performance associated with that response. You can also set custom success criteria coupled with more advanced features, like parsing dependent requests and allowing for retries.

+> [!IMPORTANT]

+> There are two upcoming availability tests retirements:

+> * **Multi-step web tests:** On August 31, 2024, multi-step web tests in Application Insights will be retired. We advise users of these tests to transition to alternative availability tests before the retirement date. Following this date, we will be taking down the underlying infrastructure which will break remaining multi-step tests.

+>

+> * **URL ping tests:** On September 30, 2026, URL ping tests in Application Insights will be retired. Existing URL ping tests will be removed from your resources. Review the [pricing](https://azure.microsoft.com/pricing/details/monitor/#pricing) for standard tests and [transition](https://aka.ms/availabilitytestmigration) to using them before September 30, 2026 to ensure you can continue to run single-step availability tests in your Application Insights resources.

+<!-- Move this message to "previous-version" documents for both web tests

+> [!IMPORTANT]

+> [Multi-step web test](availability-multistep.md) and [URL ping test](monitor-web-app-availability.md) rely on the DNS infrastructure of the public internet to resolve the domain names of the tested endpoints. If you're using private DNS, you must ensure that the public domain name servers can resolve every domain name of your test. When that's not possible, you can use [custom TrackAvailability tests](/dotnet/api/microsoft.applicationinsights.telemetryclient.trackavailability) instead.

+-->

+## Create an availability test

+## [Standard test](#tab/standard)

+> [!TIP]

+> If you're currently using other availability tests, like URL ping tests, you might add Standard tests alongside the others. If you want to use Standard tests instead of one of your other tests, add a Standard test and delete your old test.

+### Prerequisites

+> [!div class="checklist"]

+> * [Workspace-based Application Insights resource](create-workspace-resource.md)

+### Get started

+1. Go to your Application Insights resource and select the **Availability** pane.

+1. Select **Add Standard test**.

+ :::image type="content" source="./media/availability-standard-test/standard-test.png" alt-text="Screenshot that shows the Availability pane with the Add Standard test tab open." lightbox="./media/availability-standard-test/standard-test.png":::

+1. Input your test name, URL, and other settings that are described in the following table. Then, select **Create**.

+ | Setting | Description |

+ ||-|

+ | **URL** | The URL can be any webpage you want to test, but it must be visible from the public internet. The URL can include a query string. So, for example, you can exercise your database a little. If the URL resolves to a redirect, we follow it up to 10 redirects. |

+ | **Parse dependent requests** | Test requests images, scripts, style files, and other files that are part of the webpage under test. The recorded response time includes the time taken to get these files. The test fails if any of these resources can't be successfully downloaded within the timeout for the whole test. If the option isn't selected, the test only requests the file at the URL you specified. Enabling this option results in a stricter check. The test could fail for cases, which might not be noticeable when you manually browse the site. Please note, we parse only up to 15 dependent requests. |

+ | **Enable retries** | When the test fails, it's retried after a short interval. A failure is reported only if three successive attempts fail. Subsequent tests are then performed at the usual test frequency. Retry is temporarily suspended until the next success. This rule is applied independently at each test location. *We recommend this option*. On average, about 80% of failures disappear on retry. |

+ | **SSL certificate validation test** | You can verify the SSL certificate on your website to make sure it's correctly installed, valid, trusted, and doesn't give any errors to any of your users. |

+ | **Proactive lifetime check** | This setting enables you to define a set time period before your SSL certificate expires. After it expires, your test will fail. |

+ | **Test frequency** | Sets how often the test is run from each test location. With a default frequency of five minutes and five test locations, your site is tested on average every minute. |

+ | **Test locations** | Our servers send web requests to your URL from these locations. *Our minimum number of recommended test locations is five* to ensure that you can distinguish problems in your website from network issues. You can select up to 16 locations. |

+ | **Custom headers** | Key value pairs that define the operating parameters. |

+ | **HTTP request verb** | Indicate what action you want to take with your request. |

+ | **Request body** | Custom data associated with your HTTP request. You can upload your own files, enter your content, or disable this feature. |

+### Success criteria

+| Setting | Description |

+|--|--|

+| **Test timeout** | Decrease this value to be alerted about slow responses. The test is counted as a failure if the responses from your site haven't been received within this period. If you selected **Parse dependent requests**, all the images, style files, scripts, and other dependent resources must have been received within this period. |

+| **HTTP response** | The returned status code that's counted as a success. The number 200 is the code that indicates that a normal webpage has been returned. |

+| **Content match** | A string, like "Welcome!" We test that an exact case-sensitive match occurs in every response. It must be a plain string, without wildcards. Don't forget that if your page content changes, you might have to update it. *Only English characters are supported with content match.* |

+## [TrackAvailability()](#tab/track)

+> [!IMPORTANT]

+> [TrackAvailability()](/dotnet/api/microsoft.applicationinsights.telemetryclient.trackavailability) requires making a developer investment in writing and maintanining potentially complex custom code.

+>

+> *Standard tests should always be used if possible*, as they require little investment, no maintenance, and have few prerequisites.

+### Prerequisites

+> [!div class="checklist"]

+> * [Workspace-based Application Insights resource](create-workspace-resource.md)

+> * Access to the source code of a [function app](../../azure-functions/functions-how-to-use-azure-function-app-settings.md) in Azure Functions

+> * Developer expertise capable of authoring [custom code](#basic-code-sample) for [TrackAvailability()](/dotnet/api/microsoft.applicationinsights.telemetryclient.trackavailability), tailored to your specific business needs

+### Basic code sample

+> [!NOTE]

+> This example is designed solely to show you the mechanics of how the `TrackAvailability()` API call works within an Azure function. It doesn't show you how to write the underlying HTTP test code or business logic that's required to turn this example into a fully functional availability test.

+>

+> By default, if you walk through this example, you'll be creating a basic availability HTTP GET test. To follow these instructions, you must use the [dedicated plan](../../azure-functions/dedicated-plan.md) to allow editing code in App Service Editor.

+#### Create a timer trigger function

+1. Create an Azure Functions resource.

+ * **If you already have an Application Insights resource:**

+ By default, Azure Functions creates an Application Insights resource. If you want to use a resource you created previously, you must specify that during creation.

+ Follow the instructions on how to [create an Azure Functions resource](../../azure-functions/functions-create-scheduled-function.md#create-a-function-app) with the following modification:

+ On the **Monitoring** tab, select the **Application Insights** dropdown box and then enter or select the name of your resource:

+ :::image type="content" source="media/availability-azure-functions/app-insights-resource.png" alt-text="Screenshot that shows selecting your existing Application Insights resource on the Monitoring tab.":::

+ * **If you don't have an Application Insights resource created yet for your timer-triggered function:**

+ By default, when you're creating your Azure Functions application, it creates an Application Insights resource for you. Follow the instructions on how to [create an Azure Functions resource](../../azure-functions/functions-create-scheduled-function.md#create-a-function-app).

+ > [!NOTE]

+ > You can host your functions on a Consumption, Premium, or App Service plan. If you're testing behind a virtual network or testing nonpublic endpoints, you'll need to use the Premium plan in place of the Consumption plan. Select your plan on the **Hosting** tab. Ensure the latest .NET version is selected when you create the function app.

+1. Create a timer trigger function.

+ 1. In your function app, select the **Functions** tab.

+ 1. Select **Add**. On the **Add function** pane, select the following configurations:

+ * **Development environment**: Develop in portal

+ * **Select a template**: Timer trigger

+ 1. Select **Add** to create the timer trigger function.

+ :::image type="content" source="media/availability-azure-functions/add-function.png" alt-text="Screenshot that shows how to add a timer trigger function to your function app." lightbox="media/availability-azure-functions/add-function.png":::

+#### Add and edit code in the App Service Editor

+Go to your deployed function app, and under **Development Tools**, select the **App Service Editor** tab.

+To create a new file, right-click under your timer trigger function (for example, **TimerTrigger1**) and select **New File**. Then enter the name of the file and select **Enter**.

+1. Create a new file called **function.proj** and paste the following code:

+ ```xml

+ <Project Sdk="Microsoft.NET.Sdk">

+ <PropertyGroup>

+ <TargetFramework>netstandard2.0</TargetFramework>

+ </PropertyGroup>

+ <ItemGroup>

+ <PackageReference Include="Microsoft.ApplicationInsights" Version="2.15.0" /> <!-- Ensure youΓÇÖre using the latest version -->

+ </ItemGroup>

+ </Project>

+ ```

+ :::image type="content" source="media/availability-azure-functions/function-proj.png" alt-text=" Screenshot that shows function.proj in the App Service Editor." lightbox="media/availability-azure-functions/function-proj.png":::

+1. Create a new file called **runAvailabilityTest.csx** and paste the following code:

+ ```csharp

+ using System.Net.Http;

+ public async static Task RunAvailabilityTestAsync(ILogger log)

+ {

+ using (var httpClient = new HttpClient())

+ {

+ // TODO: Replace with your business logic

+ await httpClient.GetStringAsync("https://www.bing.com/");

+ }

+ }

+ ```

+1. Define the `REGION_NAME` environment variable as a valid Azure availability location.

+ Run the following command in the [Azure CLI](/cli/azure/account?view=azure-cli-latest#az-account-list-locations&preserve-view=true) to list available regions.

+ ```azurecli

+ az account list-locations -o table

+ ```

+1. Copy the following code into the **run.csx** file. (You replace the pre-existing code.)

+ ```csharp

+ #load "runAvailabilityTest.csx"

+ using System;

+ using System.Diagnostics;

+ using Microsoft.ApplicationInsights;

+ using Microsoft.ApplicationInsights.Channel;

+ using Microsoft.ApplicationInsights.DataContracts;

+ using Microsoft.ApplicationInsights.Extensibility;

+ private static TelemetryClient telemetryClient;

+ // =============================================================

+ // ****************** DO NOT MODIFY THIS FILE ******************

+ // Business logic must be implemented in RunAvailabilityTestAsync function in runAvailabilityTest.csx

+ // If this file does not exist, please add it first

+ // =============================================================

+ public async static Task Run(TimerInfo myTimer, ILogger log, ExecutionContext executionContext)

+ {

+ if (telemetryClient == null)

+ {

+ // Initializing a telemetry configuration for Application Insights based on connection string

+ var telemetryConfiguration = new TelemetryConfiguration();

+ telemetryConfiguration.ConnectionString = Environment.GetEnvironmentVariable("APPLICATIONINSIGHTS_CONNECTION_STRING");

+ telemetryConfiguration.TelemetryChannel = new InMemoryChannel();

+ telemetryClient = new TelemetryClient(telemetryConfiguration);

+ }

+ string testName = executionContext.FunctionName;

+ string location = Environment.GetEnvironmentVariable("REGION_NAME");

+ var availability = new AvailabilityTelemetry

+ {

+ Name = testName,

+ RunLocation = location,

+ Success = false,

+ };

+ availability.Context.Operation.ParentId = Activity.Current.SpanId.ToString();

+ availability.Context.Operation.Id = Activity.Current.RootId;

+ var stopwatch = new Stopwatch();

+ stopwatch.Start();

+ try

+ {

+ using (var activity = new Activity("AvailabilityContext"))

+ {

+ activity.Start();

+ availability.Id = Activity.Current.SpanId.ToString();

+ // Run business logic

+ await RunAvailabilityTestAsync(log);

+ }

+ availability.Success = true;

+ }

+ catch (Exception ex)

+ {

+ availability.Message = ex.Message;

+ throw;

+ }

+ finally

+ {

+ stopwatch.Stop();

+ availability.Duration = stopwatch.Elapsed;

+ availability.Timestamp = DateTimeOffset.UtcNow;

+ telemetryClient.TrackAvailability(availability);

+ telemetryClient.Flush();

+ }

+ }

+ ```

+#### Multi-step web test code sample

+Follow the same instructions above and instead paste the following code into the **runAvailabilityTest.csx** file:

+```csharp

+using System.Net.Http;

+public async static Task RunAvailabilityTestAsync(ILogger log)

+{

+ using (var httpClient = new HttpClient())

+ {

+ // TODO: Replace with your business logic

+ await httpClient.GetStringAsync("https://www.bing.com/");

+ // TODO: Replace with your business logic for an additional monitored endpoint, and logic for additional steps as needed

+ await httpClient.GetStringAsync("https://www.learn.microsoft.com/");

+ }

+}

+```

+## Availability alerts

+| Setting | Description |

+||-|

+| **Near real time** | We recommend using near real time alerts. Configuring this type of alert is done after your availability test is created. |

+| **Alert location threshold** |We recommend a minimum of 3/5 locations. The optimal relationship between alert location threshold and the number of test locations is **alert location threshold** = **number of test locations - 2, with a minimum of five test locations.** |

+### Location population tags

+You can use the following population tags for the geo-location attribute when you deploy an availability URL ping test by using Azure Resource Manager.

+#### Azure

+| Display name | Population name |

+|-|-|

+| Australia East | emea-au-syd-edge |

+| Brazil South | latam-br-gru-edge |

+| Central US | us-fl-mia-edge |

+| East Asia | apac-hk-hkn-azr |

+| East US | us-va-ash-azr |

+| France South (Formerly France Central) | emea-ch-zrh-edge |

+| France Central | emea-fr-pra-edge |

+| Japan East | apac-jp-kaw-edge |

+| North Europe | emea-gb-db3-azr |

+| North Central US | us-il-ch1-azr |

+| South Central US | us-tx-sn1-azr |

+| Southeast Asia | apac-sg-sin-azr |

+| UK West | emea-se-sto-edge |

+| West Europe | emea-nl-ams-azr |

+| West US | us-ca-sjc-azr |

+| UK South | emea-ru-msa-edge |

+#### Azure Government

+| Display name | Population name |

+|-||

+| USGov Virginia | usgov-va-azr |

+| USGov Arizona | usgov-phx-azr |

+| USGov Texas | usgov-tx-azr |

+| USDoD East | usgov-ddeast-azr |

+| USDoD Central | usgov-ddcentral-azr |

+#### Microsoft Azure operated by 21Vianet

+| Display name | Population name |

+|-||

+| China East | mc-cne-azr |

+| China East 2 | mc-cne2-azr |

+| China North | mc-cnn-azr |

+| China North 2 | mc-cnn2-azr |

+### Enable alerts

+Alerts are now automatically enabled by default, but to fully configure an alert, you must initially create your availability test.

+> [!NOTE]

+> With the [new unified alerts](../alerts/alerts-overview.md), the alert rule severity and notification preferences with [action groups](../alerts/action-groups.md) *must be* configured in the alerts experience. Without the following steps, you'll only receive in-portal notifications.

+<!--

+-->

+1. After you save the availability test, on the **Details** tab, select the ellipsis by the test you made. Select **Open Rules (Alerts) page**.

+ :::image type="content" source="./media/availability-alerts/edit-alert.png" alt-text="Screenshot that shows the Availability pane for an Application Insights resource in the Azure portal and the Open Rules (Alerts) page menu option." lightbox="./media/availability-alerts/edit-alert.png":::

+1. Set the severity level, rule description, and action group that have the notification preferences you want to use for this alert rule.

+### Alert criteria

+Automatically enabled availability alerts trigger an email when the endpoint you've defined is unavailable and when it's available again. Availability alerts that are created through this experience are state based. When the alert criteria are met, a single alert gets generated when the website is detected as unavailable. If the website is still down the next time the alert criteria is evaluated, it won't generate a new alert.

+For example, suppose that your website is down for an hour and you've set up an email alert with an evaluation frequency of 15 minutes. You'll only receive an email when the website goes down and another email when it's back online. You won't receive continuous alerts every 15 minutes to remind you that the website is still unavailable.

+You might not want to receive notifications when your website is down for only a short period of time, for example, during maintenance. You can change the evaluation frequency to a higher value than the expected downtime, up to 15 minutes. You can also increase the alert location threshold so that it only triggers an alert if the website is down for a specific number of regions. For longer scheduled downtimes, temporarily deactivate the alert rule or create a custom rule. It gives you more options to account for the downtime.

+#### Change the alert criteria

+To make changes to the location threshold, aggregation period, and test frequency, select the condition on the edit page of the alert rule to open the "**Configure signal logic**" window.

+### Create a custom alert rule

+If you need advanced capabilities, you can create a custom alert rule on the **Alerts** tab. Select **Create** > **Alert rule**. Choose **Metrics** for **Signal type** to show all available signals and select **Availability**.

+A custom alert rule offers higher values for the aggregation period (up to 24 hours instead of 6 hours) and the test frequency (up to 1 hour instead of 15 minutes). It also adds options to further define the logic by selecting different operators, aggregation types, and threshold values.

+* **Alert on X out of Y locations reporting failures**: The X out of Y locations alert rule is enabled by default in the [new unified alerts experience](../alerts/alerts-overview.md) when you create a new availability test. You can opt out by selecting the "classic" option or by choosing to disable the alert rule. Configure the action groups to receive notifications when the alert triggers by following the preceding steps. Without this step, you'll only receive in-portal notifications when the rule triggers.

+* **Alert on availability metrics**: By using the [new unified alerts](../alerts/alerts-overview.md), you can alert on segmented aggregate availability and test duration metrics too:

+ 1. Select an Application Insights resource in the **Metrics** experience, and select an **Availability** metric.

+

+ 1. The **Configure alerts** option from the menu takes you to the new experience where you can select specific tests or locations on which to set up alert rules. You can also configure the action groups for this alert rule here.

+* **Alert on custom analytics queries**: By using the [new unified alerts](../alerts/alerts-overview.md), you can alert on [custom log queries](../alerts/alerts-types.md#log-alerts). With custom queries, you can alert on any arbitrary condition that helps you get the most reliable signal of availability issues. It's also applicable if you're sending custom availability results by using the TrackAvailability SDK.

+ The metrics on availability data include any custom availability results you might be submitting by calling the TrackAvailability SDK. You can use the alerting on metrics support to alert on custom availability results.

+### Automate alerts

+To automate this process with Azure Resource Manager templates, see [Create a metric alert with an Azure Resource Manager template](../alerts/alerts-metric-create-templates.md#template-for-an-availability-test-along-with-a-metric-alert).

+## See your availability test results

+This section explains how to review availability test results in the Azure portal and query the data using [Log Analytics](../logs/log-analytics-overview.md#overview-of-log-analytics-in-azure-monitor). Availability test results can be visualized with both **Line** and **Scatter Plot** views.

+

+### Check availability

+Start by reviewing the graph on the **Availability** tab of your Application Insights resource.

+### [Standard test](#tab/standard)

+### [TrackAvailability](#tab/track)

+> [!NOTE]

+> Tests created with `TrackAvailability()` will appear with **CUSTOM** next to the test name.

+The **Scatter Plot** view shows samples of the test results that have diagnostic test-step detail in them. The test engine stores diagnostic detail for tests that have failures. For successful tests, diagnostic details are stored for a subset of the executions. Hover over any of the green/red dots to see the test, test name, and location.

+Select a particular test or location. Or you can reduce the time period to see more results around the time period of interest. Use Search Explorer to see results from all executions. Or you can use Log Analytics queries to run custom reports on this data.

+To see the end-to-end transaction details, under **Drill into**, select **Successful** or **Failed**. Then select a sample. You can also get to the end-to-end transaction details by selecting a data point on the graph.

+### Inspect and edit tests

+To edit, temporarily disable, or delete a test, select the ellipses next to a test name. It might take up to 20 minutes for configuration changes to propagate to all test agents after a change is made.

+You might want to disable availability tests or the alert rules associated with them while you're performing maintenance on your service.

+### If you see failures

+Select a red dot.

+From an availability test result, you can see the transaction details across all components. Here you can:

+* Review the troubleshooting report to determine what might have caused your test to fail but your application is still available.

+* Inspect the response received from your server.

+* Diagnose failure with correlated server-side telemetry collected while processing the failed availability test.

+* Log an issue or work item in Git or Azure Boards to track the problem. The bug will contain a link to this event.

+* Open the web test result in Visual Studio.

+To learn more about the end-to-end transaction diagnostics experience, see the [transaction diagnostics documentation](./transaction-search-and-diagnostics.md?tabs=transaction-diagnostics).

+Select the exception row to see the details of the server-side exception that caused the synthetic availability test to fail. You can also get the [debug snapshot](./snapshot-debugger.md) for richer code-level diagnostics.

+In addition to the raw results, you can also view two key availability metrics in [metrics explorer](../essentials/metrics-getting-started.md):

+* **Availability**: Percentage of the tests that were successful across all test executions.

+* **Test Duration**: Average test duration across all test executions.

+### Query in Log Analytics

+You can use Log Analytics to view your availability results, dependencies, and more. To learn more about Log Analytics, see [Log query overview](../logs/log-query-overview.md).

+## Migrate availability tests

+In this article, we guide you through the process of migrating from [classic URL ping tests](/previous-versions/azure/azure-monitor/app/monitor-web-app-availability) to the modern and efficient [standard tests](availability-standard-tests.md).

+We simplify this process by providing clear step-by-step instructions to ensure a seamless transition and equip your applications with the most up-to-date monitoring capabilities.

+### Migrate classic URL ping tests to standard tests

+The following steps walk you through the process of creating [standard tests](availability-standard-tests.md) that replicate the functionality of your [URL ping tests](/previous-versions/azure/azure-monitor/app/monitor-web-app-availability). It allows you to more easily start using the advanced features of [standard tests](availability-standard-tests.md) using your previously created [URL ping tests](/previous-versions/azure/azure-monitor/app/monitor-web-app-availability).

+> [!IMPORTANT]

+> A cost is associated with running **[standard tests](/editor/availability-standard-tests.md)**. Once you create a **[standard test](/editor/availability-standard-tests.md)**, you will be charged for test executions. Refer to **[Azure Monitor pricing](https://azure.microsoft.com/pricing/details/monitor/#pricing)** before starting this process.

+#### Prerequisites

+* Any [URL ping test](/previous-versions/azure/azure-monitor/app/monitor-web-app-availability) within Application Insights

+* [Azure PowerShell](/powershell/azure/get-started-azureps) access

+#### Get started

+1. Connect to your subscription with Azure PowerShell (Connect-AzAccount + Set-AzContext).

+1. List all URL ping tests in the current subscription:

+ ```azurepowershell

+ Get-AzApplicationInsightsWebTest | `

+ Where-Object { $_.WebTestKind -eq "ping" } | `

+ Format-Table -Property ResourceGroupName,Name,WebTestKind,Enabled;

+ ```

+1. Find the URL Ping Test you want to migrate and record its resource group and name.

+1. The following commands create a standard test with the same logic as the URL ping test.

+ > [!NOTE]

+ > The following commands work for both HTTP and HTTPS endpoints, which are used in your URL ping Tests.

+ ```shell

+ $resourceGroup = "pingTestResourceGroup";

+ $appInsightsComponent = "componentName";

+ $pingTestName = "pingTestName";

+ $newStandardTestName = "newStandardTestName";

+

+ $componentId = (Get-AzApplicationInsights -ResourceGroupName $resourceGroup -Name $appInsightsComponent).Id;

+ $pingTest = Get-AzApplicationInsightsWebTest -ResourceGroupName $resourceGroup -Name $pingTestName;

+ $pingTestRequest = ([xml]$pingTest.ConfigurationWebTest).WebTest.Items.Request;

+ $pingTestValidationRule = ([xml]$pingTest.ConfigurationWebTest).WebTest.ValidationRules.ValidationRule;

+

+ $dynamicParameters = @{};

+

+ if ($pingTestRequest.IgnoreHttpStatusCode -eq [bool]::FalseString) {

+ $dynamicParameters["RuleExpectedHttpStatusCode"] = [convert]::ToInt32($pingTestRequest.ExpectedHttpStatusCode, 10);

+ }

+

+ if ($pingTestValidationRule -and $pingTestValidationRule.DisplayName -eq "Find Text" `

+ -and $pingTestValidationRule.RuleParameters.RuleParameter[0].Name -eq "FindText" `

+ -and $pingTestValidationRule.RuleParameters.RuleParameter[0].Value) {

+ $dynamicParameters["ContentMatch"] = $pingTestValidationRule.RuleParameters.RuleParameter[0].Value;

+ $dynamicParameters["ContentPassIfTextFound"] = $true;

+ }

+

+ New-AzApplicationInsightsWebTest @dynamicParameters -ResourceGroupName $resourceGroup -Name $newStandardTestName `

+ -Location $pingTest.Location -Kind 'standard' -Tag @{ "hidden-link:$componentId" = "Resource" } -TestName $newStandardTestName `

+ -RequestUrl $pingTestRequest.Url -RequestHttpVerb "GET" -GeoLocation $pingTest.PropertiesLocations -Frequency $pingTest.Frequency `

+ -Timeout $pingTest.Timeout -RetryEnabled:$pingTest.RetryEnabled -Enabled:$pingTest.Enabled `

+ -RequestParseDependent:($pingTestRequest.ParseDependentRequests -eq [bool]::TrueString);

+ ```

+1. The new standard test doesn't have alert rules by default, so it doesn't create noisy alerts. No changes are made to your URL ping test so you can continue to rely on it for alerts.

+1. Once you have validated the functionality of the new standard test, [update your alert rules](/azure/azure-monitor/alerts/alerts-manage-alert-rules) that reference the URL ping test to reference the standard test instead. Then you disable or delete the URL ping test.

+1. To delete a URL ping test with Azure PowerShell, you can use this command:

+ ```azurepowershell

+ Remove-AzApplicationInsightsWebTest -ResourceGroupName $resourceGroup -Name $pingTestName;

+ ```

+## Testing behind a firewall

+To ensure endpoint availability behind firewalls, enable public availability tests or run availability tests in disconnected or no ingress scenarios.

+### Public availability test enablement

+Ensure your internal website has a public Domain Name System (DNS) record. Availability tests fail if DNS can't be resolved. For more information, see [Create a custom domain name for internal application](../../cloud-services/cloud-services-custom-domain-name-portal.md#add-an-a-record-for-your-custom-domain).

+> [!WARNING]

+> The IP addresses used by the availability tests service are shared and can expose your firewall-protected service endpoints to other tests. IP address filtering alone doesn't secure your service's traffic, so it's recommended to add extra custom headers to verify the origin of web request. For more information, see [Virtual network service tags](../../virtual-network/service-tags-overview.md#virtual-network-service-tags).

+#### Authenticate traffic

+Set custom headers in [standard availability tests](availability-standard-tests.md) to validate traffic.

+1. Generate a token or GUID to identify traffic from your availability tests.

+1. Add the custom header "X-Customer-InstanceId" with the value `ApplicationInsightsAvailability:<GUID generated in step 1>` under the "Standard test info" section when creating or updating your availability tests.

+1. Ensure your service checks if incoming traffic includes the header and value defined in the previous steps.

+ :::image type="content" source="media/availability-private-test/custom-validation-header.png" alt-text="Screenshot that shows custom validation header.":::

+Alternatively, set the token as a query parameter. For example, `https://yourtestendpoint/?x-customer-instanceid=applicationinsightsavailability:<your guid>`.

+#### Configure your firewall to permit incoming requests from availability tests

+> [!NOTE]

+> This example is specific to network security group service tag usage. Many Azure services accept service tags, each requiring different configuration steps.

+* To simplify enabling Azure services without authorizing individual IPs or maintaining an up-to-date IP list, use [Service tags](../../virtual-network/service-tags-overview.md). Apply these tags across Azure Firewall and network security groups, allowing the availability test service access to your endpoints. The service tag `ApplicationInsightsAvailability` applies to all availability tests.

+ 1. If you're using [Azure network security groups](../../virtual-network/network-security-groups-overview.md), go to your network security group resource and under **Settings**, select **inbound security rules**. Then select **Add**.

+ :::image type="content" source="media/availability-private-test/add.png" alt-text="Screenshot that shows the inbound security rules tab in the network security group resource.":::

+ 1. Next, select **Service Tag** as the source and select **ApplicationInsightsAvailability** as the source service tag. Use open ports 80 (http) and 443 (https) for incoming traffic from the service tag.

+ :::image type="content" source="media/availability-private-test/service-tag.png" alt-text="Screenshot that shows the Add inbound security rules tab with a source of service tag.":::

+* To manage access when your endpoints are outside Azure or when service tags aren't an option, allowlist the [IP addresses of our web test agents](ip-addresses.md). You can query IP ranges using PowerShell, Azure CLI, or a REST call with the [Service Tag API](../../virtual-network/service-tags-overview.md#use-the-service-tag-discovery-api). For a comprehensive list of current service tags and their IP details, download the [JSON file](../../virtual-network/service-tags-overview.md#discover-service-tags-by-using-downloadable-json-files).

+

+ 1. In your network security group resource, under **Settings**, select **inbound security rules**. Then select **Add**.

+ 1. Next, select **IP Addresses** as your source. Then add your IP addresses in a comma-delimited list in source IP address/CIRD ranges.

+ :::image type="content" source="media/availability-private-test/ip-addresses.png" alt-text="Screenshot that shows the Add inbound security rules tab with a source of IP addresses.":::

+### Disconnected or no ingress scenarios

+1. Connect your Application Insights resource to your internal service endpoint using [Azure Private Link](../logs/private-link-security.md).

+1. Write custom code to periodically test your internal server or endpoints. Send the results to Application Insights using the [TrackAvailability()](availability-azure-functions.md) API in the core SDK package.

+### Supported TLS configurations

+To provide best-in-class encryption, all availability tests use Transport Layer Security (TLS) 1.2 and 1.3 as the encryption mechanisms of choice. In addition, the following Cipher suites and Elliptical curves are also supported within each version.

+> [!NOTE]

+> TLS 1.3 is currently only available in the availability test regions NorthCentralUS, CentralUS, EastUS, SouthCentralUS, and WestUS.

+#### TLS 1.2

+**Cipher suites**

+* TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

+* TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

+* TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

+* TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

+* TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384

+* TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256

+* TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384

+* TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256

+**Elliptical curves**

+* NistP384

+* NistP256

+#### TLS 1.3

+**Cipher suites**

+* TLS_AES_256_GCM_SHA384

+* TLS_AES_128_GCM_SHA256

+**Elliptical curves:**

+* NistP384

+* NistP256

+### Deprecating TLS configuration

+> [!WARNING]

+> On 31 October 2024, in alignment with the [Azure wide legacy TLS deprecation](https://azure.microsoft.com/updates/azure-support-tls-will-end-by-31-october-2024-2/), TLS 1.0/1.1 protocol versions and the below listed TLS 1.2/1.3 legacy Cipher suites and Elliptical curves will be retired for Application Insights availability tests.

+#### TLS 1.0 and TLS 1.1

+Protocol versions will no longer be supported.

+#### TLS 1.2

+**Cipher suites**

+* TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA

+* TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA

+* TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA

+* TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA

+* TLS_RSA_WITH_AES_256_GCM_SHA384

+* TLS_RSA_WITH_AES_128_GCM_SHA256

+* TLS_RSA_WITH_AES_256_CBC_SHA256

+* TLS_RSA_WITH_AES_128_CBC_SHA256

+* TLS_RSA_WITH_AES_256_CBC_SHA

+* TLS_RSA_WITH_AES_128_CBC_SHA

+**Elliptical curves:**

+* curve25519

+#### TLS 1.3

+**Elliptical curves**

+* curve25519

+### Troubleshooting

+> [!WARNING]

+> We have recently enabled TLS 1.3 in availability tests. If you are seeing new error messages as a result, please ensure that clients running on Windows Server 2022 with TLS 1.3 enabled can connect to your endpoint. If you are unable to do this, you may consider temporarily disabling TLS 1.3 on your endpoint so that availability tests will fall back to older TLS versions.

+> For additional information, please check the [troubleshooting article](/troubleshoot/azure/azure-monitor/app-insights/troubleshoot-availability).

+See the dedicated [troubleshooting article](/troubleshoot/azure/azure-monitor/app-insights/troubleshoot-availability).

+## Downtime, SLA, and outages workbook

+This article introduces a simple way to calculate and report service-level agreement (SLA) for web tests through a single pane of glass across your Application Insights resources and Azure subscriptions. The downtime and outage report provides powerful prebuilt queries and data visualizations to enhance your understanding of your customer's connectivity, typical application response time, and experienced downtime.

+The SLA workbook template can be accessed from your Application Insights resource in two ways:

+* Open the **Availability** pane, then select **SLA Report** at the top of the screen.

+ :::image type="content" source="./media/sla-report/availability.png" alt-text="Screenshot that shows the **Availability** tab with SLA Report highlighted." lightbox="./media/sla-report/availability.png":::

+* Open the **Workbooks** pane, then select **Downtime & Outages**.

+ :::image type="content" source="./media/sla-report/workbook-gallery.png" alt-text="Screenshot of the workbook gallery with the Downtime & Outages workbook highlighted." lightbox ="./media/sla-report/workbook-gallery.png":::

+### Parameter flexibility

+The parameters set in the workbook influence the rest of your report.

+* `Subscriptions`, `App Insights Resources`, and `Web Test`: These parameters determine your high-level resource options. They're based on Log Analytics queries and are used in every report query.

+* `Failure Threshold` and `Outage Window`: You can use these parameters to determine your own criteria for a service outage. An example is the criteria for an Application Insights availability alert based on a failed location counter over a chosen period. The typical threshold is three locations over a five-minute window.

+* `Maintenance Period`: You can use this parameter to select your typical maintenance frequency. `Maintenance Window` is a datetime selector for an example maintenance period. All data that occurs during the identified period will be ignored in your results.

+* `Availability Target %`: This parameter specifies your target objective and takes custom values.

+### Overview page

+The overview page contains high-level information about your:

+* Total SLA (excluding maintenance periods, if defined)

+* End-to-end outage instances

+* Application downtime

+Outage instances are defined by when a test starts to fail until it's successful, based on your outage parameters. If a test starts failing at 8:00 AM and succeeds again at 10:00 AM, that entire period of data is considered the same outage.

+You can also investigate the longest outage that occurred over your reporting period.

+Some tests are linkable back to their Application Insights resource for further investigation. But that's only possible in the [workspace-based Application Insights resource](create-workspace-resource.md).

+### Downtime, outages, and failures

+The **Outages & Downtime** tab has information on total outage instances and total downtime broken down by test.

+The **Failures by Location** tab has a geo-map of failed testing locations to help identify potential problem connection areas.

+### Edit the report

+You can edit the report like any other [Azure Monitor workbook](../visualize/workbooks-overview.md).

+You can customize the queries or visualizations based on your team's needs.

+#### Log Analytics

+The queries can all be run in [Log Analytics](../logs/log-analytics-overview.md) and used in other reports or dashboards.

+Remove the parameter restriction and reuse the core query.

+### Access and sharing

+The report can be shared with your teams and leadership or pinned to a dashboard for further use. The user needs to have read permission/access to the Application Insights resource where the actual workbook is stored.

+## Frequently asked questions

+This section provides answers to common questions.

+### General

+#### Can I run availability tests on an intranet server?

+Our [web tests](/previous-versions/azure/azure-monitor/app/monitor-web-app-availability) run on points of presence that are distributed around the globe. There are two solutions:

+

+* **Firewall door**: Allow requests to your server from [the long and changeable list of web test agents](../ip-addresses.md).

+* **Custom code**: Write your own code to send periodic requests to your server from inside your intranet. You could run Visual Studio web tests for this purpose. The tester could send the results to Application Insights by using the `TrackAvailability()` API.

+#### What is the user agent string for availability tests?

+The user agent string is **Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Trident/5.0; AppInsights)**

+### TLS Support

+#### How does this deprecation impact my web test behavior?

+Availability tests act as a distributed client in each of the supported web test locations. Every time a web test is executed the availability test service attempts to reach out to the remote endpoint defined in the web test configuration. A TLS Client Hello message is sent which contains all the currently supported TLS configuration. If the remote endpoint shares a common TLS configuration with the availability test client, then the TLS handshake succeeds. Otherwise, the web test fails with a TLS handshake failure.

+#### How do I ensure my web test isn't impacted?

+To avoid any impact, each remote endpoint (including dependent requests) your web test interacts with needs to support at least one combination of the same Protocol Version, Cipher Suite, and Elliptical Curve that availability test does. If the remote endpoint doesn't support the needed TLS configuration, it needs to be updated with support for some combination of the above-mentioned post-deprecation TLS configuration. These endpoints can be discovered through viewing the [Transaction Details](/azure/azure-monitor/app/availability-standard-tests#see-your-availability-test-results) of your web test (ideally for a successful web test execution).

+#### How do I validate what TLS configuration a remote endpoint supports?

+There are several tools available to test what TLS configuration an endpoint supports. One way would be to follow the example detailed on this [page](/security/engineering/solving-tls1-problem#appendix-a-handshake-simulation). If your remote endpoint isn't available via the Public internet, you need to ensure you validate the TLS configuration supported on the remote endpoint from a machine that has access to call your endpoint.

+> [!NOTE]

+> For steps to enable the needed TLS configuration on your web server, it is best to reach out to the team that owns the hosting platform your web server runs on if the process is not known.

+#### After October 31, 2024, what will the web test behavior be for impacted tests?

+There's no one exception type that all TLS handshake failures impacted by this deprecation would present themselves with. However, the most common exception your web test would start failing with would be `The request was aborted: Couldn't create SSL/TLS secure channel`. You should also be able to see any TLS related failures in the TLS Transport [Troubleshooting Step](/troubleshoot/azure/azure-monitor/app-insights/availability/diagnose-ping-test-failure) for the web test result that is potentially impacted.

+#### Can I view what TLS configuration is currently in use by my web test?

+The TLS configuration negotiated during a web test execution can't be viewed. As long as the remote endpoint supports common TLS configuration with availability tests, no impact should be seen post-deprecation.

+#### Which components does the deprecation affect in the availability test service?

+The TLS deprecation detailed in this document should only affect the availability test web test execution behavior after October 31, 2024. For more information about interacting with the availability test service for CRUD operations, see [Azure Resource Manager TLS Support](/azure/azure-resource-manager/management/tls-support). This resource provides more details on TLS support and deprecation timelines.

+#### Where can I get TLS support?

+For any general questions around the legacy TLS problem, see [Solving TLS problems](/security/engineering/solving-tls1-problem).

+## Next steps

+* [Troubleshooting](troubleshoot-availability.md)

+* [Web tests Azure Resource Manager template](/azure/templates/microsoft.insights/webtests?tabs=json)

+* [Web test REST API](/rest/api/application-insights/web-tests)

+* [Custom request telemetry](./api-custom-events-metrics.md#trackrequest)

+* [Custom dependency telemetry](./api-custom-events-metrics.md#trackdependency)

+* [Custom trace telemetry](./api-custom-events-metrics.md#tracktrace)

+* [Custom event telemetry](./api-custom-events-metrics.md#trackevent)

+* [Custom metric telemetry](./api-custom-events-metrics.md#trackmetric)

+* [.NET](./asp-net-dependencies.md)

+* [Java](./opentelemetry-enable.md?tabs=java)

+* Check out [platforms](./app-insights-overview.md#supported-languages) supported by Application Insights.

+* Check out standard context properties collection [configuration](./configuration-with-applicationinsights-config.md#telemetry-initializers-aspnet).

+* Explore [.NET trace logs in Application Insights](./asp-net-trace-logs.md).

+* Explore [Java trace logs in Application Insights](./opentelemetry-add-modify.md?tabs=java#send-custom-telemetry-using-the-application-insights-classic-api).

+* Learn about the [Azure Functions built-in integration with Application Insights](../../azure-functions/functions-monitoring.md?toc=/azure/azure-monitor/toc.json) to monitor functions executions.

+* Learn how to [configure an ASP.NET Core](./asp-net.md) application with Application Insights.

+* Learn how to [diagnose exceptions in your web apps with Application Insights](./asp-net-exceptions.md).

+* Learn how to [extend and filter telemetry](./api-filtering-sampling.md).

+* Use [sampling](./sampling.md) to minimize the amount of telemetry based on data model.

+**Requests**

+* [ASP.NET

+**Dependencies**

+* [HttpClient](https://github.com/open-telemetry/opentelemetry-dotnet/blob/1.0.0-rc9.14/src/OpenTelemetry.Instrumentation.Http/README.md) ┬╣┬▓

+* [SqlClient](https://github.com/open-telemetry/opentelemetry-dotnet/blob/1.0.0-rc9.14/src/OpenTelemetry.Instrumentation.SqlClient/README.md) ┬╣

+**Logging**

+* `ILogger`

+**Requests**

+**Dependencies (plus downstream distributed trace propagation)**

+**Dependencies (without downstream distributed trace propagation)**

+**Metrics**

+**Logs**

+**Default collection**

+Telemetry emitted by the following Azure SDKs is automatically collected by default:

+**Requests for Spring Boot native applications**

+**Dependencies for Spring Boot native applications**

+**Metrics**

+**Logs for Spring Boot native applications**

+For Quartz native applications, look at the [Quarkus documentation](https://quarkus.io/guides/opentelemetry).

+**Requests**

+* [HTTP/HTTPS](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation-http)┬▓

+**Dependencies**

+* [MongoDB](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-mongodb)

+* [MySQL](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-mysql)

+* [Postgres](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-pg)

+* [Redis](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-redis)

+* [Redis-4](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-redis-4)

+* [Azure SDK](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/instrumentation/opentelemetry-instrumentation-azure-sdk)

+**Logs**

+* [Bunyan](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-bunyan)

+* [Winston](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-winston)

+Instrumentations can be configured using `AzureMonitorOpenTelemetryOptions`:

+// Import Azure Monitor OpenTelemetry

+const { useAzureMonitor, AzureMonitorOpenTelemetryOptions } = require("@azure/monitor-opentelemetry");

+// Import OpenTelemetry HTTP Instrumentation to get config type

+const { HttpInstrumentationConfig } = require("@azure/monitor-opentelemetry");

+ // Import HTTP to get type

+const { IncomingMessage } = require("http");

+// Specific Instrumentation configs could be added

+const httpInstrumentationConfig: HttpInstrumentationConfig = {

+ ignoreIncomingRequestHook: (request: IncomingMessage) => {

+ return false; //Return true if you want to ignore a specific request

+ },

+ enabled: true

+};

+// Instrumentations configuration

+const options: AzureMonitorOpenTelemetryOptions = {

+instrumentationOptions: {

+ http: httpInstrumentationConfig,

+ azureSdk: { enabled: true },

+ mongoDb: { enabled: true },

+ mySql: { enabled: true },

+ postgreSql: { enabled: true },

+ redis: { enabled: true },

+ redis4: { enabled: true },

+}

+};

+// Enable Azure Monitor integration

+useAzureMonitor(options);

+**Requests**

+* [Django](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-django) ┬╣

+* [FastApi](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-fastapi) ┬╣

+* [Flask](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-flask) ┬╣

+**Dependencies**

+* [Psycopg2](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-psycopg2)

+* [Requests](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-requests) ┬╣

+* [`Urllib`](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-urllib) ┬╣

+* [`Urllib3`](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-urllib3) ┬╣

+**Logs**

+* [Python logging library](https://docs.python.org/3/howto/logging.html) ⁴

+* ┬╣: Supports automatic reporting of *unhandled/uncaught* exceptions

+* ┬▓: Supports OpenTelemetry Metrics

+* ┬│: By default, logging is only collected at INFO level or higher. To change this setting, see the [configuration options](./java-standalone-config.md#autocollected-logging).

+* ⁴: By default, logging is only collected when that logging is performed at the WARNING level or higher.

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

+after adding the NuGet package for the library.

+The following example demonstrates how the [Runtime Instrumentation](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.Runtime) can be added to collect extra metrics:

+#### [.NET](#tab/net)

+The following example demonstrates how the [Runtime Instrumentation](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.Runtime) can be added to collect extra metrics:

+#### [Java](#tab/java)

+#### [Java native](#tab/java-native)

+You can't use community instrumentation libraries with GraalVM Java native applications.

+#### [Node.js](#tab/nodejs)

+Other OpenTelemetry Instrumentations are available [here](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node) and could be added using TraceHandler in ApplicationInsightsClient:

+#### [Python](#tab/python)

+* OpenTelemetry API

+* Language-specific logging/metrics libraries

+* Application Insights [Classic API](api-custom-events-metrics.md)

+| &nbsp;&nbsp;&nbsp;`ILogger` API | | | | | | | Yes |

+| &nbsp;&nbsp;&nbsp;AI Classic API | Yes | Yes | Yes | Yes | Yes | Yes | Yes |

+| &nbsp;&nbsp;&nbsp;Events Extension | Yes | | | | | | Yes |

+| Histogram | Min, Max, Average, Sum, and Count |

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

+Application startup must subscribe to a Meter by name:

+The `Meter` must be initialized using that same name:

+##### [.NET](#tab/net)

+##### [Java](#tab/java)

+##### [Java native](#tab/java-native)

+1. Inject `OpenTelemetry`:

+ * **Spring**

+ ```java

+ import io.opentelemetry.api.OpenTelemetry;

+

+ @Autowired

+ OpenTelemetry openTelemetry;

+ ```

+ * **Quarkus**

+ ```java

+ import io.opentelemetry.api.OpenTelemetry;

+

+ @Inject

+ OpenTelemetry openTelemetry;

+ ```

+1. Create a histogram:

+ ```java

+ import io.opentelemetry.api.metrics.DoubleHistogram;

+ import io.opentelemetry.api.metrics.Meter;

+

+ Meter meter = openTelemetry.getMeter("OTEL.AzureMonitor.Demo");

+ DoubleHistogram histogram = meter.histogramBuilder("histogram").build();

+ histogram.record(1.0);

+ histogram.record(100.0);

+ histogram.record(30.0);

+ ```

+##### [Node.js](#tab/nodejs)

+// Import the Azure Monitor OpenTelemetry plugin and OpenTelemetry API

+const { useAzureMonitor } = require("@azure/monitor-opentelemetry");

+const { metrics } = require("@opentelemetry/api");

+// Enable Azure Monitor integration

+useAzureMonitor();

+// Get the meter for the "testMeter" namespace

+const meter = metrics.getMeter("testMeter");

+// Create a histogram metric

+let histogram = meter.createHistogram("histogram");

+// Record values to the histogram metric with different tags

+histogram.record(1, { "testKey": "testValue" });

+histogram.record(30, { "testKey": "testValue2" });

+histogram.record(100, { "testKey2": "testValue" });

+##### [Python](#tab/python)

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

+Application startup must subscribe to a Meter by name:

+The `Meter` must be initialized using that same name:

+##### [.NET](#tab/net)

+##### [Java](#tab/java)

+##### [Java native](#tab/java-native)

+1. Inject `OpenTelemetry`:

+ * **Spring**

+ ```java

+ import io.opentelemetry.api.OpenTelemetry;

+

+ @Autowired

+ OpenTelemetry openTelemetry;

+ ```

+ * **Quarkus**

+ ```java

+ import io.opentelemetry.api.OpenTelemetry;

+

+ @Inject

+ OpenTelemetry openTelemetry;

+ ```

+1. Create the counter:

+ ```Java

+ import io.opentelemetry.api.common.AttributeKey;

+ import io.opentelemetry.api.common.Attributes;

+ import io.opentelemetry.api.metrics.LongCounter;

+ import io.opentelemetry.api.metrics.Meter;

+

+

+ Meter meter = openTelemetry.getMeter("OTEL.AzureMonitor.Demo");

+

+ LongCounter myFruitCounter = meter.counterBuilder("MyFruitCounter")

+ .build();

+

+ myFruitCounter.add(1, Attributes.of(AttributeKey.stringKey("name"), "apple", AttributeKey.stringKey("color"), "red"));

+ myFruitCounter.add(2, Attributes.of(AttributeKey.stringKey("name"), "lemon", AttributeKey.stringKey("color"), "yellow"));

+ myFruitCounter.add(1, Attributes.of(AttributeKey.stringKey("name"), "lemon", AttributeKey.stringKey("color"), "yellow"));

+ myFruitCounter.add(2, Attributes.of(AttributeKey.stringKey("name"), "apple", AttributeKey.stringKey("color"), "green"));

+ myFruitCounter.add(5, Attributes.of(AttributeKey.stringKey("name"), "apple", AttributeKey.stringKey("color"), "red"));

+ myFruitCounter.add(4, Attributes.of(AttributeKey.stringKey("name"), "lemon", AttributeKey.stringKey("color"), "yellow"));

+ ```

+##### [Node.js](#tab/nodejs)

+// Import the Azure Monitor OpenTelemetry plugin and OpenTelemetry API

+const { useAzureMonitor } = require("@azure/monitor-opentelemetry");

+const { metrics } = require("@opentelemetry/api");

+// Enable Azure Monitor integration

+useAzureMonitor();

+// Get the meter for the "testMeter" namespace

+const meter = metrics.getMeter("testMeter");

+// Create a counter metric

+let counter = meter.createCounter("counter");

+// Add values to the counter metric with different tags

+counter.add(1, { "testKey": "testValue" });

+counter.add(5, { "testKey2": "testValue" });

+counter.add(3, { "testKey": "testValue2" });

+##### [Python](#tab/python)

+#### Gauge example

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

+Application startup must subscribe to a Meter by name:

+The `Meter` must be initialized using that same name:

+##### [.NET](#tab/net)

+##### [Java](#tab/java)

+##### [Java native](#tab/java-native)

+1. Inject `OpenTelemetry`:

+ * **Spring**

+ ```java

+ import io.opentelemetry.api.OpenTelemetry;

+

+ @Autowired

+ OpenTelemetry openTelemetry;

+ ```

+ * **Quarkus**

+ ```java

+ import io.opentelemetry.api.OpenTelemetry;

+

+ @Inject

+ OpenTelemetry openTelemetry;

+ ```

+1. Create a gauge:

+ ```Java

+ import io.opentelemetry.api.common.AttributeKey;

+ import io.opentelemetry.api.common.Attributes;

+ import io.opentelemetry.api.metrics.Meter;

+

+ Meter meter = openTelemetry.getMeter("OTEL.AzureMonitor.Demo");

+

+ meter.gaugeBuilder("gauge")

+ .buildWithCallback(

+ observableMeasurement -> {

+ double randomNumber = Math.floor(Math.random() * 100);

+ observableMeasurement.record(randomNumber, Attributes.of(AttributeKey.stringKey("testKey"), "testValue"));

+ });

+ ```

+##### [Node.js](#tab/nodejs)

+// Import the useAzureMonitor function and the metrics module from the @azure/monitor-opentelemetry and @opentelemetry/api packages, respectively.

+const { useAzureMonitor } = require("@azure/monitor-opentelemetry");

+const { metrics } = require("@opentelemetry/api");

+// Enable Azure Monitor integration.

+useAzureMonitor();

+// Get the meter for the "testMeter" meter name.

+const meter = metrics.getMeter("testMeter");

+// Create an observable gauge metric with the name "gauge".

+let gauge = meter.createObservableGauge("gauge");

+// Add a callback to the gauge metric. The callback will be invoked periodically to generate a new value for the gauge metric.

+gauge.addCallback((observableResult: ObservableResult) => {

+ // Generate a random number between 0 and 99.

+ let randomNumber = Math.floor(Math.random() * 100);

+ // Set the value of the gauge metric to the random number.

+ observableResult.observe(randomNumber, {"testKey": "testValue"});

+});

+##### [Python](#tab/python)

+* To log an Exception using an Activity:

+ ```csharp

+ // Start a new activity named "ExceptionExample".

+ using (var activity = activitySource.StartActivity("ExceptionExample"))

+ {

+ // Try to execute some code.

+ try

+ {

+ throw new Exception("Test exception");

+ }

+ // If an exception is thrown, catch it and set the activity status to "Error".

+ catch (Exception ex)

+ {

+ activity?.SetStatus(ActivityStatusCode.Error);

+ activity?.RecordException(ex);

+ }

+ }

+ ```

+* To log an Exception using `ILogger`:

+ ```csharp

+ // Create a logger using the logger factory. The logger category name is used to filter and route log messages.

+ var logger = loggerFactory.CreateLogger(logCategoryName);

+

+ // Try to execute some code.

+ try

+ {

+ throw new Exception("Test Exception");

+ }

+ catch (Exception ex)

+ {

+ // Log an error message with the exception. The log level is set to "Error" and the event ID is set to 0.

+ // The log message includes a template and a parameter. The template will be replaced with the value of the parameter when the log message is written.

+ logger.Log(

+ logLevel: LogLevel.Error,

+ eventId: 0,

+ exception: ex,

+ message: "Hello {name}.",

+ args: new object[] { "World" });

+ }

+ ```

+* To log an Exception using an Activity:

+ ```csharp

+ // Start a new activity named "ExceptionExample".

+ using (var activity = activitySource.StartActivity("ExceptionExample"))

+ {

+ // Try to execute some code.

+ try

+ {

+ throw new Exception("Test exception");

+ }

+ // If an exception is thrown, catch it and set the activity status to "Error".

+ catch (Exception ex)

+ {

+ activity?.SetStatus(ActivityStatusCode.Error);

+ activity?.RecordException(ex);

+ }

+ }

+* To log an Exception using `ILogger`:

+ ```csharp

+ // Create a logger using the logger factory. The logger category name is used to filter and route log messages.

+ var logger = loggerFactory.CreateLogger("ExceptionExample");

+

+ try

+ {

+ // Try to execute some code.

+ throw new Exception("Test Exception");

+ }

+ catch (Exception ex)

+ {

+ // Log an error message with the exception. The log level is set to "Error" and the event ID is set to 0.

+ // The log message includes a template and a parameter. The template will be replaced with the value of the parameter when the log message is written.

+ logger.Log(

+ logLevel: LogLevel.Error,

+ eventId: 0,

+ exception: ex,

+ message: "Hello {name}.",

+ args: new object[] { "World" });

+ }

+ ```

+```java

+import io.opentelemetry.api.trace.Span;

+import io.opentelemetry.api.trace.StatusCode;

+Span span = Span.current();

+span.setStatus(StatusCode.ERROR, "errorMessage");

+span.recordException(e);

+```

+// Import the Azure Monitor OpenTelemetry plugin and OpenTelemetry API

+const { useAzureMonitor } = require("@azure/monitor-opentelemetry");

+const { trace } = require("@opentelemetry/api");

+// Enable Azure Monitor integration

+useAzureMonitor();

+// Get the tracer for the "testTracer" namespace

+const tracer = trace.getTracer("testTracer");

+// Start a span with the name "hello"

+let span = tracer.startSpan("hello");

+// Try to throw an error

+try{

+ throw new Error("Test Error");

+}

+// Catch the error and record it to the span

+catch(error){

+ span.recordException(error);

+}

+The OpenTelemetry Python SDK is implemented in such a way that exceptions thrown are automatically captured and recorded. See the following code sample for an example of this behavior:

+* **Use the OpenTelemetry annotation**

+ The simplest way to add your own spans is by using OpenTelemetry's `@WithSpan` annotation.

+

+ Spans populate the `requests` and `dependencies` tables in Application Insights.

+

+ 1. Add `opentelemetry-instrumentation-annotations-1.32.0.jar` (or later) to your application:

+

+ ```xml

+ <dependency>

+ <groupId>io.opentelemetry.instrumentation</groupId>

+ <artifactId>opentelemetry-instrumentation-annotations</artifactId>

+ <version>1.32.0</version>

+ </dependency>

+ ```

+

+ 1. Use the `@WithSpan` annotation to emit a span each time your method is executed:

+

+ ```java

+ import io.opentelemetry.instrumentation.annotations.WithSpan;

+

+ @WithSpan(value = "your span name")

+ public void yourMethod() {

+ }

+ ```

+

+ By default, the span ends up in the `dependencies` table with dependency type `InProc`.

+

+ For methods representing a background job not captured by autoinstrumentation, we recommend applying the attribute `kind = SpanKind.SERVER` to the `@WithSpan` annotation to ensure they appear in the Application Insights `requests` table.

+* **Use the OpenTelemetry API**

+ If the preceding OpenTelemetry `@WithSpan` annotation doesn't meet your needs,

+ you can add your spans by using the OpenTelemetry API.

+

+ 1. Add `opentelemetry-api-1.0.0.jar` (or later) to your application:

+

+ ```xml

+ <dependency>

+ <groupId>io.opentelemetry</groupId>

+ <artifactId>opentelemetry-api</artifactId>

+ <version>1.0.0</version>

+ </dependency>

+ ```

+

+ 1. Use the `GlobalOpenTelemetry` class to create a `Tracer`:

+

+ ```java

+ import io.opentelemetry.api.GlobalOpenTelemetry;

+ import io.opentelemetry.api.trace.Tracer;

+

+ static final Tracer tracer = GlobalOpenTelemetry.getTracer("com.example");

+ ```

+

+ 1. Create a span, make it current, and then end it:

+

+ ```java

+ Span span = tracer.spanBuilder("my first span").startSpan();

+ try (Scope ignored = span.makeCurrent()) {

+ // do stuff within the context of this

+ } catch (Throwable t) {

+ span.recordException(t);

+ } finally {

+ span.end();

+ }

+ ```

+#### [Java native](#tab/java-native)

+1. Inject `OpenTelemetry`:

+ * **Spring**

+ ```java

+ import io.opentelemetry.api.OpenTelemetry;

+

+ @Autowired

+ OpenTelemetry openTelemetry;

+ ```

+

+ * **Quarkus**

+ ```java

+ import io.opentelemetry.api.OpenTelemetry;

+ @Inject

+ OpenTelemetry openTelemetry;

+ ```

+1. Create a `Tracer`:

+ ```java

+ import io.opentelemetry.api.trace.Tracer;

+ static final Tracer tracer = openTelemetry.getTracer("com.example");

+ ```

+1. Create a span, make it current, and then end it:

+ ```java

+ ```

+// Import the Azure Monitor OpenTelemetry plugin and OpenTelemetry API

+const { useAzureMonitor } = require("@azure/monitor-opentelemetry");

+const { trace } = require("@opentelemetry/api");

+// Enable Azure Monitor integration

+useAzureMonitor();

+// Get the tracer for the "testTracer" namespace

+const tracer = trace.getTracer("testTracer");

+// Start a span with the name "hello"

+let span = tracer.startSpan("hello");

+// End the span

+span.end();

+**Events**

+1. Create a `TelemetryClient` instance:

+ > [!NOTE]

+ > It's important to only create once instance of the TelemetryClient per application.

+

+ ```csharp

+ var telemetryConfiguration = new TelemetryConfiguration { ConnectionString = "" };

+ var telemetryClient = new TelemetryClient(telemetryConfiguration);

+ ```

+1. Use the client to send custom telemetry:

+ ```csharp

+ telemetryClient.TrackEvent("testEvent");

+ ```

+**Events**

+1. Create a `TelemetryClient` instance:

+ > [!NOTE]

+ > It's important to only create once instance of the TelemetryClient per application.

+

+ ```csharp

+ var telemetryConfiguration = new TelemetryConfiguration { ConnectionString = "" };

+ var telemetryClient = new TelemetryClient(telemetryConfiguration);

+ ```

+1. Use the client to send custom telemetry:

+ ```csharp

+ telemetryClient.TrackEvent("testEvent");

+ ```

+ **Events**

+ **Logs**

+ ```java

+ telemetryClient.trackTrace(message, SeverityLevel.Warning, properties);

+ ```

+ **Metrics**

+ **Dependencies**

+ **Exceptions**

+// Import the TelemetryClient class from the Application Insights SDK for JavaScript.

+const { TelemetryClient } = require("applicationinsights");

+// Create a new TelemetryClient instance.

+const telemetryClient = new TelemetryClient();

+**Events**

+// Create an event telemetry object.

+let eventTelemetry = {

+ name: "testEvent"

+};

+// Send the event telemetry object to Azure Monitor Application Insights.

+telemetryClient.trackEvent(eventTelemetry);

+**Logs**

+// Create a trace telemetry object.

+let traceTelemetry = {

+ message: "testMessage",

+ severity: "Information"

+};

+// Send the trace telemetry object to Azure Monitor Application Insights.

+telemetryClient.trackTrace(traceTelemetry);

+**Exceptions**

+// Try to execute a block of code.

+try {

+ ...

+}

+// If an error occurs, catch it and send it to Azure Monitor Application Insights as an exception telemetry item.

+catch (error) {

+ let exceptionTelemetry = {

+ exception: error,

+ severity: "Critical"

+ };

+ telemetryClient.trackException(exceptionTelemetry);

+Use the `track_event` API offered in the extension to send customEvents:

+Any [attributes](#add-span-attributes) you add to spans are exported as custom properties. They populate the *customDimensions* field in the requests, dependencies, traces, or exceptions table.

+ * [ASP.NET Core](https://github.com/open-telemetry/opentelemetry-dotnet/blob/1.0.0-rc9.14/src/OpenTelemetry.Instrumentation.AspNetCore/README.md#enrich)

+ * [HttpClient](https://github.com/open-telemetry/opentelemetry-dotnet/blob/1.0.0-rc9.14/src/OpenTelemetry.Instrumentation.Http/README.md#enrich)

+1. Use a custom processor:

+ > [!TIP]

+ > Add the processor shown here *before* adding Azure Monitor.

+

+ ```csharp

+ // Create an ASP.NET Core application builder.

+ var builder = WebApplication.CreateBuilder(args);

+

+ // Configure the OpenTelemetry tracer provider to add a new processor named ActivityEnrichingProcessor.

+ builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => builder.AddProcessor(new ActivityEnrichingProcessor()));

+

+ // Add the Azure Monitor telemetry service to the application. This service will collect and send telemetry data to Azure Monitor.

+ builder.Services.AddOpenTelemetry().UseAzureMonitor();

+

+ // Build the ASP.NET Core application.

+ var app = builder.Build();

+

+ // Start the ASP.NET Core application.

+ app.Run();

+ ```

+

+ Add `ActivityEnrichingProcessor.cs` to your project with the following code:

+

+ ```csharp

+ public class ActivityEnrichingProcessor : BaseProcessor<Activity>

+ public override void OnEnd(Activity activity)

+ {

+ // The updated activity will be available to all processors which are called after this processor.

+ activity.DisplayName = "Updated-" + activity.DisplayName;

+ activity.SetTag("CustomDimension1", "Value1");

+ activity.SetTag("CustomDimension2", "Value2");

+ }

+ ```

+##### [.NET](#tab/net)

+ * [ASP.NET](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/blob/Instrumentation.AspNet-1.0.0-rc9.8/src/OpenTelemetry.Instrumentation.AspNet/README.md#enrich)

+ * [ASP.NET Core](https://github.com/open-telemetry/opentelemetry-dotnet/blob/1.0.0-rc9.14/src/OpenTelemetry.Instrumentation.AspNetCore/README.md#enrich)

+ * [HttpClient](https://github.com/open-telemetry/opentelemetry-dotnet/blob/1.0.0-rc9.14/src/OpenTelemetry.Instrumentation.Http/README.md#enrich)

+1. Use a custom processor:

+ > [!TIP]

+ > Add the processor shown here *before* the Azure Monitor Exporter.

+

+ ```csharp

+ // Create an OpenTelemetry tracer provider builder.

+ // It is important to keep the TracerProvider instance active throughout the process lifetime.

+ using var tracerProvider = Sdk.CreateTracerProviderBuilder()

+ // Add a source named "OTel.AzureMonitor.Demo".

+ .AddSource("OTel.AzureMonitor.Demo") // Add a new processor named ActivityEnrichingProcessor.

+ .AddProcessor(new ActivityEnrichingProcessor()) // Add the Azure Monitor trace exporter.

+ .AddAzureMonitorTraceExporter() // Add the Azure Monitor trace exporter.

+ .Build();

+ ```

+

+ Add `ActivityEnrichingProcessor.cs` to your project with the following code:

+

+ ```csharp

+ public class ActivityEnrichingProcessor : BaseProcessor<Activity>

+ // The OnEnd method is called when an activity is finished. This is the ideal place to enrich the activity with additional data.

+ public override void OnEnd(Activity activity)

+ {

+ // Update the activity's display name.

+ // The updated activity will be available to all processors which are called after this processor.

+ activity.DisplayName = "Updated-" + activity.DisplayName;

+ // Set custom tags on the activity.

+ activity.SetTag("CustomDimension1", "Value1");

+ activity.SetTag("CustomDimension2", "Value2");

+ }

+ ```

+ ```xml

+ <dependency>

+ <groupId>io.opentelemetry</groupId>

+ <artifactId>opentelemetry-api</artifactId>

+ <version>1.0.0</version>

+ </dependency>

+ ```

+ ```java

+

+ ```

+```java

+import io.opentelemetry.api.trace.Span;

+import io.opentelemetry.api.common.AttributeKey;

+AttributeKey attributeKey = AttributeKey.stringKey("mycustomdimension");

+Span.current().setAttribute(attributeKey, "myvalue1");

+```

+##### [.NET](#tab/net)

+// Import the SemanticAttributes class from the @opentelemetry/semantic-conventions package.

+const { SemanticAttributes } = require("@opentelemetry/semantic-conventions");

+// Create a new SpanEnrichingProcessor class.

+class SpanEnrichingProcessor implements SpanProcessor {

+ onEnd(span) {

+ // Set the HTTP_CLIENT_IP attribute on the span to the IP address of the client.

+ span.attributes[SemanticAttributes.HTTP_CLIENT_IP] = "<IP Address>";

+}

+Use the add [custom property example](#add-a-custom-property-to-a-span):

+Use the add [custom property example](#add-a-custom-property-to-a-span):

+ ```xml

+ <dependency>

+ <groupId>io.opentelemetry</groupId>

+ <artifactId>opentelemetry-api</artifactId>

+ <version>1.0.0</version>

+ </dependency>

+ ```

+ ```java

+ import io.opentelemetry.api.trace.Span;

+

+ Span.current().setAttribute("enduser.id", "myuser");

+ ```

+```java

+import io.opentelemetry.api.trace.Span;

+Span.current().setAttribute("enduser.id", "myuser");

+```

+##### [Node.js](#tab/nodejs)

+// Import the SemanticAttributes class from the @opentelemetry/semantic-conventions package.

+import { SemanticAttributes } from "@opentelemetry/semantic-conventions";

+// Create a new SpanEnrichingProcessor class.

+class SpanEnrichingProcessor implements SpanProcessor {

+ onEnd(span: ReadableSpan) {

+ // Set the ENDUSER_ID attribute on the span to the ID of the user.

+ span.attributes[SemanticAttributes.ENDUSER_ID] = "<User ID>";

+}

+Logback, Log4j, and java.util.logging are [autoinstrumented](#send-custom-telemetry-using-the-application-insights-classic-api). Attaching custom dimensions to your logs can be accomplished in these ways:

+const { useAzureMonitor } = require("@azure/monitor-opentelemetry");

+const bunyan = require('bunyan');

+// Instrumentations configuration

+const options: AzureMonitorOpenTelemetryOptions = {

+ instrumentationOptions: {

+ // Instrumentations generating logs

+ bunyan: { enabled: true },

+ }

+};

+// Enable Azure Monitor integration

+useAzureMonitor(options);

+var log = bunyan.createLogger({ name: 'testApp' });

+log.info({

+ "testAttribute1": "testValue1",

+ "testAttribute2": "testValue2",

+ "testAttribute3": "testValue3"

+}, 'testEvent');

+The Python [logging](https://docs.python.org/3/howto/logging.html) library is [autoinstrumented](.\opentelemetry-add-modify.md?tabs=python#included-instrumentation-libraries). You can attach custom dimensions to your logs by passing a dictionary into the `extra` argument of your logs:

+ * [ASP.NET Core](https://github.com/open-telemetry/opentelemetry-dotnet/blob/1.0.0-rc9.14/src/OpenTelemetry.Instrumentation.AspNetCore/README.md#filter)

+ * [HttpClient](https://github.com/open-telemetry/opentelemetry-dotnet/blob/1.0.0-rc9.14/src/OpenTelemetry.Instrumentation.Http/README.md#filter)

+ * [ASP.NET](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/blob/Instrumentation.AspNet-1.0.0-rc9.8/src/OpenTelemetry.Instrumentation.AspNet/README.md#filter)

+ * [ASP.NET Core](https://github.com/open-telemetry/opentelemetry-dotnet/blob/1.0.0-rc9.14/src/OpenTelemetry.Instrumentation.AspNetCore/README.md#filter)

+ * [HttpClient](https://github.com/open-telemetry/opentelemetry-dotnet/blob/1.0.0-rc9.14/src/OpenTelemetry.Instrumentation.Http/README.md#filter)

+1. Use a custom processor. You can use a custom span processor to exclude certain spans from being exported. To mark spans to not be exported, set `TraceFlag` to `DEFAULT`.

+ Use the add [custom property example](#add-a-custom-property-to-a-span), but replace the following lines of code:

+1. Use a custom processor. You can use a custom span processor to exclude certain spans from being exported. To mark spans to not be exported, set `TraceFlag` to `DEFAULT`:

+ ```xml

+ <dependency>

+ <groupId>io.opentelemetry</groupId>

+ <artifactId>opentelemetry-api</artifactId>

+ <version>1.0.0</version>

+ </dependency>

+ ```

+ ```java

+ import io.opentelemetry.api.trace.Span;

+

+ Span span = Span.current();

+ String traceId = span.getSpanContext().getTraceId();

+ String spanId = span.getSpanContext().getSpanId();

+ ```

+```java

+import io.opentelemetry.api.trace.Span;

+Span span = Span.current();

+String traceId = span.getSpanContext().getTraceId();

+String spanId = span.getSpanContext().getSpanId();

+```

+```javascript

+// Import the trace module from the OpenTelemetry API.

+const { trace } = require("@opentelemetry/api");

+// Get the span ID and trace ID of the active span.

+let spanId = trace.getActiveSpan().spanContext().spanId;

+let traceId = trace.getActiveSpan().spanContext().traceId;

+```

+# Import the necessary libraries.

+* To further configure the OpenTelemetry distro, see [Azure Monitor OpenTelemetry configuration](opentelemetry-configuration.md).

+* To review the source code, see the [Azure Monitor AspNetCore GitHub repository](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/monitor/Azure.Monitor.OpenTelemetry.AspNetCore).

+* To install the NuGet package, check for updates, or view release notes, see the [Azure Monitor AspNetCore NuGet Package](https://www.nuget.org/packages/Azure.Monitor.OpenTelemetry.AspNetCore) page.

+* To become more familiar with Azure Monitor and OpenTelemetry, see the [Azure Monitor Example Application](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/monitor/Azure.Monitor.OpenTelemetry.AspNetCore/tests/Azure.Monitor.OpenTelemetry.AspNetCore.Demo).

+* To learn more about OpenTelemetry and its community, see the [OpenTelemetry .NET GitHub repository](https://github.com/open-telemetry/opentelemetry-dotnet).

+* To enable usage experiences, [enable web or browser user monitoring](javascript.md).

+* To further configure the OpenTelemetry distro, see [Azure Monitor OpenTelemetry configuration](opentelemetry-configuration.md)

+* To review the source code, see the [Azure Monitor Exporter GitHub repository](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/monitor/Azure.Monitor.OpenTelemetry.Exporter).

+* To install the NuGet package, check for updates, or view release notes, see the [Azure Monitor Exporter NuGet Package](https://www.nuget.org/packages/Azure.Monitor.OpenTelemetry.Exporter) page.

+* To become more familiar with Azure Monitor and OpenTelemetry, see the [Azure Monitor Example Application](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/monitor/Azure.Monitor.OpenTelemetry.Exporter/tests/Azure.Monitor.OpenTelemetry.Exporter.Demo).

+* To learn more about OpenTelemetry and its community, see the [OpenTelemetry .NET GitHub repository](https://github.com/open-telemetry/opentelemetry-dotnet).

+* To enable usage experiences, [enable web or browser user monitoring](javascript.md).

+* Review [Java autoinstrumentation configuration options](java-standalone-config.md).

+* To review the source code, see the [Azure Monitor Java autoinstrumentation GitHub repository](https://github.com/Microsoft/ApplicationInsights-Java).

+* To learn more about OpenTelemetry and its community, see the [OpenTelemetry Java GitHub repository](https://github.com/open-telemetry/opentelemetry-java-instrumentation).

+* To enable usage experiences, see [Enable web or browser user monitoring](javascript.md).

+* See the [release notes](https://github.com/microsoft/ApplicationInsights-Java/releases) on GitHub.

+* For details on adding and modifying Azure Monitor OpenTelemetry, see [Add and modify Azure Monitor OpenTelemetry](opentelemetry-add-modify.md).

+* To review the source code, see [Azure Monitor OpenTelemetry Distro in Spring Boot native image Java application](https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/spring/spring-cloud-azure-starter-monitor) and [Quarkus OpenTelemetry Exporter for Azure](https://github.com/quarkiverse/quarkus-opentelemetry-exporter/tree/main/quarkus-opentelemetry-exporter-azure).

+* To learn more about OpenTelemetry and its community, see the [OpenTelemetry Java GitHub repository](https://github.com/open-telemetry/opentelemetry-java-instrumentation).

+* See the [release notes](https://github.com/Azure/azure-sdk-for-jav) on GitHub.

+* To review the source code, see the [Azure Monitor OpenTelemetry GitHub repository](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/monitor/monitor-opentelemetry).

+* To install the npm package and check for updates, see the [`@azure/monitor-opentelemetry` npm Package](https://www.npmjs.com/package/@azure/monitor-opentelemetry) page.

+* To become more familiar with Azure Monitor Application Insights and OpenTelemetry, see the [Azure Monitor Example Application](https://github.com/Azure-Samples/azure-monitor-opentelemetry-node.js).

+* To learn more about OpenTelemetry and its community, see the [OpenTelemetry JavaScript GitHub repository](https://github.com/open-telemetry/opentelemetry-js).

+* To enable usage experiences, [enable web or browser user monitoring](javascript.md).

+* To review the source code and extra documentation, see the [Azure Monitor Distro GitHub repository](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/monitor/azure-monitor-opentelemetry/README.md).

+* To see extra samples and use cases, see [Azure Monitor Distro samples](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/monitor/azure-monitor-opentelemetry/samples).

+* See the [release notes](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/monitor/azure-monitor-opentelemetry/CHANGELOG.md) on GitHub.

+* To install the PyPI package, check for updates, or view release notes, see the [Azure Monitor Distro PyPI Package](https://pypi.org/project/azure-monitor-opentelemetry/) page.

+* To become more familiar with Azure Monitor Application Insights and OpenTelemetry, see the [Azure Monitor Example Application](https://github.com/Azure-Samples/azure-monitor-opentelemetry-python).

+* To learn more about OpenTelemetry and its community, see the [OpenTelemetry Python GitHub repository](https://github.com/open-telemetry/opentelemetry-python).

+* To see available OpenTelemetry instrumentations and components, see the [OpenTelemetry Contributor Python GitHub repository](https://github.com/open-telemetry/opentelemetry-python-contrib).

+* To enable usage experiences, [enable web or browser user monitoring](javascript.md).

+> When using fixed-rate/percentage sampling and you aren't sure what to set the sampling rate as, start at 5% (i.e., 0.05 sampling ratio) and adjust the rate based on the accuracy of the operations shown in the failures and performance panes. A higher rate generally results in higher accuracy. However, ANY sampling will affect accuracy so we recommend alerting on [OpenTelemetry metrics](opentelemetry-add-modify.md#add-custom-metrics), which are unaffected by sampling.

+ Title: Migrate from Application Insights .NET SDKs to Azure Monitor OpenTelemetry

+description: This article provides guidance on how to migrate .NET applications from the Application Insights Classic API SDKs to Azure Monitor OpenTelemetry.

+ms.devlang: csharp

+# Migrate from .NET Application Insights SDKs to Azure Monitor OpenTelemetry

+This guide provides step-by-step instructions to migrate various .NET applications from using Application Insights software development kits (SDKs) to Azure Monitor OpenTelemetry.

+Expect a similar experience with Azure Monitor OpenTelemetry instrumentation as with the Application Insights SDKs. For more information and a feature-by-feature comparison, see [release state of features](opentelemetry-enable.md#whats-the-current-release-state-of-features-within-the-azure-monitor-opentelemetry-distro).

+> [!div class="checklist"]

+> - ASP.NET Core migration to the [Azure Monitor OpenTelemetry Distro](https://www.nuget.org/packages/Azure.Monitor.OpenTelemetry.AspNetCore). (`Azure.Monitor.OpenTelemetry.AspNetCore` NuGet package)

+> - ASP.NET, console, and WorkerService migration to the [Azure Monitor OpenTelemetry Exporter](https://www.nuget.org/packages/Azure.Monitor.OpenTelemetry.Exporter). (`Azure.Monitor.OpenTelemetry.Exporter` NuGet package)

+If you're getting started with Application Insights and don't need to migrate from the Classic API, see [Enable Azure Monitor OpenTelemetry](opentelemetry-enable.md).

+## Prerequisites

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

+* An ASP.NET Core web application already instrumented with Application Insights without any customizations

+* An actively supported version of [.NET](https://dotnet.microsoft.com/platform/support/policy/dotnet-core)

+### [ASP.NET](#tab/net)

+* An ASP.NET web application already instrumented with Application Insights

+* An actively supported version of [.NET Framework](/lifecycle/products/microsoft-net-framework)

+### [Console](#tab/console)

+* A Console application already instrumented with Application Insights

+* An actively supported version of [.NET Framework](/lifecycle/products/microsoft-net-framework) or [.NET](https://dotnet.microsoft.com/platform/support/policy/dotnet-core)

+### [WorkerService](#tab/workerservice)

+* A WorkerService application already instrumented with Application Insights without any customizations

+* An actively supported version of [.NET](https://dotnet.microsoft.com/platform/support/policy/dotnet-core)

+> [!Tip]

+> Our product group is actively seeking feedback on this documentation. Provide feedback to otel@microsoft.com or see the [Support](#support) section.

+## Remove the Application Insights SDK

+> [!Note]

+> Before continuing with these steps, you should confirm that you have a current backup of your application.

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

+1. Remove NuGet packages

+ Remove the `Microsoft.ApplicationInsights.AspNetCore` package from your `csproj`.

+ ```terminal

+ dotnet remove package Microsoft.ApplicationInsights.AspNetCore

+ ```

+2. Remove Initialization Code and customizations

+ Remove any references to Application Insights types in your codebase.

+ > [!Tip]

+ > After removing the Application Insights package, you can re-build your application to get a list of references that need to be removed.

+ - Remove Application Insights from your `ServiceCollection` by deleting the following line:

+ ```csharp

+ builder.Services.AddApplicationInsightsTelemetry();

+ ```

+ - Remove the `ApplicationInsights` section from your `appsettings.json`.

+ ```json

+ {

+ "ApplicationInsights": {

+ "ConnectionString": "<Your Connection String>"

+ }

+ }

+ ```

+3. Clean and Build

+ Inspect your bin directory to validate that all references to `Microsoft.ApplicationInsights.*` were removed.

+4. Test your application

+ Verify that your application has no unexpected consequences.

+### [ASP.NET](#tab/net)

+1. Remove NuGet packages

+ Remove the `Microsoft.AspNet.TelemetryCorrelation` package and any `Microsoft.ApplicationInsights.*` packages from your `csproj` and `packages.config`.

+2. Delete the `ApplicationInsights.config` file

+3. Delete section from your application's `Web.config` file

+ - Two [HttpModules](/troubleshoot/developer/webapps/aspnet/development/http-modules-handlers) were automatically added to your web.config when you first added ApplicationInsights to your project.

+ Any references to the `TelemetryCorrelationHttpModule` and the `ApplicationInsightsWebTracking` should be removed.

+ If you added Application Insights to your [Internet Information Server (IIS) Modules](/iis/get-started/introduction-to-iis/iis-modules-overview), it should also be removed.

+ ```xml

+ <configuration>

+ <system.web>

+ <httpModules>

+ <add name="TelemetryCorrelationHttpModule" type="Microsoft.AspNet.TelemetryCorrelation.TelemetryCorrelationHttpModule, Microsoft.AspNet.TelemetryCorrelation" />

+ <add name="ApplicationInsightsWebTracking" type="Microsoft.ApplicationInsights.Web.ApplicationInsightsHttpModule, Microsoft.AI.Web" />

+ </httpModules>

+ </system.web>

+ <system.webServer>

+ <modules>

+ <remove name="TelemetryCorrelationHttpModule" />

+ <add name="TelemetryCorrelationHttpModule" type="Microsoft.AspNet.TelemetryCorrelation.TelemetryCorrelationHttpModule, Microsoft.AspNet.TelemetryCorrelation" preCondition="managedHandler" />

+ <remove name="ApplicationInsightsWebTracking" />

+ <add name="ApplicationInsightsWebTracking" type="Microsoft.ApplicationInsights.Web.ApplicationInsightsHttpModule, Microsoft.AI.Web" preCondition="managedHandler" />

+ </modules>

+ </system.webServer>

+ </configuration>

+ ```

+ - Also review any [assembly version redirections](/dotnet/framework/configure-apps/redirect-assembly-versions) added to your web.config.

+4. Remove Initialization Code and customizations

+ Remove any references to Application Insights types in your codebase.

+ > [!Tip]

+ > After removing the Application Insights package, you can re-build your application to get a list of references that need to be removed.

+ - Remove references to `TelemetryConfiguration` or `TelemetryClient`. It's a part of your application startup to initialize the Application Insights SDK.

+ The following scenarios are optional and apply to advanced users.

+ - If you have any more references to the `TelemetryClient`, which are used to [manually record telemetry](./api-custom-events-metrics.md), they should be removed.

+ - If you added any [custom filtering or enrichment](./api-filtering-sampling.md) in the form of a custom `TelemetryProcessor` or `TelemetryInitializer`, they should be removed. You can find them referenced in your configuration.

+ - If your project has a `FilterConfig.cs` in the `App_Start` directory, check for any custom exception handlers that reference Application Insights and remove.

+5. Remove JavaScript Snippet

+ If you added the JavaScript SDK to collect client-side telemetry, it can also be removed although it continues to work without the .NET SDK.

+ For full code samples of what to remove, review the [onboarding guide for the JavaScript SDK](./javascript-sdk.md).

+6. Remove any Visual Studio Artifacts

+ If you used Visual Studio to onboard to Application Insights, you could have more files left over in your project.

+ - `ConnectedService.json` might have a reference to your Application Insights resource.

+ - `[Your project's name].csproj` might have a reference to your Application Insights resource:

+ ```xml

+ <ApplicationInsightsResourceId>/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/Default-ApplicationInsights-EastUS/providers/microsoft.insights/components/WebApplication4</ApplicationInsightsResourceId>

+ ```

+7. Clean and Build

+ Inspect your bin directory to validate that all references to `Microsoft.ApplicationInsights.` were removed.

+8. Test your application

+ Verify that your application has no unexpected consequences.

+### [Console](#tab/console)

+1. Remove NuGet packages

+ Remove any `Microsoft.ApplicationInsights.*` packages from your `csproj` and `packages.config`.

+ ```terminal

+ dotnet remove package Microsoft.ApplicationInsights

+ ```

+ > [!Tip]

+ > If you've used [Microsoft.ApplicationInsights.WorkerService](https://www.nuget.org/packages/Microsoft.ApplicationInsights.WorkerService), refer to the WorkerService tabs.

+2. Remove Initialization Code and customizations

+ Remove any references to Application Insights types in your codebase.

+ > [!Tip]

+ > After removing the Application Insights package, you can re-build your application to get a list of references that need to be removed.

+ - Remove references to `TelemetryConfiguration` or `TelemetryClient`. It should be part of your application startup to initialize the Application Insights SDK.

+ ```csharp

+ var config = TelemetryConfiguration.CreateDefault();

+ var client = new TelemetryClient(config);

+ ```

+ > [!Tip]

+ > If you've used `AddApplicationInsightsTelemetryWorkerService()` to add Application Insights to your `ServiceCollection`, refer to the WorkerService tabs.

+3. Clean and Build

+ Inspect your bin directory to validate that all references to `Microsoft.ApplicationInsights.` were removed.

+4. Test your application

+ Verify that your application has no unexpected consequences.

+### [WorkerService](#tab/workerservice)

+1. Remove NuGet packages

+ Remove the `Microsoft.ApplicationInsights.WorkerService` package from your `csproj`.

+ ```terminal

+ dotnet remove package Microsoft.ApplicationInsights.AspNetCore

+ ```

+2. Remove Initialization Code and customizations

+ Remove any references to Application Insights types in your codebase.

+ > [!Tip]

+ > After removing the Application Insights package, you can re-build your application to get a list of references that need to be removed.

+ - Remove Application Insights from your `ServiceCollection` by deleting the following line:

+ ```csharp

+ builder.Services.AddApplicationInsightsTelemetryWorkerService();

+ ```

+ - Remove the `ApplicationInsights` section from your `appsettings.json`.

+ ```json

+ {

+ "ApplicationInsights": {

+ "ConnectionString": "<Your Connection String>"

+ }

+ }

+ ```

+3. Clean and Build

+ Inspect your bin directory to validate that all references to `Microsoft.ApplicationInsights.*` were removed.

+4. Test your application

+ Verify that your application has no unexpected consequences.

+> [!Tip]

+> Our product group is actively seeking feedback on this documentation. Provide feedback to otel@microsoft.com or see the [Support](#support) section.

+## Enable OpenTelemetry

+We recommended creating a development [resource](./create-workspace-resource.md) and using its [connection string](./sdk-connection-string.md) when following these instructions.

+Plan to update the connection string to send telemetry to the original resource after confirming migration is successful.

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

+1. Install the Azure Monitor Distro

+ Our Azure Monitor Distro enables automatic telemetry by including OpenTelemetry instrumentation libraries for collecting traces, metrics, logs, and exceptions, and allows collecting custom telemetry.

+ Installing the Azure Monitor Distro brings the [OpenTelemetry SDK](https://www.nuget.org/packages/OpenTelemetry) as a dependency.

+ ```terminal

+ dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore

+ ```

+2. Add and configure both OpenTelemetry and Azure Monitor

+ The OpenTelemery SDK must be configured at application startup as part of your `ServiceCollection`, typically in the `Program.cs`.

+ OpenTelemetry has a concept of three signals; Traces, Metrics, and Logs.

+ The Azure Monitor Distro configures each of these signals.

+##### Program.cs

+The following code sample demonstrates the basics.

+```csharp

+using Azure.Monitor.OpenTelemetry.AspNetCore;

+using Microsoft.AspNetCore.Builder;

+using Microsoft.Extensions.DependencyInjection;

+public class Program

+{

+ public static void Main(string[] args)

+ {

+ var builder = WebApplication.CreateBuilder(args);

+ // Call AddOpenTelemetry() to add OpenTelemetry to your ServiceCollection.

+ // Call UseAzureMonitor() to fully configure OpenTelemetry.

+ builder.Services.AddOpenTelemetry().UseAzureMonitor();

+ var app = builder.Build();

+ app.MapGet("/", () => "Hello World!");

+ app.Run();

+ }

+}

+```

+We recommend setting your Connection String in an environment variable:

+`APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>`

+More options to configure the Connection String are detailed here: [Configure the Application Insights Connection String](./opentelemetry-configuration.md?tabs=aspnetcore#connection-string).

+### [ASP.NET](#tab/net)

+1. Install the OpenTelemetry SDK via Azure Monitor

+ Installing the Azure Monitor Exporter brings the [OpenTelemetry SDK](https://www.nuget.org/packages/OpenTelemetry) as a dependency.

+ ```terminal

+ dotnet add package Azure.Monitor.OpenTelemetry.Exporter

+ ```

+2. Configure OpenTelemetry as part of your application startup

+ The OpenTelemery SDK must be configured at application startup, typically in the `Global.asax.cs`.

+ OpenTelemetry has a concept of three signals; Traces, Metrics, and Logs.

+ Each of these signals needs to be configured as part of your application startup.

+ `TracerProvider`, `MeterProvider`, and `ILoggerFactory` should be created once for your application and disposed when your application shuts down.

+##### Global.asax.cs

+The following code sample shows a simple example meant only to show the basics.

+No telemetry is collected at this point.

+```csharp

+using Microsoft.Extensions.Logging;

+using OpenTelemetry;

+using OpenTelemetry.Metrics;

+using OpenTelemetry.Trace;

+public class Global : System.Web.HttpApplication

+{

+ private TracerProvider? tracerProvider;

+ private MeterProvider? meterProvider;

+ // The LoggerFactory needs to be accessible from the rest of your application.

+ internal static ILoggerFactory loggerFactory;

+ protected void Application_Start()

+ {

+ this.tracerProvider = Sdk.CreateTracerProviderBuilder()

+ .Build();

+ this.meterProvider = Sdk.CreateMeterProviderBuilder()

+ .Build();

+ loggerFactory = LoggerFactory.Create(builder =>

+ {

+ builder.AddOpenTelemetry();

+ });

+ }

+ protected void Application_End()

+ {

+ this.tracerProvider?.Dispose();

+ this.meterProvider?.Dispose();

+ loggerFactory?.Dispose();

+ }

+}

+```

+### [Console](#tab/console)

+1. Install the OpenTelemetry SDK via Azure Monitor

+ Installing the [Azure Monitor Exporter](https://www.nuget.org/packages/Azure.Monitor.OpenTelemetry.Exporter) brings the [OpenTelemetry SDK](https://www.nuget.org/packages/OpenTelemetry) as a dependency.

+ ```terminal

+ dotnet add package Azure.Monitor.OpenTelemetry.Exporter

+ ```

+2. Configure OpenTelemetry as part of your application startup

+ The OpenTelemery SDK must be configured at application startup, typically in the `Program.cs`.

+ OpenTelemetry has a concept of three signals; Traces, Metrics, and Logs.

+ Each of these signals needs to be configured as part of your application startup.

+ `TracerProvider`, `MeterProvider`, and `ILoggerFactory` should be created once for your application and disposed when your application shuts down.

+The following code sample shows a simple example meant only to show the basics.

+No telemetry is collected at this point.

+##### Program.cs

+```csharp

+using Microsoft.Extensions.Logging;

+using OpenTelemetry;

+using OpenTelemetry.Metrics;

+using OpenTelemetry.Trace;

+internal class Program

+{

+ static void Main(string[] args)

+ {

+ TracerProvider tracerProvider = Sdk.CreateTracerProviderBuilder()

+ .Build();

+ MeterProvider meterProvider = Sdk.CreateMeterProviderBuilder()

+ .Build();

+ ILoggerFactory loggerFactory = LoggerFactory.Create(builder =>

+ {

+ builder.AddOpenTelemetry();

+ });

+ Console.WriteLine("Hello, World!");

+ // Dispose tracer provider before the application ends.

+ // It will flush the remaining spans and shutdown the tracing pipeline.

+ tracerProvider.Dispose();

+ // Dispose meter provider before the application ends.

+ // It will flush the remaining metrics and shutdown the metrics pipeline.

+ meterProvider.Dispose();

+ // Dispose logger factory before the application ends.

+ // It will flush the remaining logs and shutdown the logging pipeline.

+ loggerFactory.Dispose();

+ }

+}

+```

+### [WorkerService](#tab/workerservice)

+1. Install the OpenTelemetry SDK via Azure Monitor

+ Installing the [Azure Monitor Exporter](https://www.nuget.org/packages/Azure.Monitor.OpenTelemetry.Exporter) brings the [OpenTelemetry SDK](https://www.nuget.org/packages/OpenTelemetry) as a dependency.

+ ```terminal

+ dotnet add package Azure.Monitor.OpenTelemetry.Exporter

+ ```

+ You must also install the [OpenTelemetry Extensions Hosting](https://www.nuget.org/packages/OpenTelemetry.Extensions.Hosting) package.

+ ```terminal

+ dotnet add package OpenTelemetry.Extensions.Hosting

+ ```

+2. Configure OpenTelemetry as part of your application startup

+ The OpenTelemery SDK must be configured at application startup, typically in the `Program.cs`.

+ OpenTelemetry has a concept of three signals; Traces, Metrics, and Logs.

+ Each of these signals needs to be configured as part of your application startup.

+ `TracerProvider`, `MeterProvider`, and `ILoggerFactory` should be created once for your application and disposed when your application shuts down.

+The following code sample shows a simple example meant only to show the basics.

+No telemetry is collected at this point.

+##### Program.cs

+```csharp

+using Microsoft.Extensions.DependencyInjection;

+using Microsoft.Extensions.Hosting;

+using Microsoft.Extensions.Logging;

+public class Program

+{

+ public static void Main(string[] args)

+ {

+ var builder = Host.CreateApplicationBuilder(args);

+ builder.Services.AddHostedService<Worker>();

+ builder.Services.AddOpenTelemetry()

+ .WithTracing()

+ .WithMetrics();

+ builder.Logging.AddOpenTelemetry();

+ var host = builder.Build();

+ host.Run();

+ }

+}

+```

+> [!Tip]

+> Our product group is actively seeking feedback on this documentation. Provide feedback to otel@microsoft.com or see the [Support](#support) section.

+## Install and configure instrumentation libraries

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

+[Instrumentation libraries](https://opentelemetry.io/docs/specs/otel/overview/#instrumentation-libraries) can be added to your project to auto collect telemetry about specific components or dependencies.

+The following libraries are included in the Distro.

+- [HTTP](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.Http)

+- [ASP.NET Core](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.AspNetCore)

+- [SQL](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.sqlclient)

+#### Customizing instrumentation libraries

+The Azure Monitor Distro includes .NET OpenTelemetry instrumentation for [ASP.NET Core](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.AspNetCore/), [HttpClient](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.Http/), and [SQLClient](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.SqlClient).

+You can customize these included instrumentations or manually add extra instrumentation on your own using the OpenTelemetry API.

+Here are some examples of how to customize the instrumentation:

+##### Customizing AspNetCoreTraceInstrumentationOptions

+```C#

+builder.Services.AddOpenTelemetry().UseAzureMonitor();

+builder.Services.Configure<AspNetCoreTraceInstrumentationOptions>(options =>

+{

+ options.RecordException = true;

+ options.Filter = (httpContext) =>

+ {

+ // only collect telemetry about HTTP GET requests

+ return HttpMethods.IsGet(httpContext.Request.Method);

+ };

+});

+```

+##### Customizing HttpClientTraceInstrumentationOptions

+```C#

+builder.Services.AddOpenTelemetry().UseAzureMonitor();

+builder.Services.Configure<HttpClientTraceInstrumentationOptions>(options =>

+{

+ options.RecordException = true;

+ options.FilterHttpRequestMessage = (httpRequestMessage) =>

+ {

+ // only collect telemetry about HTTP GET requests

+ return HttpMethods.IsGet(httpRequestMessage.Method.Method);

+ };

+});

+```

+##### Customizing SqlClientInstrumentationOptions

+We vendor the [SQLClient](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.SqlClient) instrumentation within our package while it's still in beta. When it reaches a stable release, we include it as a standard package reference. Until then, to customize the SQLClient instrumentation, add the `OpenTelemetry.Instrumentation.SqlClient` package reference to your project and use its public API.

+```

+dotnet add package --prerelease OpenTelemetry.Instrumentation.SqlClient

+```

+```C#

+builder.Services.AddOpenTelemetry().UseAzureMonitor().WithTracing(builder =>

+{

+ builder.AddSqlClientInstrumentation(options =>

+ {

+ options.SetDbStatementForStoredProcedure = false;

+ });

+});

+```

+### [ASP.NET](#tab/net)

+[Instrumentation libraries](https://opentelemetry.io/docs/specs/otel/overview/#instrumentation-libraries) can be added to your project to auto collect telemetry about specific components or dependencies. We recommend the following libraries:

+1. [OpenTelemetry.Instrumentation.AspNet](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.AspNet) can be used to collect telemetry for incoming requests. Azure Monitor maps it to [Request Telemetry](./data-model-complete.md#request).

+ ```terminal

+ dotnet add package OpenTelemetry.Instrumentation.AspNet

+ ```

+ It requires adding an extra HttpModule to your `Web.config`:

+ ```xml

+ <system.webServer>

+ <modules>

+ <add

+ name="TelemetryHttpModule"

+ type="OpenTelemetry.Instrumentation.AspNet.TelemetryHttpModule,

+ OpenTelemetry.Instrumentation.AspNet.TelemetryHttpModule"

+ preCondition="integratedMode,managedHandler" />

+ </modules>

+ </system.webServer>

+ ```

+ A complete getting started guide is available here: [OpenTelemetry.Instrumentation.AspNet Readme](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.AspNet)

+2. [OpenTelemetry.Instrumentation.Http](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.Http) can be used to collect telemetry for outbound http dependencies. Azure Monitor maps it to [Dependency Telemetry](./data-model-complete.md#dependency).

+ ```terminal

+ dotnet add package OpenTelemetry.Instrumentation.Http

+ ```

+ A complete getting started guide is available here: [OpenTelemetry.Instrumentation.Http Readme](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.Http)

+3. [OpenTelemetry.Instrumentation.SqlClient](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.SqlClient) can be used to collect telemetry for MS SQL dependencies. Azure Monitor maps it to [Dependency Telemetry](./data-model-complete.md#dependency).

+ ```terminal

+ dotnet add package --prerelease OpenTelemetry.Instrumentation.SqlClient

+ ```

+ A complete getting started guide is available here: [OpenTelemetry.Instrumentation.SqlClient Readme](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.SqlClient)

+##### Global.asax.cs

+The following code sample expands on the previous example.

+It now collects telemetry, but doesn't yet send to Application Insights.

+```csharp

+using Microsoft.Extensions.Logging;

+using OpenTelemetry;

+using OpenTelemetry.Metrics;

+using OpenTelemetry.Trace;

+public class Global : System.Web.HttpApplication

+{

+ private TracerProvider? tracerProvider;

+ private MeterProvider? meterProvider;

+ internal static ILoggerFactory loggerFactory;

+ protected void Application_Start()

+ {

+ this.tracerProvider = Sdk.CreateTracerProviderBuilder()

+ .AddAspNetInstrumentation()

+ .AddHttpClientInstrumentation()

+ .AddSqlClientInstrumentation()

+ .Build();

+ this.meterProvider = Sdk.CreateMeterProviderBuilder()

+ .AddAspNetInstrumentation()

+ .AddHttpClientInstrumentation()

+ .Build();

+ loggerFactory = LoggerFactory.Create(builder =>

+ {

+ builder.AddOpenTelemetry();

+ });

+ }

+ protected void Application_End()

+ {

+ this.tracerProvider?.Dispose();

+ this.meterProvider?.Dispose();

+ loggerFactory?.Dispose();

+ }

+}

+```

+### [Console](#tab/console)

+[Instrumentation libraries](https://opentelemetry.io/docs/specs/otel/overview/#instrumentation-libraries) can be added to your project to auto collect telemetry about specific components or dependencies. We recommend the following libraries:

+1. [OpenTelemetry.Instrumentation.Http](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.Http) can be used to collect telemetry for outbound http dependencies. Azure Monitor maps it to [Dependency Telemetry](./data-model-complete.md#dependency).

+ ```terminal

+ dotnet add package OpenTelemetry.Instrumentation.Http

+ ```

+ A complete getting started guide is available here: [OpenTelemetry.Instrumentation.Http Readme](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.Http)

+2. [OpenTelemetry.Instrumentation.SqlClient](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.SqlClient) can be used to collect telemetry for MS SQL dependencies. Azure Monitor maps it to [Dependency Telemetry](./data-model-complete.md#dependency).

+ ```terminal

+ dotnet add package --prerelease OpenTelemetry.Instrumentation.SqlClient

+ ```

+ A complete getting started guide is available here: [OpenTelemetry.Instrumentation.SqlClient Readme](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.SqlClient)

+The following code sample expands on the previous example.

+It now collects telemetry, but doesn't yet send to Application Insights.

+##### Program.cs

+```csharp

+using Microsoft.Extensions.Logging;

+using OpenTelemetry;

+using OpenTelemetry.Metrics;

+using OpenTelemetry.Trace;

+internal class Program

+{

+ static void Main(string[] args)

+ {

+ TracerProvider tracerProvider = Sdk.CreateTracerProviderBuilder()

+ .AddHttpClientInstrumentation()

+ .AddSqlClientInstrumentation()

+ .Build();

+ MeterProvider meterProvider = Sdk.CreateMeterProviderBuilder()

+ .AddHttpClientInstrumentation()

+ .Build();

+ ILoggerFactory loggerFactory = LoggerFactory.Create(builder =>

+ {

+ builder.AddOpenTelemetry();

+ });

+ Console.WriteLine("Hello, World!");

+ tracerProvider.Dispose();

+ meterProvider.Dispose();

+ loggerFactory.Dispose();

+ }

+}

+```

+### [WorkerService](#tab/workerservice)

+[Instrumentation libraries](https://opentelemetry.io/docs/specs/otel/overview/#instrumentation-libraries) can be added to your project to auto collect telemetry about specific components or dependencies. We recommend the following libraries:

+1. [OpenTelemetry.Instrumentation.Http](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.Http) can be used to collect telemetry for outbound http dependencies. Azure Monitor maps it to [Dependency Telemetry](./data-model-complete.md#dependency).

+ ```terminal

+ dotnet add package OpenTelemetry.Instrumentation.Http

+ ```

+ A complete getting started guide is available here: [OpenTelemetry.Instrumentation.Http Readme](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.Http)

+2. [OpenTelemetry.Instrumentation.SqlClient](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.SqlClient) can be used to collect telemetry for MS SQL dependencies. Azure Monitor maps it to [Dependency Telemetry](./data-model-complete.md#dependency).

+ ```terminal

+ dotnet add package --prerelease OpenTelemetry.Instrumentation.SqlClient

+ ```

+ A complete getting started guide is available here: [OpenTelemetry.Instrumentation.SqlClient Readme](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.SqlClient)

+The following code sample expands on the previous example.

+It now collects telemetry, but doesn't yet send to Application Insights.

+##### Program.cs

+```csharp

+using Microsoft.Extensions.DependencyInjection;

+using Microsoft.Extensions.Hosting;

+using Microsoft.Extensions.Logging;

+public class Program

+{

+ public static void Main(string[] args)

+ {

+ var builder = Host.CreateApplicationBuilder(args);

+ builder.Services.AddHostedService<Worker>();

+ builder.Services.AddOpenTelemetry()

+ .WithTracing(builder =>

+ {

+ builder.AddHttpClientInstrumentation();

+ builder.AddSqlClientInstrumentation();

+ })

+ .WithMetrics(builder =>

+ {

+ builder.AddHttpClientInstrumentation();

+ });

+ builder.Logging.AddOpenTelemetry();

+ var host = builder.Build();

+ host.Run();

+ }

+}

+```

+## Configure Azure Monitor

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

+Application Insights offered many more configuration options via `ApplicationInsightsServiceOptions`.

+| Application Insights Setting | OpenTelemetry Alternative |

+|--|-|

+| AddAutoCollectedMetricExtractor | N/A |

+| ApplicationVersion | Set "service.version" on Resource |

+| ConnectionString | See [instructions](./opentelemetry-configuration.md?tabs=aspnetcore#connection-string) on configuring the Connection String. |

+| DependencyCollectionOptions | N/A. To customize dependencies, review the available configuration options for applicable Instrumentation libraries. |

+| DeveloperMode | N/A |

+| EnableActiveTelemetryConfigurationSetup | N/A |

+| EnableAdaptiveSampling | N/A. Only fixed-rate sampling is supported. |

+| EnableAppServicesHeartbeatTelemetryModule | N/A |

+| EnableAuthenticationTrackingJavaScript | N/A |

+| EnableAzureInstanceMetadataTelemetryModule | N/A |

+| EnableDependencyTrackingTelemetryModule | See instructions on filtering Traces. |

+| EnableDiagnosticsTelemetryModule | N/A |

+| EnableEventCounterCollectionModule | N/A |

+| EnableHeartbeat | N/A |

+| EnablePerformanceCounterCollectionModule | N/A |

+| EnableQuickPulseMetricStream | AzureMonitorOptions.EnableLiveMetrics |

+| EnableRequestTrackingTelemetryModule | See instructions on filtering Traces. |

+| EndpointAddress | Use ConnectionString. |

+| InstrumentationKey | Use ConnectionString. |

+| RequestCollectionOptions | N/A. See OpenTelemetry.Instrumentation.AspNetCore options. |

+### Remove custom configurations

+The following scenarios are optional and only apply to advanced users.

+* If you have any more references to the `TelemetryClient`, which could be used to [manually record telemetry](./api-custom-events-metrics.md), they should be removed.

+* If you added any [custom filtering or enrichment](./api-filtering-sampling.md) in the form of a custom `TelemetryProcessor` or `TelemetryInitializer`, they should be removed. They can be found in your `ServiceCollection`.

+ ```csharp

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

+ ```

+ ```csharp

+ builder.Services.AddApplicationInsightsTelemetryProcessor<MyCustomTelemetryProcessor>();

+ ```

+* Remove JavaScript Snippet

+ If you used the Snippet provided by the Application Insights .NET SDK, it must also be removed.

+ For full code samples of what to remove, review the guide [enable client-side telemetry for web applications](./asp-net-core.md?tabs=netcorenew#enable-client-side-telemetry-for-web-applications).

+ If you added the JavaScript SDK to collect client-side telemetry, it can also be removed although it continues to work without the .NET SDK.

+ For full code samples of what to remove, review the [onboarding guide for the JavaScript SDK](./javascript-sdk.md).

+* Remove any Visual Studio Artifacts

+ If you used Visual Studio to onboard to Application Insights, you could have more files left over in your project.

+ - `Properties/ServiceDependencies` directory might have a reference to your Application Insights resource.

+### [ASP.NET](#tab/net)

+To send your telemetry to Application Insights, the Azure Monitor Exporter must be added to the configuration of all three signals.

+##### Global.asax.cs

+The following code sample expands on the previous example.

+It now collects telemetry and sends to Application Insights.

+```csharp

+public class Global : System.Web.HttpApplication

+{

+ private TracerProvider? tracerProvider;

+ private MeterProvider? meterProvider;

+ internal static ILoggerFactory loggerFactory;

+ protected void Application_Start()

+ {

+ this.tracerProvider = Sdk.CreateTracerProviderBuilder()

+ .AddAspNetInstrumentation()

+ .AddHttpClientInstrumentation()

+ .AddSqlClientInstrumentation()

+ .AddAzureMonitorTraceExporter()

+ .Build();

+ this.meterProvider = Sdk.CreateMeterProviderBuilder()

+ .AddAspNetInstrumentation()

+ .AddHttpClientInstrumentation()

+ .AddAzureMonitorMetricExporter()

+ .Build();

+ loggerFactory = LoggerFactory.Create(builder =>

+ {

+ builder.AddOpenTelemetry(o => o.AddAzureMonitorLogExporter());

+ });

+ }

+ protected void Application_End()

+ {

+ this.tracerProvider?.Dispose();

+ this.meterProvider?.Dispose();

+ loggerFactory?.Dispose();

+ }

+}

+```

+We recommend setting your Connection String in an environment variable:

+`APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>`

+More options to configure the Connection String are detailed here: [Configure the Application Insights Connection String](./opentelemetry-configuration.md?tabs=net#connection-string).

+### [Console](#tab/console)

+To send your telemetry to Application Insights, the Azure Monitor Exporter must be added to the configuration of all three signals.

+##### Program.cs

+The following code sample expands on the previous example.

+It now collects telemetry and sends to Application Insights.

+```csharp

+using Microsoft.Extensions.Logging;

+using OpenTelemetry;

+using OpenTelemetry.Metrics;

+using OpenTelemetry.Trace;

+internal class Program

+{

+ static void Main(string[] args)

+ {

+ TracerProvider tracerProvider = Sdk.CreateTracerProviderBuilder()

+ .AddHttpClientInstrumentation()

+ .AddSqlClientInstrumentation()

+ .AddAzureMonitorTraceExporter()

+ .Build();

+ MeterProvider meterProvider = Sdk.CreateMeterProviderBuilder()

+ .AddHttpClientInstrumentation()

+ .AddAzureMonitorMetricExporter()

+ .Build();

+ ILoggerFactory loggerFactory = LoggerFactory.Create(builder =>

+ {

+ builder.AddOpenTelemetry(o => o.AddAzureMonitorLogExporter());

+ });

+ Console.WriteLine("Hello, World!");

+ tracerProvider.Dispose();

+ meterProvider.Dispose();

+ loggerFactory.Dispose();

+ }

+}

+```

+We recommend setting your Connection String in an environment variable:

+`APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>`

+More options to configure the Connection String are detailed here: [Configure the Application Insights Connection String](./opentelemetry-configuration.md?tabs=net#connection-string).

+### Remove custom configurations

+The following scenarios are optional and apply to advanced users.

+* If you have any more references to the `TelemetryClient`, which is used to [manually record telemetry](./api-custom-events-metrics.md), they should be removed.

+* Remove any [custom filtering or enrichment](./api-filtering-sampling.md) added as a custom `TelemetryProcessor` or `TelemetryInitializer`. The configuration references them.

+* Remove any Visual Studio Artifacts

+ If you used Visual Studio to onboard to Application Insights, you could have more files left over in your project.

+ - `ConnectedService.json` might have a reference to your Application Insights resource.

+ - `[Your project's name].csproj` might have a reference to your Application Insights resource:

+ ```xml

+ <ApplicationInsightsResourceId>/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/Default-ApplicationInsights-EastUS/providers/microsoft.insights/components/WebApplication4</ApplicationInsightsResourceId>

+ ```

+### [WorkerService](#tab/workerservice)

+To send your telemetry to Application Insights, the Azure Monitor Exporter must be added to the configuration of all three signals.

+##### Program.cs

+The following code sample expands on the previous example.

+It now collects telemetry and sends to Application Insights.

+```csharp

+using Microsoft.Extensions.DependencyInjection;

+using Microsoft.Extensions.Hosting;

+using Microsoft.Extensions.Logging;

+public class Program

+{

+ public static void Main(string[] args)

+ {

+ var builder = Host.CreateApplicationBuilder(args);

+ builder.Services.AddHostedService<Worker>();

+ builder.Services.AddOpenTelemetry()

+ .WithTracing(builder =>

+ {

+ builder.AddHttpClientInstrumentation();

+ builder.AddSqlClientInstrumentation();

+ builder.AddAzureMonitorTraceExporter();

+ })

+ .WithMetrics(builder =>

+ {

+ builder.AddHttpClientInstrumentation();

+ builder.AddAzureMonitorMetricExporter();

+ });

+ builder.Logging.AddOpenTelemetry(builder => builder.AddAzureMonitorLogExporter());

+ var host = builder.Build();

+ host.Run();

+ }

+}

+```

+We recommend setting your Connection String in an environment variable:

+`APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>`

+More options to configure the Connection String are detailed here: [Configure the Application Insights Connection String](./opentelemetry-configuration.md?tabs=net#connection-string).

+#### More configurations

+Application Insights offered many more configuration options via `ApplicationInsightsServiceOptions`.

+| Application Insights Setting | OpenTelemetry Alternative |

+|--|-|

+| AddAutoCollectedMetricExtractor | N/A |

+| ApplicationVersion | Set "service.version" on Resource |

+| ConnectionString | See [instructions](./opentelemetry-configuration.md?tabs=aspnetcore#connection-string) on configuring the Connection String. |

+| DependencyCollectionOptions | N/A. To customize dependencies, review the available configuration options for applicable Instrumentation libraries. |

+| DeveloperMode | N/A |

+| EnableAdaptiveSampling | N/A. Only fixed-rate sampling is supported. |

+| EnableAppServicesHeartbeatTelemetryModule | N/A |

+| EnableAzureInstanceMetadataTelemetryModule | N/A |

+| EnableDependencyTrackingTelemetryModule | See instructions on filtering Traces. |

+| EnableDiagnosticsTelemetryModule | N/A |

+| EnableEventCounterCollectionModule | N/A |

+| EnableHeartbeat | N/A |

+| EnablePerformanceCounterCollectionModule | N/A |

+| EnableQuickPulseMetricStream | AzureMonitorOptions.EnableLiveMetrics |

+| EndpointAddress | Use ConnectionString. |

+| InstrumentationKey | Use ConnectionString. |

+### Remove Custom Configurations

+The following scenarios are optional and apply to advanced users.

+* If you have any more references to the `TelemetryClient`, which are used to [manually record telemetry](./api-custom-events-metrics.md), they should be removed.

+* If you added any [custom filtering or enrichment](./api-filtering-sampling.md) in the form of a custom `TelemetryProcessor` or `TelemetryInitializer`, it should be removed. You can find references in your `ServiceCollection`.

+ ```csharp

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

+ ```

+ ```csharp

+ builder.Services.AddApplicationInsightsTelemetryProcessor<MyCustomTelemetryProcessor>();

+ ```

+* Remove any Visual Studio Artifacts

+ If you used Visual Studio to onboard to Application Insights, you could have more files left over in your project.

+ - `Properties/ServiceDependencies` directory might have a reference to your Application Insights resource.

+> [!Tip]

+> Our product group is actively seeking feedback on this documentation. Provide feedback to otel@microsoft.com or see the [Support](#support) section.

+## Frequently asked questions

+This section is for customers who use telemetry initializers or processors, or write custom code against the classic Application Insights API to create custom telemetry.

+### How do the SDK API's map to OpenTelemetry concepts?

+[OpenTelemetry](https://opentelemetry.io/) is a vendor neutral observability framework. There are no Application Insights APIs in the OpenTelemetry SDK or libraries. Before migrating, it's important to understand some of OpenTelemetry's concepts.

+* In Application Insights, all telemetry was managed through a single `TelemetryClient` and `TelemetryConfiguration`. In OpenTelemetry, each of the three telemetry signals (Traces, Metrics, and Logs) has its own configuration. You can manually create telemetry via the .NET runtime without external libraries. For more information, see the .NET guides on [distributed tracing](/dotnet/core/diagnostics/distributed-tracing-instrumentation-walkthroughs), [metrics](/dotnet/core/diagnostics/metrics), and [logging](/dotnet/core/extensions/logging).

+* Application Insights used `TelemetryModules` to automatically collect telemetry for your application.

+Instead, OpenTelemetry uses [Instrumentation libraries](https://opentelemetry.io/docs/specs/otel/overview/#instrumentation-libraries) to collect telemetry from specific components (such as [AspNetCore](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.AspNetCore) for Requests and [HttpClient](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.Http) for Dependencies).

+* Application Insights used `TelemetryInitializers` to enrich telemetry with additional information or to override properties.

+With OpenTelemetry, you can write a [Processor](https://opentelemetry.io/docs/collector/configuration/#processors) to customize a specific signal. Additionally, many OpenTelemetry Instrumentation libraries offer an `Enrich` method to customize the telemetry generated by that specific component.

+* Application Insights used `TelemetryProcessors` to filter telemetry. An OpenTelemetry [Processor](https://opentelemetry.io/docs/collector/configuration/#processors) can also be used to apply filtering rules on a specific signal.

+### How do Application Insights telemetry types map to OpenTelemetry?

+This table maps Application Insights data types to OpenTelemetry concepts and their .NET implementations.

+| Azure Monitor Table | Application Insights DataType | OpenTelemetry DataType | .NET Implementation |

+||-||--|

+| customEvents | EventTelemetry | N/A | N/A |

+| customMetrics | MetricTelemetry | Metrics | System.Diagnostics.Metrics.Meter |

+| dependencies | DependencyTelemetry | Spans (Client, Internal, Consumer) | System.Diagnostics.Activity |

+| exceptions | ExceptionTelemetry | Exceptions | System.Exception |

+| requests | RequestTelemetry | Spans (Server, Producer) | System.Diagnostics.Activity |

+| traces | TraceTelemetry | Logs | Microsoft.Extensions.Logging.ILogger |

+The following documents provide more information.

+- [Data Collection Basics of Azure Monitor Application Insights](./opentelemetry-overview.md)

+- [Application Insights telemetry data model](./data-model-complete.md)

+- [OpenTelemetry Concepts](https://opentelemetry.io/docs/concepts/)

+### How do Application Insights sampling concepts map to OpenTelemetry?

+While Application Insights offered multiple options to configure sampling, Azure Monitor Exporter or Azure Monitor Distro only offers fixed rate sampling. Only *Requests* and *Dependencies* (*OpenTelemetry Traces*) can be sampled.

+For code samples detailing how to configure sampling, see our guide [Enable Sampling](./opentelemetry-configuration.md#enable-sampling)

+### How do Telemetry Processors and Initializers map to OpenTelemetry?

+In the Application Insights .NET SDK, use telemetry processors to filter and modify or discard telemetry. Use telemetry initializers to add or modify custom properties. For more information, see the [Azure Monitor documentation](./api-filtering-sampling.md). OpenTelemetry replaces these concepts with activity or log processors, which enrich and filter telemetry.

+#### Filtering Traces

+To filter telemetry data in OpenTelemetry, you can implement an activity processor. This example is equivalent to the Application Insights example for filtering telemetry data as described in [Azure Monitor documentation](./api-filtering-sampling.md). The example illustrates where unsuccessful dependency calls are filtered.

+```csharp

+using System.Diagnostics;

+using OpenTelemetry;

+internal sealed class SuccessfulDependencyFilterProcessor : BaseProcessor<Activity>

+{

+ public override void OnEnd(Activity activity)

+ {

+ if (!OKtoSend(activity))

+ {

+ activity.ActivityTraceFlags &= ~ActivityTraceFlags.Recorded;

+ }

+ }

+ private bool OKtoSend(Activity activity)

+ {

+ return activity.Kind == ActivityKind.Client && activity.Status == ActivityStatusCode.Ok;

+ }

+}

+```

+To use this processor, you need to create a `TracerProvider` and add the processor before `AddAzureMonitorTraceExporter`.

+```csharp

+using OpenTelemetry.Trace;

+public static void Main()

+{

+ var tracerProvider = Sdk.CreateTracerProviderBuilder()

+ .AddProcessor(new SuccessfulDependencyFilterProcessor())

+ .AddAzureMonitorTraceExporter()

+ .Build();

+}

+```

+#### Filtering Logs

+[`ILogger`](/dotnet/core/extensions/logging)

+implementations have a built-in mechanism to apply [log

+filtering](/dotnet/core/extensions/logging?tabs=command-line#how-filtering-rules-are-applied).

+This filtering lets you control the logs that are sent to each registered

+provider, including the `OpenTelemetryLoggerProvider`. "OpenTelemetry" is the

+[alias](/dotnet/api/microsoft.extensions.logging.provideraliasattribute)

+for `OpenTelemetryLoggerProvider`, used in configuring filtering rules.

+The following example defines "Error" as the default `LogLevel`

+and also defines "Warning" as the minimum `LogLevel` for a user defined category.

+These rules as defined only apply to the `OpenTelemetryLoggerProvider`.

+```csharp

+builder.AddFilter<OpenTelemetryLoggerProvider>("*", LogLevel.Error);

+builder.AddFilter<OpenTelemetryLoggerProvider>("MyProduct.MyLibrary.MyClass", LogLevel.Warning);

+```

+For more information, please read the [OpenTelemetry .NET documentation on logs](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/docs/logs/README.md).

+#### Adding Custom Properties to Traces

+In OpenTelemetry, you can use activity processors to enrich telemetry data with more properties. It's similar to using telemetry initializers in Application Insights, where you can modify telemetry properties.

+By default, Azure Monitor Exporter flags any HTTP request with a response code of 400 or greater as failed. However, if you want to treat 400 as a success, you can add an enriching activity processor that sets the success on the activity and adds a tag to include more telemetry properties. It's similar to adding or modifying properties using an initializer in Application Insights as described in [Azure Monitor documentation](./api-filtering-sampling.md?tabs=javascriptwebsdkloaderscript#addmodify-properties-itelemetryinitializer).

+Here's an example of how to add custom properties and override the default behavior for certain response codes:

+```csharp

+using System.Diagnostics;

+using OpenTelemetry;

+/// <summary>

+/// Custom Processor that overrides the default behavior of treating response codes >= 400 as failed requests.

+/// </summary>

+internal class MyEnrichingProcessor : BaseProcessor<Activity>

+{

+ public override void OnEnd(Activity activity)

+ {

+ if (activity.Kind == ActivityKind.Server)

+ {

+ int responseCode = GetResponseCode(activity);

+ if (responseCode >= 400 && responseCode < 500)

+ {

+ // If we set the Success property, the SDK won't change it

+ activity.SetStatus(ActivityStatusCode.Ok);

+ // Allow to filter these requests in the portal

+ activity.SetTag("Overridden400s", "true");

+ }

+ // else leave the SDK to set the Success property

+ }

+ }

+ private int GetResponseCode(Activity activity)

+ {

+ foreach (ref readonly var tag in activity.EnumerateTagObjects())

+ {

+ if (tag.Key == "http.response.status_code" && tag.Value is int value)

+ {

+ return value;

+ }

+ }

+ return 0;

+ }

+}

+```

+To use this processor, you need to create a `TracerProvider` and add the processor before `AddAzureMonitorTraceExporter`.

+```csharp

+using OpenTelemetry.Trace;

+public static void Main()

+{

+ var tracerProvider = Sdk.CreateTracerProviderBuilder()

+ .AddSource("Company.Product.Name")

+ .AddProcessor(new MyEnrichingProcessor())

+ .AddAzureMonitorTraceExporter()

+ .Build();

+}

+```

+### How do I manually track telemetry using OpenTelemetry?

+#### Sending Traces - Manual

+Traces in Application Insights are stored as `RequestTelemetry` and `DependencyTelemetry`. In OpenTelemetry, traces are modeled as `Span` using the `Activity` class.

+OpenTelemetry .NET utilizes the `ActivitySource` and `Activity` classes for tracing, which are part of the .NET runtime. This approach is distinctive because the .NET implementation integrates the tracing API directly into the runtime itself. The `System.Diagnostics.DiagnosticSource` package allows developers to use `ActivitySource` to create and manage `Activity` instances. This method provides a seamless way to add tracing to .NET applications without relying on external libraries, applying the built-in capabilities of the .NET ecosystem. For more detailed information, refer to the [distributed tracing instrumentation walkthroughs](/dotnet/core/diagnostics/distributed-tracing-instrumentation-walkthroughs).

+Here's how to migrate manual tracing:

+ > [!Note]

+ > In Application Insights, the role name and role instance could be set at a per-telemetry level. However, with the Azure Monitor Exporter, we cannot customize at a per-telemetry level. The role name and role instance are extracted from the OpenTelemetry resource and applied across all telemetry. Please read this document for more information: [Set the cloud role name and the cloud role instance](./opentelemetry-configuration.md?tabs=aspnetcore#set-the-cloud-role-name-and-the-cloud-role-instance).

+#### DependencyTelemetry

+Application Insights `DependencyTelemetry` is used to model outgoing requests. Here's how to convert it to OpenTelemetry:

+**Application Insights Example:**

+```csharp

+DependencyTelemetry dep = new DependencyTelemetry

+{

+ Name = "DependencyName",

+ Data = "https://www.example.com/",

+ Type = "Http",

+ Target = "www.example.com",

+ Duration = TimeSpan.FromSeconds(10),

+ ResultCode = "500",

+ Success = false

+};

+dep.Context.Cloud.RoleName = "MyRole";

+dep.Context.Cloud.RoleInstance = "MyRoleInstance";

+dep.Properties["customprop1"] = "custom value1";

+client.TrackDependency(dep);

+```

+**OpenTelemetry Example:**

+```csharp

+var activitySource = new ActivitySource("Company.Product.Name");

+var resourceAttributes = new Dictionary<string, object>

+{

+ { "service.name", "MyRole" },

+ { "service.instance.id", "MyRoleInstance" }

+};

+var resourceBuilder = ResourceBuilder.CreateDefault().AddAttributes(resourceAttributes);

+using var tracerProvider = Sdk.CreateTracerProviderBuilder()

+ .SetResourceBuilder(resourceBuilder)

+ .AddSource(activitySource.Name)

+ .AddAzureMonitorTraceExporter()

+ .Build();

+// Emit traces

+using (var activity = activitySource.StartActivity("DependencyName", ActivityKind.Client))

+{

+ activity?.SetTag("url.full", "https://www.example.com/");

+ activity?.SetTag("server.address", "www.example.com");

+ activity?.SetTag("http.request.method", "GET");

+ activity?.SetTag("http.response.status_code", "500");

+ activity?.SetTag("customprop1", "custom value1");

+ activity?.SetStatus(ActivityStatusCode.Error);

+ activity?.SetEndTime(activity.StartTimeUtc.AddSeconds(10));

+}

+```

+#### RequestTelemetry

+Application Insights `RequestTelemetry` models incoming requests. Here's how to migrate it to OpenTelemetry:

+**Application Insights Example:**

+```csharp

+RequestTelemetry req = new RequestTelemetry

+{

+ Name = "RequestName",

+ Url = new Uri("http://example.com"),

+ Duration = TimeSpan.FromSeconds(10),

+ ResponseCode = "200",

+ Success = true,

+ Properties = { ["customprop1"] = "custom value1" }

+};

+req.Context.Cloud.RoleName = "MyRole";

+req.Context.Cloud.RoleInstance = "MyRoleInstance";

+client.TrackRequest(req);

+```

+**OpenTelemetry Example:**

+```csharp

+var activitySource = new ActivitySource("Company.Product.Name");

+var resourceAttributes = new Dictionary<string, object>

+{

+ { "service.name", "MyRole" },

+ { "service.instance.id", "MyRoleInstance" }

+};

+var resourceBuilder = ResourceBuilder.CreateDefault().AddAttributes(resourceAttributes);

+using var tracerProvider = Sdk.CreateTracerProviderBuilder()

+ .SetResourceBuilder(resourceBuilder)

+ .AddSource(activitySource.Name)

+ .AddAzureMonitorTraceExporter()

+ .Build();

+// Emit traces

+using (var activity = activitySource.StartActivity("RequestName", ActivityKind.Server))

+{

+ activity?.SetTag("url.scheme", "https");

+ activity?.SetTag("server.address", "www.example.com");

+ activity?.SetTag("url.path", "/");

+ activity?.SetTag("http.response.status_code", "200");

+ activity?.SetTag("customprop1", "custom value1");

+ activity?.SetStatus(ActivityStatusCode.Ok);

+}

+```

+#### Custom Operations Tracking

+In Application Insights, track custom operations using `StartOperation` and `StopOperation` methods. Achieve it using `ActivitySource` and `Activity` in OpenTelemetry .NET. For operations with `ActivityKind.Server` and `ActivityKind.Consumer`, Azure Monitor Exporter generates `RequestTelemetry`. For `ActivityKind.Client`, `ActivityKind.Producer`, and `ActivityKind.Internal`, it generates `DependencyTelemetry`. For more information on custom operations tracking, see the [Azure Monitor documentation](./custom-operations-tracking.md). For more on using `ActivitySource` and `Activity` in .NET, see the [.NET distributed tracing instrumentation walkthroughs](/dotnet/core/diagnostics/distributed-tracing-instrumentation-walkthroughs#activity).

+Here's an example of how to start and stop an activity for custom operations:

+```csharp

+using System.Diagnostics;

+using OpenTelemetry;

+var activitySource = new ActivitySource("Company.Product.Name");

+using var tracerProvider = Sdk.CreateTracerProviderBuilder()

+ .AddSource(activitySource.Name)

+ .AddAzureMonitorTraceExporter()

+ .Build();

+// Start a new activity

+using (var activity = activitySource.StartActivity("CustomOperation", ActivityKind.Server))

+{

+ activity?.SetTag("customTag", "customValue");

+ // Perform your custom operation logic here

+ // No need to explicitly call Activity.Stop() because the using block automatically disposes the Activity object, which stops it.

+}

+```

+#### Sending Logs

+Logs in Application Insights are stored as `TraceTelemetry` and `ExceptionTelemetry`.

+##### TraceTelemetry

+In OpenTelemetry, logging is integrated via the `ILogger` interface. Here's how to migrate `TraceTelemetry`:

+**Application Insights Example:**

+```csharp

+TraceTelemetry traceTelemetry = new TraceTelemetry

+{

+ Message = "hello from tomato 2.99",

+ SeverityLevel = SeverityLevel.Warning,

+};

+traceTelemetry.Context.Cloud.RoleName = "MyRole";

+traceTelemetry.Context.Cloud.RoleInstance = "MyRoleInstance";

+client.TrackTrace(traceTelemetry);

+```

+**OpenTelemetry Example:**

+```csharp

+var resourceAttributes = new Dictionary<string, object>

+{

+ { "service.name", "MyRole" },

+ { "service.instance.id", "MyRoleInstance" }

+};

+var resourceBuilder = ResourceBuilder.CreateDefault().AddAttributes(resourceAttributes);

+using var loggerFactory = LoggerFactory.Create(builder => builder

+ .AddOpenTelemetry(loggerOptions =>

+ {

+ loggerOptions.SetResourceBuilder(resourceBuilder);

+ loggerOptions.AddAzureMonitorLogExporter();

+ }));

+// Create a new instance `ILogger` from the above LoggerFactory

+var logger = loggerFactory.CreateLogger<Program>();

+// Use the logger instance to write a new log

+logger.FoodPrice("tomato", 2.99);

+internal static partial class LoggerExtensions

+{

+ [LoggerMessage(LogLevel.Warning, "Hello from `{name}` `{price}`.")]

+ public static partial void FoodPrice(this ILogger logger, string name, double price);

+}

+```

+##### ExceptionTelemetry

+Application Insights uses `ExceptionTelemetry` to log exceptions. Here's how to migrate to OpenTelemetry:

+**Application Insights Example:**

+```csharp

+ExceptionTelemetry exceptionTelemetry = new ExceptionTelemetry(new Exception("Test exception"))

+{

+ SeverityLevel = SeverityLevel.Error

+};

+exceptionTelemetry.Context.Cloud.RoleName = "MyRole";

+exceptionTelemetry.Context.Cloud.RoleInstance = "MyRoleInstance";

+exceptionTelemetry.Properties["customprop1"] = "custom value1";

+client.TrackException(exceptionTelemetry);

+```

+**OpenTelemetry Example:**

+```csharp

+var resourceAttributes = new Dictionary<string, object>

+{

+ { "service.name", "MyRole" },

+ { "service.instance.id", "MyRoleInstance" }

+};

+var resourceBuilder = ResourceBuilder.CreateDefault().AddAttributes(resourceAttributes);

+using var loggerFactory = LoggerFactory.Create(builder => builder

+ .AddOpenTelemetry(loggerOptions =>

+ {

+ loggerOptions.SetResourceBuilder(resourceBuilder);

+ loggerOptions.AddAzureMonitorLogExporter();

+ }));

+// Create a new instance `ILogger` from the above LoggerFactory.

+var logger = loggerFactory.CreateLogger<Program>();

+try

+{

+ // Simulate exception

+ throw new Exception("Test exception");

+}

+catch (Exception ex)

+{

+ logger?.LogError(ex, "An error occurred");

+}

+```

+#### Sending Metrics

+Metrics in Application Insights are stored as `MetricTelemetry`. In OpenTelemetry, metrics are modeled as `Meter` from the `System.Diagnostics.DiagnosticSource` package.

+Application Insights has both non-pre-aggregating (`TrackMetric()`) and preaggregating (`GetMetric().TrackValue()`) Metric APIs. Unlike OpenTelemetry, Application Insights has no notion of [Instruments](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/supplementary-guidelines.md#instrument-selection). Application Insights has the same API for all the metric scenarios.

+OpenTelemetry, on the other hand, requires users to first [pick the right metric instrument](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/supplementary-guidelines.md#instrument-selection) based on the actual semantics of the metric. For example, if the intention is to count something (like the number of total server requests received, etc.), [OpenTelemetry Counter](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#counter) should be used. If the intention is to calculate various percentiles (like the P99 value of server latency), then [OpenTelemetry Histogram](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#histogram) instrument should be used. Due to this fundamental difference between Application Insights and OpenTelemetry, no direct comparison is made between them.

+Unlike Application Insights, OpenTelemetry doesn't provide built-in mechanisms to enrich or filter metrics. In Application Insights, telemetry processors and initializers could be used to modify or discard metrics, but this capability isn't available in OpenTelemetry.

+Additionally, OpenTelemetry doesn't support sending raw metrics directly, as there's no equivalent to the `TrackMetric()` functionality found in Application Insights.

+Migrating from Application Insights to OpenTelemetry involves replacing all Application Insights Metric API usages with the OpenTelemetry API. It requires understanding the various OpenTelemetry Instruments and their semantics.

+> [!Tip]

+> The histogram is the most versatile and the closest equivalent to the Application Insights `GetMetric().TrackValue()` API. You can replace Application Insights Metric APIs with Histogram to achieve the same purpose.

+#### Other Telemetry Types

+##### CustomEvents

+Not supported in OpenTelemetry.

+**Application Insights Example:**

+```csharp

+TelemetryClient.TrackEvent()

+```

+##### AvailabilityTelemetry

+Not supported in OpenTelemetry.

+**Application Insights Example:**

+```csharp

+TelemetryClient.TrackAvailability()

+```

+##### PageViewTelemetry

+Not supported in OpenTelemetry.

+**Application Insights Example:**

+```csharp

+TelemetryClient.TrackPageView()

+```

+## Next steps

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

+* [Azure Monitor Distro Demo project](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/monitor/Azure.Monitor.OpenTelemetry.AspNetCore/tests/Azure.Monitor.OpenTelemetry.AspNetCore.Demo)

+* [OpenTelemetry SDK's getting started guide](https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/src/OpenTelemetry)

+* [OpenTelemetry's example ASP.NET Core project](https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/examples/AspNetCore)

+* [C# and .NET Logging](/dotnet/core/extensions/logging)

+* [Azure Monitor OpenTelemetry getting started with ASP.NET Core](./opentelemetry-enable.md?tabs=aspnetcore)

+### [ASP.NET](#tab/net)

+* [OpenTelemetry SDK's getting started guide](https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/src/OpenTelemetry)

+* [OpenTelemetry's example ASP.NET project](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/blob/main/examples/AspNet/Global.asax.cs)

+* [C# and .NET Logging](/dotnet/core/extensions/logging)

+* [Azure Monitor OpenTelemetry getting started with .NET](./opentelemetry-enable.md?tabs=net)

+### [Console](#tab/console)

+* [OpenTelemetry SDK's getting started guide](https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/src/OpenTelemetry)

+* OpenTelemetry's example projects:

+ * [Getting Started with Traces](https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/trace/getting-started-console)

+ * [Getting Started with Metrics](https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/metrics/getting-started-console)

+ * [Getting Started with Logs](https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/logs/getting-started-console)

+* [C# and .NET Logging](/dotnet/core/extensions/logging)

+* [Azure Monitor OpenTelemetry getting started with .NET](./opentelemetry-enable.md?tabs=net)

+### [WorkerService](#tab/workerservice)

+* [OpenTelemetry SDK's getting started guide](https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/src/OpenTelemetry)

+* [Logging in C# and .NET](/dotnet/core/extensions/logging)

+* [Azure Monitor OpenTelemetry getting started with .NET](./opentelemetry-enable.md?tabs=net)

+> [!Tip]

+> Our product group is actively seeking feedback on this documentation. Provide feedback to otel@microsoft.com or see the [Support](#support) section.

+## Support

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

+- For Azure support issues, open an [Azure support ticket](https://azure.microsoft.com/support/create-ticket/).

+- For OpenTelemetry issues, contact the [OpenTelemetry .NET community](https://github.com/open-telemetry/opentelemetry-dotnet) directly.

+- For a list of open issues related to Azure Monitor Exporter, see the [GitHub Issues Page](https://github.com/Azure/azure-sdk-for-net/issues?q=is%3Aopen+is%3Aissue+label%3A%22Monitor+-+Exporter%22).

+#### [.NET](#tab/net)

+- For Azure support issues, open an [Azure support ticket](https://azure.microsoft.com/support/create-ticket/).

+- For OpenTelemetry issues, contact the [OpenTelemetry .NET community](https://github.com/open-telemetry/opentelemetry-dotnet) directly.

+- For a list of open issues related to Azure Monitor Exporter, see the [GitHub Issues Page](https://github.com/Azure/azure-sdk-for-net/issues?q=is%3Aopen+is%3Aissue+label%3A%22Monitor+-+Exporter%22).

+### [Console](#tab/console)

+- For Azure support issues, open an [Azure support ticket](https://azure.microsoft.com/support/create-ticket/).

+- For OpenTelemetry issues, contact the [OpenTelemetry .NET community](https://github.com/open-telemetry/opentelemetry-dotnet) directly.

+- For a list of open issues related to Azure Monitor Exporter, see the [GitHub Issues Page](https://github.com/Azure/azure-sdk-for-net/issues?q=is%3Aopen+is%3Aissue+label%3A%22Monitor+-+Exporter%22).

+### [WorkerService](#tab/workerservice)

+- For Azure support issues, open an [Azure support ticket](https://azure.microsoft.com/support/create-ticket/).

+- For OpenTelemetry issues, contact the [OpenTelemetry .NET community](https://github.com/open-telemetry/opentelemetry-dotnet) directly.

+- For a list of open issues related to Azure Monitor Exporter, see the [GitHub Issues Page](https://github.com/Azure/azure-sdk-for-net/issues?q=is%3Aopen+is%3Aissue+label%3A%22Monitor+-+Exporter%22).

+> [!Tip]

+> If you're migrating from the Application Insights Classic API, see our [migration documentation](./opentelemetry-dotnet-migrate.md).

+### [.NET](#tab/net)

+> [!Tip]

+> If you're migrating from the Application Insights Classic API, see our [migration documentation](./opentelemetry-dotnet-migrate.md).

+### [Java](#tab/java)

+> [!Tip]

+> If you're migrating from the Application Insights Classic API, see our [migration documentation](./opentelemetry-nodejs-migrate.md).

+### [Python](#tab/python)

+> [!Tip]

+> If you're migrating from OpenCensus, see our [migration documentation](./opentelemetry-python-opencensus-migrate.md).

+##### Node.js version support

+For a version of Node.js to be supported by the ApplicationInsights 3.X SDK, it must have overlapping support from both the Azure SDK and OpenTelemetry. Check the [OpenTelemetry supported runtimes](https://github.com/open-telemetry/opentelemetry-js#supported-runtimes) for the latest updates. Users on older versions like Node 8, previously supported by the ApplicationInsights SDK, can still use OpenTelemetry solutions but can experience unexpected or breaking behavior. The ApplicationInsights SDK also depends on the Azure SDK for JS which does not guarantee support for any Node.js versions that have reached end-of-life. See [the Azure SDK for JS support policy](https://github.com/Azure/azure-sdk-for-js/blob/main/SUPPORT.md). For a version of Node.js to be supported by the ApplicationInsights 3.X SDK, it must have overlapping support from both the Azure SDK and OpenTelemetry.

+| Java | Not supported | Not supported | [Supported](opentelemetry-add-modify.md?tabs=java#send-custom-telemetry-using-the-application-insights-classic-api) |

+* Capture log traces from your favorite logging framework in [.NET](./asp-net-trace-logs.md) or [Java](./opentelemetry-add-modify.md?tabs=java#send-custom-telemetry-using-the-application-insights-classic-api). This means you can search through your log traces and correlate them with page views, exceptions, and other events.

+Administrator permissions for the cluster or resource are required to complete the steps in this article.

+Remote-write is configured in the Prometheus configuration file `prometheus.yml`, or in the Prometheus Operator.

+### [Configure remote-write for Prometheus Operator](#tab/prom-operator)

+If you are running Prometheus Operator on a Kubernetes cluster, follow the below steps to send data to your Azure Monitor Workspace.

+1. If you are using Microsoft Entra ID authentication, convert the secret using base64 encoding, and then apply the secret into your Kubernetes cluster. Save the following into a yaml file. Skip this step if you are using managed identity authentication.

+```yaml

+apiVersion: v1

+kind: Secret

+metadata:

+ name: remote-write-secret

+ namespace: monitoring # Replace with namespace where Prometheus Operator is deployed.

+type: Opaque

+data:

+ password: <base64-encoded-secret>

+```

+Apply the secret.

+```azurecli

+# set context to your cluster

+az aks get-credentials -g <aks-rg-name> -n <aks-cluster-name>

+kubectl apply -f <remote-write-secret.yaml>

+```

+2. You will need to update the values for remote write section in Prometheus Operator. Copy the following and save it as a yaml file. For the values of the yaml file, see below section. Refer to [Prometheus Operator documentation](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api.md#azuread) for more details on the Azure Monitor Workspace remote write specification in Prometheus Operator.

+```yaml

+prometheus:

+ prometheusSpec:

+ remoteWrite:

+ - url: "<metrics ingestion endpoint for your Azure Monitor workspace>"

+ azureAd:

+# AzureAD configuration.

+# The Azure Cloud. Options are 'AzurePublic', 'AzureChina', or 'AzureGovernment'.

+ cloud: 'AzurePublic'

+ managedIdentity:

+ clientId: "<clientId of the managed identity>"

+ oauth:

+ clientId: "<clientId of the Entra app>"

+ clientSecret:

+ name: remote-write-secret

+ key: password

+ tenantId: "<Azure subscription tenant Id>"

+```

+3. Use helm to update your remote write config using the above yaml file.

+```azurecli

+helm upgrade -f <YAML-FILENAME>.yml prometheus prometheus-community/kube-prometheus-stack --namespace <namespace where Prometheus Operator is deployed>

+```

+### [Configure remote-write for Prometheus running in VMs or other environments](#tab/prom-vm)

+To send data to your Azure Monitor Workspace, add the following section to the configuration file (prometheus.yml) of your self-managed Prometheus instance.

+## Sampling rate and overhead

+Profiler randomly runs two minutes per hour on each virtual machine hosting applications with Profiler enabled.

+[Enable Profiler and view traces](profiler.md?toc=/azure/azure-monitor/toc.json)

+## Are you aware of the Profiler sampling rate and overhead?

+Profiler randomly runs two minutes per hour on each virtual machine hosting applications with Profiler enabled.

+[Application Insights Profiler](./profiler-overview.md) is preinstalled as part of the Azure App Service runtime. You can run Profiler on ASP.NET and ASP.NET Core apps running on App Service by using the Basic service tier or higher. Follow these steps, even if you included the Application Insights SDK in your application at build time.

+ms.assetid:

+ Title: Monitor Azure and Off-Azure Virtual machines with Azure Monitor SCOM Managed Instance extensions.

+description: Azure Monitor SCOM Managed Instance provides a cloud-based alternative for Operations Manager users providing monitoring continuity for cloud and on-premises environments across the cloud adoption journey.

+# Monitor Azure and Off-Azure Virtual machines with Azure Monitor SCOM Managed Instance extensions

+Azure Monitor SCOM Managed Instance provides a cloud-based alternative for Operations Manager users providing monitoring continuity for cloud and on-premises environments across the cloud adoption journey.

+## SCOM Managed Instance Agent

+In Azure Monitor SCOM Managed Instance, an agent is a service that is installed on a computer that looks for configuration data and proactively collects information for analysis and reporting, measures the health state of monitored objects like an SQL database or logical disk, and executes tasks on demand by an operator or in response to a condition. It allows SCOM Managed Instance to monitor Windows operating systems and the components installed on them, such as a website or an Active Directory domain controller.

+In Azure Monitor SCOM Managed Instance, monitoring agent is installed and managed by Azure Virtual Machine Extensions, named **SCOMMI-Agent-Windows**. For more information on VM extensions, see [Azure Virtual Machine extensions and features](/azure/virtual-machines/extensions/overview).

+## Supported Windows versions for monitoring

+Following are the supported Windows versions that can be monitored using SCOM Managed Instance:

+- Windows 2022

+- Windows 2019

+- Windows 2016

+- Windows 2012 R2

+- Windows 2012

+For more information, see [Operations Manager System requirements](/system-center/scom/system-requirements).

+## Use Arc channel for Agent configuration and monitoring data

+Azure Arc can unlock connectivity and monitor on-premises workloads. Azure based manageability of monitoring agents for SCOM Managed Instance helps you to reduce operations cost and simplify agent configuration. The following are the key capabilities of SCOM Managed Instance monitoring over Arc channel:

+- Discover and Install SCOM Managed Instance agent as a VM extension for Arc connected servers.

+- Monitor Arc connected servers and hosted applications by reusing existing System Center Operations Manager management packs.

+- Monitor Arc connected servers and applications, which are in untrusted domain/workgroup.

+- Azure based SCOM Managed Instance agent management (such as patch, push management pack rules and monitors) via Arc connectivity.

+## Prerequisites

+Following are the prerequisites required to monitor Virtual machines:

+1. Line of sight to Nexus endpoint.

+ For example, `Test-NetConnection -ComputerName westus.workloadnexus.azure.com -Port 443`

+2. Line of sight to SCOMMI LB

+ For example, `Test-NetConnection -ComputerName <LBDNS> -Port 5723`

+3. Ensure to install [.NET Framework 4.7.2](https://support.microsoft.com/topic/microsoft-net-framework-4-7-2-offline-installer-for-windows-05a72734-2127-a15d-50cf-daf56d5faec2) or higher on desired monitoring endpoints.

+To Troubleshooting connectivity problems, see [Troubleshoot issues with Azure Monitor SCOM Managed Instance](/system-center/scom/troubleshoot-scom-managed-instance?view=sc-om-2022#scenario-agent-connectivity-failing&preserve-view=true).

+## Install an agent to monitor Azure and Arc-enabled servers

+>[!NOTE]

+>Agent doesn't support multihoming to multiple SCOM Managed Instances.

+To install SCOM Managed Instance agent, follow these steps:

+1. On the desired SCOM Managed Instance **Overview** page, under Manage, select **Monitored Resources**.

+2. On the **Monitored Resources** page, select **New Monitored Resource**.

+ :::image type="content" source="media/monitor-azure-off-azure-vm-with-scom-managed-instance/monitored-resources-inline.png" alt-text="Screenshot that shows the Monitored Resource page." lightbox="media/monitor-azure-off-azure-vm-with-scom-managed-instance/monitored-resources-expanded.png":::

+ **Add a Monitored Resource** page opens listing all the unmonitored virtual machines.

+

+ :::image type="content" source="media/monitor-azure-off-azure-vm-with-scom-managed-instance/add-monitored-resource-inline.png" alt-text="Screenshot that shows add a monitored resource page." lightbox="media/monitor-azure-off-azure-vm-with-scom-managed-instance/add-monitored-resource-expanded.png":::

+3. Select the desired resource and then select **Add**.

+ :::image type="content" source="media/monitor-azure-off-azure-vm-with-scom-managed-instance/add-resource-inline.png" alt-text="Screenshot that shows the Add a resource option." lightbox="media/monitor-azure-off-azure-vm-with-scom-managed-instance/add-resource-expanded.png":::

+4. On the **Add Monitored Resources** window, enable **Auto upgrade**, review the selections and select **Add**.

+

+ :::image type="content" source="media/monitor-azure-off-azure-vm-with-scom-managed-instance/install-inline.png" alt-text="Screenshot that shows Install option." lightbox="media/monitor-azure-off-azure-vm-with-scom-managed-instance/install-expanded.png":::

+## Manage agent configuration installed on Azure and Arc-enabled servers

+### Upgrade an agent

+>[!NOTE]

+>Upgrading an agent is a one time effort for existing monitored resources. Further updates will be applied automatically to these resources. For new resources, you can choose this option when you add them to the SCOM Managed Instance.

+To upgrade the agent version, follow these steps:

+1. Sign in to the [Azure portal](https://portal.azure.com/). Search and select **SCOM Managed Instance**.

+2. On the **Overview** page, under **Manage**, select **SCOM managed instances**.

+3. On the **SCOM managed instances** page, select the desired SCOM managed instance.

+4. On the desired SCOM Managed Instance **Overview** page, under **Manage**, select **Monitored Resources**.

+5. On the **Monitored Resources** page, select Ellipsis button **(…)**, which is next to your desired monitored resource, and select **Configure**.

+

+ :::image type="content" source="media/monitor-azure-off-azure-vm-with-scom-managed-instance/resource-inline.png" alt-text="Screenshot that shows monitored resources." lightbox="media/monitor-azure-off-azure-vm-with-scom-managed-instance/resource-expanded.png":::

+ :::image type="content" source="media/monitor-azure-off-azure-vm-with-scom-managed-instance/configure-agent-inline.png" alt-text="Screenshot that shows agent configuration option." lightbox="media/monitor-azure-off-azure-vm-with-scom-managed-instance/configure-agent-expanded.png":::

+6. On the **Configure Monitored Resource** page, enable **Auto upgrade** and then select **Configure**.

+ :::image type="content" source="media/monitor-azure-off-azure-vm-with-scom-managed-instance/configure-monitored-resource-inline.png" alt-text="Screenshot that shows configuration option." lightbox="media/monitor-azure-off-azure-vm-with-scom-managed-instance/configure-monitored-resource-expanded.png":::

+### Remove an agent

+To remove the agent version, follow these steps:

+1. Sign in to the [Azure portal](https://portal.azure.com/). Search and select **SCOM Managed Instance**.

+2. On the **Overview** page, under **Manage**, select **SCOM managed instances**.

+3. On the **SCOM managed instances** page, select the desired SCOM Managed Instance.

+4. On the desired SCOM Managed Instance **Overview** page, under **Manage**, select **Monitored Resources**.

+5. On the **Monitored Resources** page, select Ellipsis button **(…)**, which is next to your desired monitored resource, and select **Remove**.

+ :::image type="content" source="media/monitor-azure-off-azure-vm-with-scom-managed-instance/delete-agent-inline.png" alt-text="Screenshot that shows delete agent option." lightbox="media/monitor-azure-off-azure-vm-with-scom-managed-instance/delete-agent-expanded.png":::

+6. On the **Remove Monitored Resources** page, enter *remove* under **Enter "remove" to confirm "removal"** and then select **Remove**.

+ :::image type="content" source="media/monitor-azure-off-azure-vm-with-scom-managed-instance/delete-monitored-resource-inline.png" alt-text="Screenshot that shows delete option." lightbox="media/monitor-azure-off-azure-vm-with-scom-managed-instance/delete-monitored-resource-expanded.png":::

+## Multihome On-premises virtual machines

+Multihoming allows you to monitor on-premises virtual machines by retaining the existing connection with Operations Manager (On-premises) and establishing a new connection with SCOM Managed Instance. When a virtual machine that is monitored by Operations Manager (on-premises) is multihomed with SCOM Managed Instance, the Azure extensions replace existing monitoring agent (*Monagent.msi*) with the latest version of SCOM Managed Instance agent. During this operation, the connection to Operations Manager (on-premises) is retained automatically to ensure continuity in monitoring process.

+>[!Note]

+>- To multihome your on-premises your virtual machines, they must be Arc-enabled.

+>- Multihome with Operations Manager is supported only using Kerberos authentication.

+>- Multihome is limited only to two connections, one with SCOM Managed Instance and another with Operations Manager. A virtual machine cannot be multihomed to multiple Operations Manager Management Groups or multiple SCOM Managed Instances.

+### Multihome supported scenarios

+Multihome is supported with the following Operations Manager versions using the SCOM Managed Instance extension-based agent:

+| -|Operations Manager 2012|Operations Manager 2016|Operations Manager 2019|Operations Manager 2022|

+||||||

+|Supported |✅|✅|✅|✅|

+>[!NOTE]

+>Agents (Monagent) that are installed by Operations Manager (on-premises) aren't supported to multihome with SCOM Managed Instance.

+## Jul-2024

+ "apiVersion": "2024-03-01",

+ "apiVersion": "2023-04-01",

+resource virtualNetwork 'Microsoft.Network/virtualNetworks@2023-11-01' = {

+resource exampleStorage 'Microsoft.Storage/storageAccounts@2023-04-01' = {

+resource virtualNetwork 'Microsoft.Network/virtualNetworks@2023-11-01' = {

+resource exampleStorage 'Microsoft.Storage/storageAccounts@2023-04-01' = {

+resource virtualNetwork 'Microsoft.Network/virtualNetworks@2023-11-01' = {

+resource exampleStorage 'Microsoft.Storage/storageAccounts@2023-04-01' = {

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

+ 'apiVersion': '2023-04-01'

+ 'apiVersion': '2023-04-01'

+resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {

+resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {

+resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {

+resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {

+resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {

+resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {

+resource aks 'Microsoft.ContainerService/managedClusters@2024-02-01' = {

+resource vm 'Microsoft.Compute/virtualMachines@2024-03-01' = {

+resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {

+resource exampleDnsZone 'Microsoft.Network/dnsZones@2023-07-01-preview' = {

+resource otherResource 'Microsoft.Example/examples@2024-05-01' = {

+resource myParent 'My.Rp/parentType@2024-05-01' = {

+resource dnsZone 'Microsoft.Network/dnszones@2023-07-01-preview' = {

+resource otherZone 'Microsoft.Network/dnszones@2023-07-01-preview' = {

+resource networkingSecretsKeyVault 'Microsoft.KeyVault/vaults@2023-07-01' existing = {

+resource createRgLock 'Microsoft.Authorization/locks@2020-05-01' = {

+resource roleAssignSub 'Microsoft.Authorization/roleAssignments@2022-04-01' = {

+resource demoStorageAcct 'Microsoft.Storage/storageAccounts@2023-04-01' = {

+resource roleAssignStorage 'Microsoft.Authorization/roleAssignments@2022-04-01' = {

+resource demoStorageAcct 'Microsoft.Storage/storageAccounts@2023-04-01' existing = {

+resource createStorageLock 'Microsoft.Authorization/locks@2020-05-01' = {

+

+ resource storage 'Microsoft.Storage/storageAccounts@2023-04-01' existing = {

+

+ resource storeLock 'Microsoft.Authorization/locks@2020-05-01' = {

+resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {

+resource createTemplateSpec 'Microsoft.Resources/templateSpecs@2022-02-01' = {

+resource createTemplateSpecVersion 'Microsoft.Resources/templateSpecs/versions@2022-02-01' = {

+ 'apiVersion': '2023-04-01'

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

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

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

+ "apiVersion": "2024-02-01",

+| Australia East | AZ01 | AV36P, AV64 | Yes |7|

+| Australia East | AZ02 | AV36, (AV64 Planned H2 2024)| No |N/A (7 Planned H2 2024) |

+| Australia East | AZ03 | AV36P, AV64 | Yes |7|

+| Canada Central | AZ02 | AV36, **AV36P,** (AV64 Planned H2 2024)| No |N/A (7 Planned H2 2024)|

+| Canada East | N/A | AV36| No | N/A |

+| Central India | AZ03 | AV36P, (AV64 Planned H2 2024) | No |N/A (7 Planned H2 2024) |

+| Central US | AZ01 | AV36P, (AV64 Planned H2 2024) | No |N/A (7 Planned H2 2024) |

+| Central US | AZ02 | **AV36**, (AV64 Planned H2 2024)| No |N/A (7 Planned H2 2024) |

+| Central US | AZ03 | AV36P, (AV64 Planned H2 2024) | No |N/A (7 Planned H2 2024) |

+| East Asia | AZ01 | AV36, (AV64 Planned H2 2024)| No |N/A (7 Planned H2 2024) |

+| East US | AZ01 | **AV36P****,** (AV64 Planned H2 2024)| Yes |N/A (7 Planned H2 2024) |

+| East US 2 | AZ01 | **AV36**, AV64 | No |7|

+| East US 2 | AZ02 | AV36P, **AV52**, AV64 | No | 7|

+| France Central | AZ01 | **AV36**, (AV64 Planned H2 2024)| No |N/A (7 Planned H2 2024) |

+| Germany West Central | AZ01 | AV36P, (AV64 Planned H2 2024)| Yes |N/A (7 Planned H2 2024) |

+| Germany West Central | AZ02 | **AV36**, (AV64 Planned H2 2024)| Yes |N/A (7 Planned H2 2024) |

+| Germany West Central | AZ03 | AV36, **AV36P**, AV64 | Yes |7|

+| Italy North | AZ03 | AV36P, (AV64 Planned H2 2024)| No |N/A (7 Planned H2 2024) |

+| Japan East | AZ02 | **AV36**, (AV64 Planned H2 2024)| No |N/A (7 Planned H2 2024) |

+| Japan West | AZ01 | **AV36**, (AV64 Planned H2 2024) | No |N/A (7 Planned H2 2024) |

+| North Central US | AZ01 | **AV36**, AV64 | No |7|

+| North Central US | AZ02 | AV36P, AV64 | No |7|

+| Qatar Central | AZ03 | AV36P, (AV64 Planned H2 2024)| No |N/A (7 Planned H2 2024) |

+| South Africa North | AZ03 | AV36, (AV64 Planned H2 2024) | No |N/A (7 Planned H2 2024) |

+| South Central US | AZ01 | AV36, AV64 | No | 7 |

+| South Central US | AZ02 | **AV36P**, AV52, AV64 | No | 7 |

+| Switzerland North | AZ03 | AV36P, (AV64 Planned H2 2024)| No |N/A (7 Planned H2 2024) |

+| West Europe | AZ01 | **AV36**, AV36P, AV52, AV64 | Yes | 7 |

+| West Europe | AZ03 | AV36P, AV64 | Yes |N/A (7 Planned H2 2024|

+After approval, DigiCert completes the certificate creation for your custom domain name. The certificate is valid for one year. If the CNAME record for your custom domain is added or updated to map to your endpoint hostname after verification, then it will be autorenewed before it's expired.

+>[!NOTE]

+> Managed certificate autorenewal requires that your custom domain be directly mapped to your CDN endpoint by a CNAME record.

+> [!NOTE]

+> Requests that include authorization header will not be cached.

+You can enable the .NET Aspire Dashboard on any existing container app environment by using the following commands.

+| Docker Hub | Supports both authenticated and unauthenticated pulls. | Azure CLI |

+| Docker Hub | Supports authenticated pulls only. | Azure portal |

+- **ReadWrite mode** - The mode allows clients to pull and push artifacts (read and write) to the connected registry. Artifacts that are pushed to the connected registry will be synchronized with the cloud registry.

+ The ReadWrite mode is useful when a local development environment is in place. The images are pushed to the local connected registry and from there synchronized to the cloud.

+- **Default mode** - The ***ReadOnly mode*** is now the default mode for connected registries. This change is likely due to security concerns and customer preferences. Starting with CLI version 2.60.0, the default mode is ReadOnly.

+| Docker Hub | Supports both authenticated and unauthenticated pulls. | Azure CLI |

+| Docker Hub | Supports authenticated pulls only. | Azure portal |

+- "Can I use Azure OpenAI with React?"

+## Latest release: July 02, 2024

+- Metrics added

+ - Customer Activity.

+ - Requests.

+(Preview feature list)

+- Support for accumulators

+ - $mergeObjects.

+- Support for aggregation operator

+ - $let.

+- Geospatial query operators

+ - $minDistance.

+ - $maxDistance.

+## Previous releases

+### May 06, 2024

+ - $geoNear aggregation. This can be enabled through Flag - `Geospatial support for vcore "MongoDB for CosmosDB"`

+

+(Preview feature list)

+> [!IMPORTANT]

+> Currently, Azure Pricing Calculator is only showing reservations bigger than one million RU/s. This temporary limitation is being fixed and reservations of any size, starting with 100 RU/s, will soon be available. The Azure Portal isn't affected by this issue.

+* Azure Synapse Link for Azure Cosmos DB is supported for NoSQL, Gremlin and MongoDB APIs. It is not supported for Cassandra or Table APIs.

+* Data Explorer in Synapse Workspaces doesn't list Gremlin graphs in the tree view. But you can still run queries.

+| objectApiName | The Salesforce object name to retrieve data from. | No for source (if "query" in source is specified), Yes for sink |

+| reportId | The ID of the Salesforce report to retrieve data from. It isn't supported in sink. There are [limitations](https://developer.salesforce.com/docs/atlas.en-us.api_analytics.meta/api_analytics/sforce_analytics_rest_api_limits_limitations.htm) when you use reports. | No for source (if "query" in source is specified), not support sink |

+| query | Use the custom query to read data. You can only use [Salesforce Object Query Language (SOQL)](https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/sforce_api_calls_soql.htm) query with limitations. For SOQL limitations, see this [article](https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/queries.htm#SOQL%20Considerations). If query isn't specified, all the data of the Salesforce object specified in "ObjectApiName/reportId" in dataset is retrieved. | No (if "ObjectApiName/reportId" in the dataset is specified) |

+ "query": "SELECT Col_Currency__c, Col_Date__c, Col_Email__c FROM AllDataType__c",

+| July 11 | Upcoming update | [GitHub application permissions update](#github-application-permissions-update) |

+### GitHub application permissions update

+July 11, 2024

+**Estimated date for change**: July 18, 2024

+DevOps security in Defender for Cloud is constantly making updates that require customers with GitHub connectors in Defender for Cloud to update the permissions for the Microsoft Security DevOps application in GitHub.

+As part of this update, the GitHub application will require GitHub Copilot Business read permissions. This permission will be used to help customers better secure their GitHub Copilot deployments. We suggest updating the application as soon as possible.

+Permissions can be granted in two different ways:

+1. In your GitHub organization, navigate to the Microsoft Security DevOps application within **Settings > GitHub Apps** and accept the permissions request.

+1. In an automated email from GitHub Support, select **Review permission request** to accept or reject this change.

+> - [Python](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/eventgrid/azure-eventgrid/samples/basic/sync_samples/sample_publish_eg_events_to_a_domain.py)

+SAP's capability to send events to Azure Event Grid is available through SAP's beta program. Using this program, you can let SAP know about your desire to have your S4/HANA events available on Azure. You can find the SAP's announcement of this new feature [here](https://blogs.sap.com/2022/10/11/sap-event-mesh-event-bridge-to-microsoft-azure-to-go-beta/). Through SAP's Beta program, you'll be provided with the documentation on how to configure your SAP S4/HANA system to flow events to Event Grid.

+> [!NOTE]

+> * This article discusses the issues that may occur with asymmetric routing in a network with multiple links to a destination. It should not be used as a reference for designing a network with asymmetric routing, as Microsoft does not recommend or support this architecture.

+| **Taipei2** | Chunghwa Telecom | 2 | n/a | Supported | |

+| Amsterdam Metro | Amsterdam<br>Amsterdam2 | Equinix AM5<br>Digital Realty AMS8 | 1 | West Europe | &check; | Colt¹<br>Console Connect¹<br>Digital Realty<br>Equinix<br>euNetworks<br><br>Megaport<br> |

+| Singapore Metro | Singapore<br>Singapore2 | Equinix SG1<br>Global Switch Tai Seng | 2 | Southeast Asia | &check; | Console Connect¹<br>Equinix<br>Megaport |

+| Zurich Metro | Zurich<br>Zurich2 | Digital Realty ZUR2<br>Equinix ZH5 | 1 | Switzerland North | &check; | Colt¹<br>Digital Realty |

+> [!NOTE]

+> Requests that include authorization header will not be cached.

+This article lists the keyboard shortcuts that work in the Azure Resource Graph Explorer page of the Azure portal. For a list of global keyboard shortcuts or a list of keyboard shortcuts available for other pages, visit [Keyboard shortcuts in the Azure portal](../../../azure-portal/azure-portal-keyboard-shortcuts.md).

+- [Understanding the Azure Resource Graph query language](../concepts/query-language.md)

+ Title: Troubleshoot common errors for Azure Resource Graph

+You might run into errors when querying Azure resources with Azure Resource Graph. This article describes various errors that might occur and how to resolve them.

+Most errors are the result of an issue while running a query with Azure Resource Graph. When a query fails, the SDK provides details about the failed query. This information indicates the issue so that it can be fixed and a later query succeeds.

+Azure Resource Graph allocates a quota number for each user based on a time window. For example, a user can send at most 15 queries within every 5-second window without being throttled. The quota value is determined by many factors and is subject to change. For more information, see [Throttling in Azure Resource Graph](../overview.md#throttling).

+Customers with access to more than 1,000 subscriptions, including cross-tenant subscriptions with [Azure Lighthouse](../../../lighthouse/overview.md), can't fetch data across all subscriptions in a single call to Azure Resource Graph.

+Azure CLI and PowerShell forward only the first 1,000 subscriptions to Azure Resource Graph. The REST API for Azure Resource Graph accepts a maximum number of subscriptions to perform the query on.

+Batch requests for the query with a subset of subscriptions to stay under the 1,000 subscription limit. The solution is using the **Subscription** parameter in PowerShell.

+Customers querying the Azure Resource Graph REST API get a _500_ (Internal Server Error) response returned.

+The Azure Resource Graph REST API only supports a `Content-Type` of `application/json`. Some REST tools or agents default to `text/plain`, which is unsupported by the REST API.

+Validate that the tool or agent you're using to query Azure Resource Graph has the REST API header `Content-Type` configured for `application/json`.

+Customers that explicitly pass a list of subscriptions with an Azure Resource Graph query get a _403_ (Forbidden) response.

+If the customer doesn't have read permission to all the provided subscriptions, the request is denied because of lack of appropriate security rights.

+Include at least one subscription in the subscription list that the customer running the query has at least read access to. For more information, see [Permissions in Azure Resource Graph](../overview.md#permissions-in-azure-resource-graph).

+If you didn't see your problem or are unable to solve your issue, visit one of the following channels for more support:

+- Get answers from Azure experts through [Azure Forums](https://azure.microsoft.com/support/forums/).

+- Connect with [@AzureSupport](https://twitter.com/azuresupport) - the official Microsoft Azure account for improving customer experience by connecting the Azure community to the right resources: answers, support, and experts.

+- If you need more help, you can file an Azure support incident. Go to the [Azure support site](https://azure.microsoft.com/support/options/) and select **Get Support**.

+* The [URI scheme](../hdinsight-hadoop-linux-information.md#URI-and-scheme) for your clusters primary storage. This would be wasb:// for Azure Storage, `abfs://` for Azure Data Lake Storage Gen2 or adl:// for Azure Data Lake Storage Gen1. If secure transfer is enabled for Azure Storage, the URI would be `wasbs://`. See also, [secure transfer](../../storage/common/storage-require-secure-transfer.md).

+### Visual explains

+To display a visualization of the query plan, select the **Visual Explains** tab below the worksheet.

+The **Visual Explains** view of the query can be helpful in understanding the flow of complex queries.

+* `/mnt/resource` might be filled with orphaned files (as if Resource Manager restart). If necessary, manually clean `/mnt/resource/hadoop/yarn/log` and `/mnt/resource/hadoop/yarn/local`.

+The HDInsight Management SDK can also be used to manage to monitor on your clusters via the Operations Management Suite (OMS).

+HDInsight provides a configuration function called script actions that invoke custom scripts to customize the cluster.

+[!Code-powershell[main](../../powershell_scripts/hdinsight/use-script-action/use-script-action.ps1?range=5-90)]

+[!Code-powershell[main](../../powershell_scripts/hdinsight/use-script-action/use-script-action.ps1?range=105-117)]

+[!Code-powershell[main](../../powershell_scripts/hdinsight/use-script-action/use-script-action.ps1?range=123-140)]

+### Release date: May 16, 2024

+This release note applies to

+HDInsight release will be available to all regions over several days. This release note is applicable for image number **2405081840**. [How to check the image number?](./view-hindsight-cluster-image-version.md)

+HDInsight uses safe deployment practices, which involve gradual region deployment. It might take up to 10 business days for a new release or a new version to be available in all regions.

+**OS versions**

+* HDInsight 5.0: Ubuntu 18.04.5 LTS Linux Kernel 5.4

+* HDInsight 4.0: Ubuntu 18.04.5 LTS Linux Kernel 5.4

+> [!NOTE]

+> Ubuntu 18.04 is supported under [Extended Security Maintenance(ESM)](https://techcommunity.microsoft.com/t5/linux-and-open-source-blog/canonical-ubuntu-18-04-lts-reaching-end-of-standard-support/ba-p/3822623) by the Azure Linux team for [Azure HDInsight July 2023](/azure/hdinsight/hdinsight-release-notes-archive#release-date-july-25-2023), release onwards.

+For workload specific versions, see [HDInsight 5.x component versions](./hdinsight-5x-component-versioning.md).

+## Fixed issues

+* Added API in gateway to get token for Keyvault, as part of the SFI initiative.

+* In the new Log monitor `HDInsightSparkLogs` table, for log type `SparkDriverLog`, some of the fields were missing. For example, `LogLevel & Message`. This release adds the missing fields to schemas and fixed formatting for `SparkDriverLog`.

+* Livy logs not available in Log Analytics monitoring `SparkDriverLog` table, which was due to an issue with Livy log source path and log parsing regex in `SparkLivyLog` configs.

+* Any HDInsight cluster, using ADLS Gen2 as a primary storage account can leverage MSI based access to any of the Azure resources (for example, SQL, Keyvaults) which is used within the application code.

+

+* [Basic and Standard A-series VMs Retirement](https://azure.microsoft.com/updates/basic-and-standard-aseries-vms-on-hdinsight-will-retire-on-31-august-2024/).

+ * On August 31, 2024, we'll retire Basic and Standard A-series VMs. Before that date, you need to migrate your workloads to Av2-series VMs, which provide more memory per vCPU and faster storage on solid-state drives (SSDs).

+ * To avoid service disruptions, [migrate your workloads](https://aka.ms/Av1retirement) from Basic and Standard A-series VMs to Av2-series VMs before August 31, 2024.

+* Retirement Notifications for [HDInsight 4.0](https://azure.microsoft.com/updates/azure-hdinsight-40-will-be-retired-on-31-march-2025-migrate-your-hdinsight-clusters-to-51) and [HDInsight 5.0](https://azure.microsoft.com/updates/hdinsight5retire/).

+

+If you have any more questions, contact [Azure Support](https://ms.portal.azure.com/#view/Microsoft_Azure_Support/HelpAndSupportBlade/~/overview).

+You can always ask us about HDInsight on [Azure HDInsight - Microsoft Q&A](/answers/tags/168/azure-hdinsight).

+We're listening: YouΓÇÖre welcome to add more ideas and other topics here and vote for them - [HDInsight Ideas](https://feedback.azure.com/d365community/search/?q=HDInsight) and follow us for more updates on [AzureHDInsight Community](https://www.linkedin.com/groups/14313521/).

+> [!NOTE]

+> We advise customers to use to latest versions of HDInsight [Images](./view-hindsight-cluster-image-version.md) as they bring in the best of open source updates, Azure updates and security fixes. For more information, see [Best practices](./hdinsight-overview-before-you-start.md).

+**Fixed issues**

+**Fixed issues**

+The only cluster types that have data disks are Kafka and HBase clusters with the Accelerated Writes feature enabled. HDInsight supports P30 and S30 disk sizes in these scenarios. For all other cluster types, HDInsight provides managed disk space with the cluster. From 11/07/2019 onwards, the managed disk size of each node in the newly created cluster is 128 GB. This can't be changed.

+* [General purpose virtual machine sizes: `Dv2` series 1-5](../virtual-machines/dv2-dsv2-series.md)

+* [Memory optimized virtual machine sizes: `Dv2` series 11-15](../virtual-machines/dv2-dsv2-series-memory.md)

+* [General purpose virtual machine sizes: `Av2` series 1-8](../virtual-machines/av2-series.md)

+* **webhcat.log** is the Log4j log to which server writes logs

+ The time for the queued jobs continues to increase because the rate at which new jobs get submitted is higher than the rate at which the old jobs are completed. Once the YARN memory is 100% used, the `joblauncher queue` can no longer borrow capacity from the *default queue*. Therefore, no more new jobs can be accepted into the job launcher queue. This behavior can cause the waiting time to become longer and longer, causing a timeout error that is usually followed by many others.

+ The following image shows the job launcher queue at 714.4% overused. This is acceptable so long as there is still free capacity in the default queue to borrow from. However, when the cluster is fully utilized and the YARN memory is at 100% capacity, new jobs must wait, which eventually causes timeouts.

+ * List all jobs: This is a time-consuming call. This call enumerates the applications from the YARN Resource Manager, and for each completed application, gets the status from the YARN JobHistoryServer. With higher numbers of jobs, this call can time out.

+When you create the cluster, HDInsight service needs to connect to the external metastore and verify your credentials. Configure Azure SQL Database firewall rules to allow Azure services and resources to access the server. Enable this option in the Azure portal by selecting **Set server firewall**. Then select **No** underneath **Deny public network access**, and **Yes** underneath **Allow Azure services and resources to access this server** for Azure SQL Database. For more information, see [Create and manage IP firewall rules](/azure/azure-sql/database/firewall-configure#use-the-azure-portal-to-manage-server-level-ip-firewall-rules)

+Private endpoints for SQL stores are only supported on the clusters created with `outbound` ResourceProviderConnection. To learn more, see this [documentation](./hdinsight-private-link.md).

+The Gateway timeout value is 2 minutes. Queries from Ambari Hive View are submitted to the `/hive2` endpoint through the gateway. Once the query is successfully compiled and accepted, the HiveServer returns a `queryid`. Clients then keep polling for the status of the query. During this process, if the HiveServer doesn't return an HTTP response within 2 minutes, the HDI Gateway throws a 502.3 Gateway timeout error to the caller. The errors could happen when the query is submitted for processing (more likely) and also in the got status call (less likely). Users could see either of them.

+The http handler thread is supposed to be quick: prepare the job and return a `queryid`. However, due to several reasons, all the handler threads could be busy resulting in timeouts for new queries and the got status calls.

+* Ensure that parallel ops are turned on (this enables the HTTP handler threads to run in parallel). To verify the value, launch [Apache Ambari](../hdinsight-hadoop-manage-ambari.md) and navigate to **Hive** > **Configs** > **Advanced** > **Custom hive-site**. The value for `hive.server2.parallel.ops.in.session` should be `true`.

+# Tutorial: Load data, and run queries on an Apache Spark cluster in Azure HDInsight

+ When you run an interactive query in Jupyter, the web browser window or tab caption shows a **(Busy)** status along with the notebook title. You also see a solid circle next to the **PySpark** text in the top-right corner. After the job is completed, it changes to a hollow circle.

+1. From the Ambari UI navigate to **Spark 2** > **Configs** > **Custom spark2-defaults**.

+2. In the next page, select **Spark 2 Thrift Servers**.

+3. You should see the two headnodes on which the Spark 2 Thrift Server is running. Select one of the headnodes.

+4. The next page lists all the services running on that headnode. From the list, select the drop-down button next to Spark 2 Thrift Server, and then select **Stop**.

+ :::image type="content" source="./media/apache-spark-resource-manager/apache-ambari-kill-app1.png " alt-text="Kill App 1." border="true":::

+ :::image type="content" source="./media/apache-spark-resource-manager/apache-ambari-kill-app2.png " alt-text="Kill App 2." border="true":::

+| Visual Studio Code | [Use Spark & Hive Tools for Visual Studio Code](../hdinsight-for-vscode.md) |

+A device template in Azure IoT Central is a blueprint that defines the characteristics and behaviors of a type of device that connects to your application. For example, the device template defines the telemetry that a device sends so that IoT Central can create visualizations that use the correct units and data types. Telemetry that matches the device template definition is referred to as *modeled* data. Telemetry that doesn't match the device template definition is referred to as *unmodeled* data.

+A solution builder adds device templates to an IoT Central application. A device developer writes the device code that implements the behaviors defined in the device template. To learn more about how to create a device template or have one automatically generated, see [Create a device template in your Azure IoT Central application](howto-set-up-template.md). To learn more about the data that a device exchanges with IoT Central, see [Telemetry, property, and command payloads](../../iot/concepts-message-payloads.md).

+ - _Components_. A device model can include components in addition to the root component to describe device capabilities. Each component has an interface that describes the component's capabilities. Component interfaces can be reused in other device models. For example, several phone device models could use the same camera interface.

+Don't use properties to send telemetry from your device. For example, a readonly property such as `temperatureSetting=80` should mean that the device temperature is set to 80, and the device is trying to get to, or stay at, this target temperature.

+## Next step

+* `contents`: lists the properties, telemetry, and commands that make up your device. The capabilities can be defined in multiple interfaces.

+> [!TIP]

+> If you want to autogenerate a device template from unmodeled telemetry, see [Autogenerate a device template](howto-set-up-template.md#autogenerate-a-device-template).

+ Title: Create a device template in Azure IoT Central

+description: How to create a device template. You define the telemetry, state, properties, and commands for your template. Device templates can also be autogenerated.

+# Create a device template in your Azure IoT Central application

+A device template is a blueprint that defines the characteristics and behaviors of a type of device that connects to an Azure IoT Central application. For example, you can create a device template for a sensor that sends telemetry, such as temperature and properties, such as location. To learn more, see [What are device templates?](concepts-device-templates.md).

+This article describes some of the ways to create a device template in IoT Central such as [autogenerating a device template from a telemetry message](#autogenerate-a-device-template) or defining one in the [IoT Central UI](#create-a-device-template-in-your-azure-iot-central-application).

+From a device template, an operator can create and connect real devices.

+- Design the device template in the IoT Central UI.

+## Import a device template

+This section shows you how to import a device template from the list of featured device templates and how to customize it using the IoT Central UI. This example uses the **Onset Hobo MX-100 Temp Sensor** device template from the list of featured device templates:

+## Manage device templates in the UI

+You can create, edit, rename, or delete a template from the template's editor page.

+To publish a device template, go to your device template, and select **Publish**.

+ * IP-based load balancers backend instances must still be virtual machines or virtual machine scale sets. Attaching other PaaS services to the backend pool of an IP based Load Balancer is not supported.

+ * IP-based load balancers doesn't support ACI containers

+ :::image type="content" source="./media/best-practice-performance/metrics-cpu.png" alt-text="Screenshot of CPU metrics by idle usage." lightbox="./media/best-practice-performance/metrics-cpu.png" border="true":::

+

+ > [!TIP]

+ > For a realistic CPU view, add a filter and split the property by `Usage kind=usage_idle`. If this value is lower than 20%, you can apply splitting to obtain usage by all usage kinds.

+ :::image type="content" source="./media/best-practice-performance/metrics-cpu-by-usage.png" alt-text="Screenshot of CPU metrics by usage kind." lightbox="./media/best-practice-performance/metrics-cpu-by-usage.png" border="true":::

+| fargments | Specify the IP fragment packets | Range: 1-8191<br> Example: [1, 5, 1250-1300, 8000-8191] |

+| ports | Port number that needs to be matched | Range: 0-65535<br> Example: [1, 10, 500, 1025-1050, 64000-65535] |

+> - Ports inputs can be `port-number` or `range-of-ports`.<br>

+> - Fragments inputs can be `port-number` or `range-of-ports`.<br>

+| <b> Restore to specific point in time | No | No |

+- Azure Database for PostgreSQL Flexible Server takes snapshot of your database during an upgrade. The snapshot is taken before the upgrade starts. If the upgrade fails, the system will automatically restore your database to its state from the snapshot.

+* [SCRAM authentication](how-to-connect-scram.md) authentication set as default for new PostgreSQL 14+ new server deployments.

+ Title: Cross-region replication for non-paired regions

+description: Learn about cross-region replication for non-paired regions

+# Cross-region replication solutions for non-paired regions

+Some Azure services support cross-region replication to ensure business continuity and protect against data loss. These services make use of another secondary region that uses *cross-region replication*. Both the primary and secondary regions together form a [region pair](./cross-region-replication-azure.md#azure-paired-regions).

+However, there are some [regions that are non-paired](./cross-region-replication-azure.md#regions-with-availability-zones-and-no-region-pair) and so require alternative methods to achieving geo-replication.

+This document lists some of the services and possible solutions that support geo-replication methods without requiring paired regions.

+## Azure App Service

+For App Service, custom backups are stored on a selected storage account. As a result, there's a dependency for cross-region restore on GRS and paired regions. For automatic backup type, you can't backup/restore across regions. As a workaround, you can implement a custom file copy mechanism for the saved data set to manually copy across non-paired regions and different storage accounts.

+## Azure Backup

+To achieve geo-replication in non-paired regions:

+- Use [Azure Site Recovery](/azure/site-recovery/azure-to-azure-enable-global-disaster-recovery).ΓÇ» Azure Site Recovery is the Disaster Recovery service from Azure that provides business continuity and disaster recovery by replicating workloads from the primary location to the secondary location. The secondary location can be a non-paired region if it is supported by Azure Site Recovery. You can have maximum data retention up to 15 days with Azure Site Recovery.

+- Use [Zone-redundant Storage](../backup/backup-overview.md#why-use-azure-backup) to replicate your data in availability zones, guaranteeing data residency and resiliency in the same region.

+## Azure Database for MySQL

+Choose any [Azure Database for MySQL available Azure regions](/azure/mysql/flexible-server/overview#azure-region) to spin up your [read replicas](/azure/mysql/flexible-server/concepts-read-replicas#cross-region-replication).

+## Azure Database for PostgreSQL

+For geo-replication in non-paired regions with Azure Database for PostgreSQL, you can use:

+**Managed service with geo-replication**: Azure PostgreSQL Managed service supports active [geo-replication](/azure/postgresql/flexible-server/concepts-read-replicas) to create a continuously readable secondary replica of your primary server. The readable secondary may be in the same Azure region as the primary or, more commonly, in a different region. This kind of readable secondary replica is also known as *geo-replica*.

+

+You can also utilize any of the two customer-managed data migration methods listed below to replicate the data to a non-paired region.

+- [Copy](/azure/postgresql/migrate/how-to-migrate-using-dump-and-restore?tabs=psql).

+- [Logical Replication & Logical Decoding](/azure/postgresql/flexible-server/concepts-logical).

+

+## Azure Data Factory

+For geo-replication in non-paired regions, Azure Data Factory (ADF) supports Infrastructure-as-code provisioning of ADF pipelines combined withΓÇ»[Source Control for ADF](/azure/data-factory/concepts-data-redundancy#using-source-control-in-azure-data-factory).

+## Azure Event Grid

+For geo-replication of Event Grid topics in non-paired regions, you can implement [client-side failover](/azure/event-grid/custom-disaster-recovery-client-side).

+## Azure IoT Hub

+For geo-replication in non-paired regions, use the [concierge pattern](/azure/iot-hub/iot-hub-ha-dr#achieve-cross-region-ha) for routing to a secondary IoT Hub.

+## Azure Key Vault

+## Azure Kubernetes Service (AKS)

+Azure Backup can provide protection for AKS clusters, including a [cross-region restore (CRR)](/azure/backup/tutorial-restore-aks-backups-across-regions) feature that's currently in preview and only supports Azure Disks. Although the CRR feature relies on GRS paired regions replicas, any dependency on CRR can be avoided if the AKS cluster stores data only in external storage and avoids using "in-cluster" solutions.

+## Azure Monitor Logs

+Log Analytics workspaces in Azure Monitor Logs don't use paired regions. To ensure business continuity and protect against data loss, enable cross-region workspace replication.

+For more information, see [Enhance resilience by replicating your Log Analytics workspace across regions](/azure/azure-monitor/logs/workspace-replication)

+## Azure SQL Database

+For geo-replication in non-paired regions with Azure SQL Database, you can use:

+- [Failover group feature](/azure/azure-sql/database/failover-group-sql-db?view=azuresql&preserve-view=true) that replicates across any combination of Azure regions without any dependency on underlying storage GRS.

+- [Active geo-replication feature](/azure/azure-sql/database/active-geo-replication-overview?view=azuresql&preserve-view=true) to create a continuously synchronized readable secondary database for a primary database. The readable secondary database may be in the same Azure region as the primary or, more commonly, in a different region. This kind of readable secondary database is also known as a *geo-secondary* or *geo-replica*.

+## Azure SQL Managed Instance

+For geo-replication in non-paired regions with Azure SQL Managed Instance, you can use:

+- [Failover group feature](/azure/azure-sql/managed-instance/failover-group-sql-mi?view=azuresql&preserve-view=true) that replicates across any combination of Azure regions without any dependency on underlying storage GRS.

+## Azure Storage

+To achieve geo-replication in non-paired regions:

+- **For Azure Object Storage**:

+ - For blob storage and Azure Data Lake Storage, you can use tools such as [AZCopy](../storage/common/storage-use-azcopy-blobs-copy.md) or [Azure Data Factory](/azure/data-factory/connector-azure-blob-storage?tabs=data-factory.md).

+ - For general-purpose v2 storage accounts and premium block blob accounts, you can use [Azure Storage Object Replication](../storage/blobs/object-replication-overview.md).

+

+ >[!NOTE]

+ >Object replication isn't supported for [Azure Data Lake Storage](../storage/blobs/data-lake-storage-best-practices.md).

+- **For Azure NetApp Files (ANF)**, you can replicate to a set of non-standard pairs besides Azure region pairs. See [Azure NetApp Files (ANF) cross-region replication](/azure/azure-netapp-files/cross-region-replication-introduction).

+- **For Azure Files:**

+ - To copy your files to another storage account in a different region, use tools such as:

+ - [AZCopy](../storage/common/storage-use-azcopy-blobs-copy.md)

+ - [Azure PowerShell](/powershell/module/az.storage/?view=azps-12.0.0&preserve-view=true)

+ - [Azure Data Factory](/azure/data-factory/connector-azure-blob-storage?tabs=data-factory)

+

+ For a sample script, see [Sync between two Azure file shares for Backup and Disaster Recovery](https://github.com/Azure-Samples/azure-files-samples/tree/master/SyncBetweenTwoAzureFileSharesForDR).

+ - To sync between your Azure file share (cloud endpoint), an on-premises Windows file server, and a mounted file share running on a virtual machine in another Azure region (your server endpoint for disaster recovery purposes), use [Azure File Sync](/azure/storage/file-sync/file-sync-introduction).

+ > [!IMPORTANT]

+ > You must disable cloud tiering to ensure that all data is present locally, and provision enough storage on the Azure Virtual Machine to hold the entire dataset. To ensure changes replicate quickly to the secondary region, files should only be accessed and modified on the server endpoint rather than in Azure.

+## Next steps

+- [Azure services and regions that support availability zones](availability-zones-service-support.md)

+- [Disaster recovery guidance by service](disaster-recovery-guidance-overview.md)

+- [Reliability guidance](./reliability-guidance-overview.md)

+- [Business continuity management program in Azure](./business-continuity-management-program.md)

+While Azure regions are designed to offer protection against local disasters with [availability zones](./availability-zones-overview.md), they can also provide protection from regional or large geography disasters with disaster recovery by making use of another secondary region that uses *cross-region replication*. Both the primary and secondary regions together form a [region pair](#azure-paired-regions).

+Some Azure services support cross-region replication to ensure business continuity and protect against data loss. Azure provides several [storage solutions](../storage/common/storage-redundancy.md#redundancy-in-a-secondary-region) that make use of cross-region replication to ensure data availability. For example, [Azure geo-redundant storage](../storage/common/storage-redundancy.md#geo-redundant-storage) (GRS) replicates data to a secondary region automatically. This approach ensures that data is durable even if the primary region isn't recoverable.

+## Shared responsibility

+Not all Azure services automatically replicate data or automatically fall back from a failed region to cross-replicate to another enabled region. In these scenarios, you are responsible for recovery and replication. These examples are illustrations of the *shared responsibility model*. It's a fundamental pillar in your disaster recovery strategy. For more information about the shared responsibility model and to learn about business continuity and disaster recovery in Azure, see [Business continuity management in Azure](business-continuity-management-program.md).

+Many regions have a paired region to support cross-region replication based on proximity and other factors.

+Azure continues to expand globally in regions without a regional pair and achieves high availability by leveraging [availability zones](../reliability/availability-zones-overview.md) and [locally redundant or zone-redundant storage (LRS/ZRS)](../storage/common/storage-redundancy.md#zone-redundant-storage). Regions without a pair will not have [geo-redundant storage (GRS)](../storage/common/storage-redundancy.md#geo-redundant-storage). However, [some services offer alternative options for cross-region replication](./cross-region-replication-azure-no-pair.md).

+Non-paired regions follow [data residency](https://azure.microsoft.com/global-infrastructure/data-residency/#overview) guidelines to allow for the option to keep data resident within the same region. Customers are responsible for data resiliency based on their Recovery Point Objective or Recovery Time Objective (RTO/RPO) needs and may move, copy, or access their data from any location globally. In the rare event that an entire Azure region is unavailable, customers will need to plan for their Cross Region Disaster Recovery per guidance from [Azure services that support high availability](../reliability/availability-zones-service-support.md#azure-services-with-availability-zone-support) and [Azure Resiliency ΓÇô Business Continuity and Disaster Recovery](https://azure.microsoft.com/mediahandler/files/resourcefiles/resilience-in-azure-whitepaper/resiliency-whitepaper-2022.pdf).

+- [Azure cross-region replication for non-paired regions](./cross-region-replication-azure-no-pair.md)

+Microsoft Sentinel is now generally available within the Microsoft unified security operations platform in the Microsoft Defender portal. The Microsoft unified security operations platform brings together the full capabilities of Microsoft Sentinel, Microsoft Defender XDR, and Microsoft Copilot in Microsoft Defender. For more information, see the following resources:

+- [Microsoft Copilot in Microsoft Defender](/defender-xdr/security-copilot-in-microsoft-365-defender)

+## Using Azure Storage Mover and Azure Data Box

+When transitioning on-premises workloads to Azure Storage, reducing downtime and ensuring predictable periods of unavailability is crucial for users and business operations. For the initial bulk migration, you can use [Azure Data Box](https://learn.microsoft.com/azure/databox/) and combine it with Azure Storage Mover for online catch-up.

+Using Azure Data Box conserves significant network bandwidth. However, active workloads on your source storage might undergo changes while the Data Box is in transit to an Azure Data Center. The "online catch-up" phase involves updating your cloud storage with these changes before fully cutting over the workload to use the cloud data. This typically requires minimal bandwidth since most data already resides in Azure, and only the delta needs to be transferred. Azure Storage Mover excels in this task.

+Azure Storage Mover detects differences between your on-premises storage and cloud storage, transferring updates and new files not captured by the Data Box transfer. Additionally, if only a file's metadata (such as permissions) has changed, Azure Storage Mover uploads just the new metadata instead of the entire file content.

+Read more details on how to use Azure Storage Mover with Azure Data Box [here](https://techcommunity.microsoft.com/t5/azure-storage-blog/storage-migration-combine-azure-storage-mover-and-azure-data-box/ba-p/4143354).

+2. In the Synapse workspace, assign the **Contributor** role to your user identity. See [Azure RBAC: Owner role for the workspace](../../synapse-analytics/get-started-add-admin.md#azure-role-based-access-control-owner-role-for-the-workspace).

+2. In Synapse Studio, Make sure that your identity is assigned the role of **Synapse Administrator**. See [Synapse RBAC: Synapse Administrator role for the workspace](../../synapse-analytics/get-started-add-admin.md#synapse-role-based-access-control-synapse-administrator-role-for-the-workspace).

+ [Optimize costs by automatically managing the data lifecycle](lifecycle-management-overview.md)

+> [!NOTE]

+> Accounts left in a **Prepare** migration state more 30 days may have their migrations committed on your behalf. If you need more than 30 days to validate your migration to Azure Resource Manager, you can abort the current migration and restart it when you are ready.

+> [!NOTE]

+> Accounts left in a **Prepare** migration state more 30 days may have their migrations committed on your behalf. If you need more than 30 days to validate your migration to Azure Resource Manager, you can abort the current migration and restart it when you are ready.

+In this tutorial, you'll learn how to add an administrator to your Synapse workspace. This user has full control over the workspace.

+So far in the get started guide, we've focused on activities *you* do in the workspace. Because you created the workspace in STEP 1, you're an administrator of the Synapse workspace. Now, we'll make another user Ryan (`ryan@contoso.com`) an administrator. When we're done, Ryan will be able to do everything you can do in the workspace.

+## Azure role-based access control: Owner role for the workspace

+## Synapse role-based access control: Synapse Administrator role for the workspace

+Assign to `ryan@contoso.com` to the **Synapse Administrator** role on the workspace.

+## Azure role-based access control: Role assignments on the workspace's primary storage account

+You can analyze the data in your workspace default Azure Data Lake Storage (ADLS) Gen2 account or you can link an ADLS Gen2 or Blob storage account to your workspace through "**Manage**" > "**Linked Services**" > "**New**" (The next steps will refer to the primary ADLS Gen2 account).

+1. Open the **PassengerCountStats_parquetformat** folder. Inside, there's a parquet file with a name like `part-00000-2638e00c-0790-496b-a523-578da9a15019-c000.snappy.parquet`.

+1. Attach to the Spark pool named **Spark1**. Run the cell. If you run into an error related to lack of cores, another session could be using this spark pool this spark pool. Cancel all the existing sessions and retry.

+To complete this tutorial's steps, you need to have access to a resource group for which you're assigned the **Owner** role. Create the Synapse workspace in this resource group.

+1. **Region** - Pick the region where you have placed your client applications/services (for example, Azure Virtual Machine, Power BI, Azure Analysis Service) and storages that contain data (for example Azure Data Lake storage, Azure Cosmos DB analytical storage).

+We're going to use a small 100 K row sample dataset of NYC Taxi Cab data for many examples in this getting started guide. We begin by placing it in the primary storage account you created for the workspace.

+* Download the [NYC Taxi - green trip dataset](../open-datasets/dataset-taxi-green.md?tabs=azureml-opendatasets#additional-information) to your computer. Navigate to the [original dataset location](https://www.nyc.gov/site/tlc/about/tlc-trip-record-data.page) from the link, choose a specific year and download the Green taxi trip records in Parquet format.

+* Under the category Azure Data Lake Storage Gen2,** you'll see an item with a name like **myworkspace ( Primary - contosolake )**.

+Once the parquet file is uploaded, it's available through two equivalent URIs:

+ 1. In the Home hub, near the top-right of the page, select **Learn**.

+ 2. In the menu bar at the top, select **?** and then **Knowledge center**.

+Once it's visible, you'll see that the **Knowledge center** allows you to do three things:

+1. In the **Knowledge center**, select **Use samples immediately**.

+1. Select **Use sample**.

+1. select Run. It will run only code you have selected.

+1. Go to the **Knowledge center**, select **Browse gallery**.

+1. Select **Load the New York Taxicab dataset** Data ingestion sample, select **Continue**.

+1. Select **Open Script**.

+1. Select **Run**

+1. This will create several tables for all of the NYC Taxi data and load them using the T-SQL COPY command. If you had created these tables in the previous quick start steps, select and execute only code to CREATE and COPY for tables that don't exist.