+ |Metadata URL | `https://authorization.asignio.com/.well-known/openid-configuration`|

+1. Search for and select **Azure Active Directory**, then select **Users** > **All users**.

+1. Select **Per-user MFA**.

+ :::image type="content" border="true" source="media/howto-mfa-userstates/selectmfa-cropped.png" alt-text="Screenshot of select Multi-Factor Authentication from the Users window in Azure AD.":::

+# How to: Block legacy authentication access to Azure AD with Conditional Access

+- [Back to school ΓÇô Using Boolean algebra correctly in complex filters](https://techcommunity.microsoft.com/t5/intune-customer-success/back-to-school-using-boolean-algebra-correctly-in-complex/ba-p/3422765)

+- [Securing devices as part of the privileged access story](/security/compass/privileged-access-devices)

+ - Allows administrators to select specific built-in Azure AD directory roles used to determine policy assignment. For example, organizations may create a more restrictive policy on users assigned the global administrator role. Other role types aren't supported, including administrative unit-scoped roles and custom roles.

+When organizations both include and exclude a user or group the user or group is excluded from the policy, as an exclude action overrides an include in policy. Exclusions are commonly used for emergency access or break-glass accounts. More information about emergency access accounts and why they're important can be found in the following articles:

+To prevent an administrator from locking themselves out of their directory when creating a policy applied to **All users** and **All apps**, they'll see the following warning.

+If you do find yourself locked out, see [What to do if you're locked out of the Azure portal?](troubleshoot-conditional-access.md#what-to-do-if-youre-locked-out-of-the-azure-portal)

+### External partner access

+Conditional Access policies that target external users may interfere with service provider access, for example granular delegated admin privileges [Introduction to granular delegated admin privileges (GDAP)](/partner-center/gdap-introduction).

+ Title: Microsoft identity platform access tokens

+ Title: Microsoft identity platform accounts & tenant profiles on Android

+ Title: Configure role claim for enterprise Azure AD apps

+ Title: How to integrate with the Microsoft identity platform

+ Title: OAuth 2.0 and OpenID Connect protocols on the Microsoft identity platform

+ Title: Find an API for a custom-developed app

+ Title: "How to use Continuous Access Evaluation enabled APIs in your applications"

+ Title: App sign-in flow with the Microsoft identity platform

+ Title: Application model

+ Title: Microsoft identity platform authentication flows & app scenarios

+ Title: Azure AD authentication & national clouds

+ Title: Authentication vs. authorization

+ Title: Authorization basics

+ Title: Configure identity providers (MSAL iOS/macOS)

+ Title: "Quickstart: Call Microsoft Graph from a console application"

+ Title: Customize browsers & WebViews (MSAL iOS/macOS)

+ Title: Differences between delegated and app permissions

+ Title: "Quickstart: Sign in users and call Microsoft Graph in a desktop app"

+ Title: Support and help options for Microsoft identity platform developers

+ Title: Add app roles and get them from a token

+ Title: Terms of Service and privacy statement for apps

+ Title: Create an Azure app identity (PowerShell)

+ Title: "How to: Build services that are resilient to Azure AD's OpenID Connect metadata refresh"

+ Title: Configure an app's publisher domain

+ Title: Create a self-signed public certificate to authenticate your application

+ Title: "How to: Get a complete list of all apps using Active Directory Authentication Library (ADAL) in your tenant"

+ Title: How to handle SameSite cookie changes in Chrome browser

+ Title: "How to: Change the account types supported by an application"

+ Title: "How to: Remove a registered app from the Microsoft identity platform"

+ Title: "How to: Restore or remove a recently deleted application with the Microsoft identity platform"

+ Title: Restrict Azure AD app to a set of users

+ Title: Microsoft identity platform ID tokens

+ Title: Best practices for the Microsoft identity platform

+ Title: Microsoft identity platform videos

+ Title: Mark an app as publisher verified

+ Title: ADAL to MSAL migration guide (MSAL4j)

+ Title: ADAL to MSAL migration guide for Android

+ Title: ADAL to MSAL migration guide (MSAL iOS/macOS)

+ Title: Python ADAL to MSAL migration guide

+ Title: Migrate JavaScript single-page app from implicit grant to authorization code flow

+ Title: "Quickstart: Add sign in with Microsoft to an Android app"

+ Title: "Quickstart: Add sign in with Microsoft to an iOS or macOS app"

+ Title: "Quickstart: Add sign in with Microsoft to a mobile app"

+ Title: Support single sign-on and app protection policies in mobile apps you develop

+ Title: Acquire and cache tokens with Microsoft Authentication Library (MSAL)

+ Title: Azure AD B2C (MSAL Android)

+ Title: Errors and exceptions (MSAL Android)

+ Title: How to enable cross-app SSO on Android using MSAL

+ Title: Authentication flow support in the Microsoft Authentication Library (MSAL)

+ Title: Client application configuration (MSAL)

+ Title: Public and confidential client apps (MSAL)

+ Title: "Migrate your JavaScript application from ADAL.js to MSAL.js"

+ Title: Android MSAL configuration file

+ Title: MSAL for iOS & macOS differences

+ Title: Get & remove accounts from the token cache (MSAL4j)

+ Title: Avoid page reloads (MSAL.js)

+ Title: Initialize MSAL.js client apps

+ Title: Issues on Internet Explorer & Microsoft Edge (MSAL.js)

+ Title: Pass custom state in authentication requests (MSAL.js)

+ Title: Interactive request prompt behavior (MSAL.js)

+ Title: Single sign-on (MSAL.js)

+ Title: Issues on Internet Explorer (MSAL.js)

+ Title: Use MSAL in a national cloud app

+ Title: AD FS support in MSAL.NET

+ Title: Clear the token cache (MSAL.NET)

+ Title: Client assertions (MSAL.NET)

+ Title: Differences between ADAL.NET and MSAL.NET apps

+ Title: Initialize MSAL.NET client applications

+ Title: Instantiate a confidential client app (MSAL.NET)

+ Title: Instantiate a public client app (MSAL.NET)

+ Title: Provide an HttpClient & proxy (MSAL.NET)

+ Title: Xamarin Android system browser considerations (MSAL.NET)

+ Title: Token cache serialization (MSAL.NET)

+ Title: Use brokers with Xamarin iOS & Android

+ Title: Get consent for several resources (MSAL.NET)

+ Title: UWP considerations (MSAL.NET)

+ Title: Using web browsers (MSAL.NET)

+ Title: Xamarin Android code configuration and troubleshooting (MSAL.NET)

+ Title: Xamarin iOS considerations (MSAL.NET)

+ Title: "Learn about Microsoft Authentication Extensions for Node"

+ Title: "Migrate your Node.js application from ADAL to MSAL"

+ Title: Learn about MSAL

+ Title: Custom token cache serialization (MSAL Python)

+ Title: Scopes for v1.0 apps (MSAL)

+ Title: Tutorial - Web app accesses Microsoft Graph as the user

+ Title: Tutorial - Web app accesses storage by using managed identities

+ Title: Tutorial - Add authentication to a web app on Azure App Service

+ Title: Tutorial - Clean up resources

+ Title: Tutorial - Build a secure web app on Azure App Service

+ Title: Publisher verification overview

+ Title: "Quickstart: Configure an app to access a web API"

+ Title: "Quickstart: Register and expose a web API"

+ Title: "Quickstart: Register an app in the Microsoft identity platform"

+ Title: "Quickstart: Add sign in with Microsoft to an Android app"

+ Title: "Quickstart: Protect an ASP.NET Core web API with the Microsoft identity platform"

+ Title: "Quickstart: ASP.NET Core web app that signs in users and calls Microsoft Graph"

+ Title: "Quickstart: Add sign-in with Microsoft Identity to an ASP.NET Core web app"

+ Title: "Quickstart: Call an ASP.NET web API that is protected by the Microsoft identity platform"

+ Title: "Quickstart: Add sign in with Microsoft to an iOS or macOS app"

+ Title: "Quickstart: Call Microsoft Graph from a Java daemon"

+ Title: "Quickstart: Add sign-in with Microsoft to a Java web app"

+ Title: "Quickstart: Sign in users in JavaScript Angular single-page apps (SPA) with auth code and call Microsoft Graph"

+ Title: "Quickstart: Sign in users in JavaScript React single-page apps (SPA) with auth code and call Microsoft Graph"

+ Title: "Quickstart: Sign in users in JavaScript single-page apps (SPA) with auth code"

+ Title: "Quickstart: Sign in users in JavaScript single-page apps"

+ Title: "Quickstart: Get token & call Microsoft Graph in a console app"

+ Title: "Quickstart: Call Microsoft Graph from a Node.js console app"

+ Title: "Quickstart: Call Microsoft Graph from a Node.js desktop app"

+ Title: "Quickstart: Add authentication to a Node.js web app with MSAL Node"

+ Title: "Quickstart: Add user sign-in to a Node.js web app"

+ Title: "Quickstart: Call Microsoft Graph from a Python daemon"

+ Title: "Quickstart: Add sign-in with Microsoft to a Python web app"

+ Title: "Quickstart: Sign in users and call Microsoft Graph in a Universal Windows Platform app"

+ Title: "Quickstart: Sign in users and call Microsoft Graph in a Windows desktop app"

+ Title: Use redirect URIs with MSAL (iOS/macOS)

+ Title: SAML 2.0 token claims reference

+ Title: How to handle Intelligent Tracking Protection (ITP) in Safari

+ Title: Microsoft identity platform authentication libraries

+ Title: Microsoft identity platform refresh tokens

+ Title: Configure daemon apps that call web APIs

+ Title: Register daemon apps that call web APIs

+ Title: Call a web API from a daemon app

+ Title: Build a daemon app that calls web APIs

+ Title: Move a daemon app that calls web APIs to production

+ Title: Acquire a token to call a web API using device code flow (desktop app)

+ Title: Acquire a token to call a web API using integrated Windows authentication (desktop app)

+ Title: Acquire a token to call a web API interactively (desktop app)

+ Title: Acquire a token to call a web API using username and password (desktop app)

+ Title: Acquire a token to call a web API using web account manager (desktop app)

+ Title: Acquire a token to call a web API (desktop app)

+ Title: Configure desktop apps that call web APIs

+ Title: Register desktop apps that call web APIs

+ Title: Call web APIs from a desktop app

+ Title: Build a desktop app that calls web APIs

+ Title: Move desktop app calling web APIs to production

+ Title: Acquire a token to call a web API (mobile apps)

+ Title: Configure mobile apps that call web APIs

+ Title: Register mobile apps that call web APIs

+ Title: Call a web API from a mobile app

+ Title: Build a mobile app that calls web APIs

+ Title: Prepare mobile app-calling web APIs for production

+ Title: Protected web API app registration

+ Title: Move a protected web API to production

+ Title: Acquire a token to call a web API (single-page apps)

+ Title: Configure single-page app

+ Title: Register single-page applications (SPA)

+ Title: Get a token for a web API that calls web APIs

+ Title: Configure a web API that calls web APIs

+ Title: Register a web API that calls web APIs

+ Title: Web API that calls web APIs

+ Title: Build a web API that calls web APIs

+ Title: Move web API calling web APIs to production

+ Title: Get a token in a web app that calls web APIs

+ Title: Configure a web app that calls web APIs

+ Title: Register a web app that calls web APIs

+ Title: Call a web api from a web app

+ Title: Build a web app that authenticates users and calls web APIs

+ Title: Move to production a web app that calls web APIs

+ Title: Remove accounts from the token cache on sign-out

+ Title: Configure a web app that signs in users

+ Title: Register a web app that signs in users

+ Title: Sign in users from a Web app

+ Title: Move web app that signs in users to production

+ Title: Write a web app that signs in/out users

+ Title: Secure access control using groups in Azure AD

+ Title: Best practices for Azure AD application registration configuration

+ Title: Security tokens

+ Title: Single and multiple account public client apps

+ Title: "Quickstart: Sign in users in single-page apps (SPA) with auth code"

+ Title: Troubleshoot TLS/SSL issues (MSAL iOS/macOS)

+ Title: SSO between ADAL & MSAL apps (iOS/macOS)

+ Title: Support passwordless authentication with FIDO2 keys in apps you develop

+ Title: Validation differences by supported account types

+ Title: Troubleshoot publisher verification

+ Title: Tutorial - Create a Blazor Server app that uses the Microsoft identity platform for authentication

+ Title: "Tutorial: Create an Android app that uses the Microsoft identity platform for authentication"

+ Title: "Tutorial: Create an Angular app that uses the Microsoft identity platform for authentication using auth code flow"

+ Title: "Tutorial: Create an ASP.NET web app that uses the Microsoft identity platform for authentication"

+ Title: "Tutorial: Build a multi-tenant daemon that accesses Microsoft Graph business data"

+ Title: "Tutorial: Create a JavaScript single-page app that uses auth code flow"

+ Title: "Tutorial: Create a JavaScript single-page app that uses the Microsoft identity platform for authentication"

+ Title: "Tutorial: Call Microsoft Graph in a Node.js console app"

+ Title: "Tutorial: Sign in users and call the Microsoft Graph API in an Electron desktop app"

+ Title: "Tutorial: Sign in users in a Node.js & Express web app"

+ Title: "Tutorial: Create a React single-page app that uses auth code flow"

+ Title: "Tutorial: Use shared-device mode with the Microsoft Authentication Library (MSAL) for Android"

+ Title: "Tutorial: Create a Windows Presentation Foundation (WPF) app that uses the Microsoft identity platform for authentication"

+ Title: "Tutorial: Create a Universal Windows Platform (UWP) app that uses the Microsoft identity platform for authentication"

+ Title: Microsoft identity platform UserInfo endpoint

+ Title: Application types for the Microsoft identity platform

+ Title: Sign in with resource owner password credentials grant

+ Title: Microsoft identity platform and OAuth 2.0 authorization code flow

+ Title: OAuth 2.0 client credentials flow on the Microsoft identity platform

+ Title: OAuth 2.0 device code flow

+ Title: OAuth 2.0 implicit grant flow - The Microsoft identity platform

+ Title: Microsoft identity platform and OAuth2.0 On-Behalf-Of flow

+ Title: Microsoft identity platform and OpenID Connect protocol

+ Title: Supported account types

+ Title: "Quickstart: Protect a web API with the Microsoft identity platform"

+You can join devices directly to Azure Active Directory (Azure AD) without the need to join to on-premises Active Directory while keeping your users productive and secure. Azure AD join is enterprise-ready for both at-scale and scoped deployments. Single sign-on (SSO) access to on-premises resources is also available to devices that are Azure AD joined. For more information, see [How SSO to on-premises resources works on Azure AD joined devices](azuread-join-sso.md).

+Azure AD join enables you to transition towards a cloud-first model with Windows. If you're planning to modernize your devices management and reduce device-related IT costs, Azure AD join provides a great foundation towards achieving those goals.

+Azure AD join works in managed and federated environments. We think most organizations will deploy with managed domains. Managed domain scenarios don't require configuring and managing a federation server like Active Directory Federation Services (AD FS).

+On-premises user principal names (UPNs) that are different from Azure AD UPNs aren't supported on Azure AD joined devices. If your users use an on-premises UPN, you should plan to switch to using their primary UPN in Azure AD.

+Device management for Azure AD joined devices is based on a mobile device management (MDM) platform such as Intune, and MDM CSPs. Starting in Windows 10 there's a built-in MDM agent that works with all compatible MDM solutions.

+- **Co-management** - A device is managed by an MDM provider and Microsoft Endpoint Configuration Manager. In this approach, the Microsoft Endpoint Configuration Manager agent is installed on an MDM-managed device to administer certain aspects.

+Through co-management, you can use Microsoft Endpoint Configuration Manager to manage certain aspects of your devices while policies are delivered through your MDM platform. Microsoft Intune enables co-management with Microsoft Endpoint Configuration Manager. For more information on co-management for Windows 10 or newer devices, see [What is co-management?](/configmgr/core/clients/manage/co-management-overview). If you use an MDM product other than Intune, check with your MDM provider on applicable co-management scenarios.

+1. On the **Azure Active Directory page**, in the **Manage** section, select `Mobility (MDM and MAM)`.

+1. Select **Add application**.

+- **Require Multi-Factor Authentication to register or join devices with Azure AD**: This setting allows you to specify whether users are required to provide another authentication factor to join or register their devices to Azure AD. The default is **No**. We recommend that you require multifactor authentication when a device is registered or joined. Before you enable multifactor authentication for this service, you must ensure that multifactor authentication is configured for users that register their devices. For more information on Azure AD Multi-Factor Authentication services, see [getting started with Azure AD Multi-Factor Authentication](../authentication/concept-mfa-howitworks.md). This setting may not work with third-party identity providers.

+> Legacy per-user Enabled/Enforced Azure AD Multi-Factor Authentication is not supported for VM Sign-In. This setting causes Sign-in to fail with ΓÇ£Your credentials do not work.ΓÇ¥ error message.

+

+You can resolve the above issue by removing the per-user MFA setting, by following these steps:

+If your device is under control of Intune or any other MDM solution, retire the device in the management system before disabling or deleting it. For more information see the article [Remove devices by using wipe, retire, or manually unenrolling the device](/mem/intune/remote-actions/devices-wipe).

+Devices managed with Intune can be retired or wiped, for more information see the article [Remove devices by using wipe, retire, or manually unenrolling the device](/mem/intune/remote-actions/devices-wipe).

+### External partner access

+Conditional Access policies that target external users may interfere with service provider access, for example granular delegated admin privileges [Introduction to granular delegated admin privileges (GDAP)](/partner-center/gdap-introduction).

+In the blog post *[Cyber Signals: Defending against cyber threats with the latest research, insights, and trends](https://www.microsoft.com/security/blog/2022/02/03/cyber-signals-defending-against-cyber-threats-with-the-latest-research-insights-and-trends/)* dated February 3, 2022 we shared a thread intelligence brief including the following statistics:

+> * Analyzed ...24 trillion security signals combined with intelligence we track by monitoring more than 40 nation-state groups and over 140 threat groups...

+> * ...From January 2021 through December 2021, weΓÇÖve blocked more than 25.6 billion Azure AD brute force authentication attacks...

+This scale of signals and attacks requires some level of automation to be able to keep up.

+More detail on these and other risks including how or when they're calculated can be found in the article, [What is risk](concept-identity-protection-risks.md).

+Identity Protection categorizes risk into tiers: low, medium, and high.

+While Microsoft doesn't provide specific details about how risk is calculated, we'll say that each level brings higher confidence that the user or sign-in is compromised. For example, something like one instance of unfamiliar sign-in properties for a user might not be as threatening as leaked credentials for another user.

+Additionally, organizations can choose to store data for longer periods by changing diagnostic settings in Azure AD to send RiskyUsers and UserRiskEvents data to a Log Analytics workspace, archive data to a storage account, stream data to Event Hubs, or send data to a partner solution. Detailed information about how to do so can be found in the article, [How To: Export risk data](howto-export-risk-data.md).

+Currently, the security operator role can't access the Risky sign-ins report.

+| Capability | Details | Azure AD Free / Microsoft 365 Apps | Azure AD Premium P1 | Azure AD Premium P2 |

+| Risk policies | User risk policy (via Identity Protection) | No | No | Yes |

+| Risk policies | Sign-in risk policy (via Identity Protection or Conditional Access) | No | No | Yes |

+| Security reports | Overview | No | No | Yes |

+| Security reports | Risky users | Limited Information. Only users with medium and high risk are shown. No details drawer or risk history. | Limited Information. Only users with medium and high risk are shown. No details drawer or risk history. | Full access|

+| Security reports | Risky sign-ins | Limited Information. No risk detail or risk level is shown. | Limited Information. No risk detail or risk level is shown. | Full access |

+| Security reports | Risk detections | No | Limited Information. No details drawer.| Full access |

+| Notifications | Users at risk detected alerts | No | No | Yes |

+| Notifications | Weekly digest | No | No | Yes |

+| MFA registration policy | | No | No | Yes |

+## On-demand bursting

+On-demand disk bursting model allows disk bursts whenever its needs exceed its current capacity. This model incurs additional charges anytime the disk bursts. On-demand bursting is only available for premium SSDs larger than 512 GiB. For more information on premium SSDs provisioned IOPS and throughput per disk, see [Premium SSD size][az-premium-ssd]. Alternatively, credit-based bursting is where the disk will burst only if it has burst credits accumulated in its credit bucket. Credit-based bursting does not incur additional charges when the disk bursts. Credit-based bursting is only available for premium SSDs 512 GiB and smaller, and standard SSDs 1024 GiB and smaller. For more details on on-demand bursting, see [On-demand bursting][az-on-demand-bursting].

+> [!IMPORTANT]

+> The default `managed-csi-premium` storage class has on-demand bursting disabled and uses credit-based bursting. Any premium SSD dynamically created by a persistent volume claim based on the default `managed-csi-premium` storage class also has on-demand bursting disabled.

+To create a premium SSD persistent volume with [on-demand bursting][az-on-demand-bursting] enabled you can create a new storage class with the [enableBursting][csi-driver-parameters] parameter set to `true` as shown in the following YAML template. For more details on enabling on-demand bursting, see [On-demand bursting][az-on-demand-bursting]. For more details on building your own storage class with on-demand bursting enabled, see [Create a Burstable Managed CSI Premium Storage Class][create-burstable-storage-class].

+```yaml

+apiVersion: storage.k8s.io/v1

+kind: StorageClass

+metadata:

+ name: burstable-managed-csi-premium

+provisioner: disk.csi.azure.com

+parameters:

+ skuname: Premium_LRS

+ enableBursting: "true"

+reclaimPolicy: Delete

+volumeBindingMode: WaitForFirstConsumer

+allowVolumeExpansion: true

+```

+[csi-driver-parameters]: https://github.com/kubernetes-sigs/azuredisk-csi-driver/blob/master/docs/driver-parameters.md

+[create-burstable-storage-class]: https://github.com/Azure-Samples/burstable-managed-csi-premium

+[az-on-demand-bursting]: ../virtual-machines/disk-bursting.md#on-demand-bursting

+[enable-on-demand-bursting]: ../virtual-machines/disks-enable-bursting.md?tabs=azure-cli

+[az-premium-ssd]: ../virtual-machines/disks-types.md#premium-ssds

+[aks-quickstart-powershell]: /azure/aks/learn/quick-kubernetes-deploy-powershell

+kubectl get ValidatingWebhookConfiguration aks-osm-validator-mesh-osm -o json | jq '.webhooks[0].clientConfig.service'

+[aks-quickstart-powershell]: /azure/aks/learn/quick-kubernetes-deploy-powershell

+description: Learn how to configure and use an external Redis-compatible cache in Azure API Management. Using an external cache gives you more control and flexibility than the built-in cache.

+In addition to utilizing the built-in cache, Azure API Management allows for caching responses in an external Redis-compatible cache, such as Azure Cache for Redis.

+* Cache more data than your API Management tier allows

+* Enable caching in the [API Management self-hosted gateway](self-hosted-gateway-overview.md)

+This section explains how to create an Azure Cache for Redis in Azure. If you already have an Azure Cache for Redis, or another Redis-compatible cache within or outside of Azure, you can <a href="#add-external-cache">skip</a> to the next section.

+For a self-hosted gateway, caching requires an external cache. For caching to be effective, a self-hosted gateway and the cache it relies on must be located close to each other to minimize lookup and store latencies. Deploying a Redis cache into the same Kubernetes cluster or in a separate cluster nearby are the best options. Learn how to [deploy Redis cache to a Kubernetes cluster](https://github.com/kubernetes/examples/tree/master/guestbook).

+Follow the steps below to add an external Redis-compatible cache in Azure API Management. You can limit the cache to a specific gateway in your API Management instance.

+### Use from setting

+The **Use from** setting in the configuration specifies the location of your API Management instance that will use the cache. Select one of the following:

+* The Azure region where the API Management instance is hosted (or one of the configured locations, if you have a [multi-region](api-management-howto-deploy-multi-region.md) deployment)

+* A self-hosted gateway location

+* **Default**, to configure the cache as the default for all gateway locations in the API Management instance

+ A cache used for **Default** will be overridden by a cache used for a specific matching region or location.

+ For example, consider an API Management instance that's hosted in the East US, Southeast Asia, and West Europe regions. There are two caches configured, one for **Default** and one for **Southeast Asia**. In this example, API Management in **Southeast Asia** will use its own cache, while the other two regions will use the **Default** cache entry.

+> You can configure the same external cache for more than one API Management instance. The API Management instances can be in the same or different regions. When sharing the cache for more than one instance, you must select **Default** in the **Use from** setting.

+3. Select the **+ Add** button.

+5. Select **Default** or specify the desired region in the [**Use from**](#use-from-setting) dropdown field.

+6. Select **Save**.

+### Add a Redis-compatible cache hosted outside of the current Azure subscription or Azure in general

+3. Select the **+ Add** button.

+5. Select **Default** or specify the desired region in the [**Use from**](#use-from-setting) dropdown field.

+6. Provide your Azure Cache for Redis (or Redis-compatible cache) connection string in the **Connection string** field.

+7. Select **Save**.

+3. Select the **+ Add** button.

+5. Specify the desired self-hosted gateway location or **Default** in the [**Use from**](#use-from-setting) dropdown field.

+7. Select **Save**.

+After adding a Redis-compatible cache, configure [caching policies](api-management-caching-policies.md) to enable response caching, or caching of values by key, in the external cache.

+For a detailed example, see [Add caching to improve performance in Azure API Management](api-management-howto-cache.md).

+* To cache items by key using policy expressions, see [Custom caching in Azure API Management](api-management-sample-cache-by-key.md).

+Azure API Management service has built-in support for [HTTP response caching](api-management-howto-cache.md) using the resource URL as the key. The key can be modified by request headers using the `vary-by` properties. This is useful for caching entire HTTP responses (also known as representations), but sometimes it's useful to just cache a portion of a representation. The [cache-lookup-value](./api-management-caching-policies.md#GetFromCacheByKey) and [cache-store-value](./api-management-caching-policies.md#StoreToCacheByKey) policies provide the ability to store and retrieve arbitrary pieces of data from within policy definitions. This ability also adds value to the [send-request](./api-management-advanced-policies.md#SendRequest) policy because you can cache responses from external services.

+API Management service uses a shared per-tenant internal data cache so that, as you scale up to multiple units, you still get access to the same cached data. However, when working with a multi-region deployment there are independent caches within each of the regions. It's important to not treat the cache as a data store, where it's the only source of some piece of information. If you did, and later decided to take advantage of the multi-region deployment, then customers with users that travel may lose access to that cached data.

+> [!NOTE]

+> The internal cache is not available in the **Consumption** tier of Azure API Management. You can [use an external Azure Cache for Redis](api-management-howto-cache-external.md) instead. An external cache allows for greater cache control and flexibility for API Management instances in all tiers.

+There are certain cases where responses being returned contain some portion of data that is expensive to determine and yet remains fresh for a reasonable amount of time. As an example, consider a service built by an airline that provides information relating flight reservations, flight status, and so on. If the user is a member of the airlines points program, they would also have information relating to their current status and accumulated mileage. This user-related information might be stored in a different system, but it may be desirable to include it in responses returned about flight status and reservations. This can be done using a process called fragment caching. The primary representation can be returned from the origin server using some kind of token to indicate where the user-related information is to be inserted.

+To determine the appropriate user information to include, API Management needs to identify who the end user is. This mechanism is implementation-dependent. The following example uses the `Subject` claim of a `JWT` token.

+API Management stores the value in the cache using the same key that API Management originally attempted to retrieve it with. The duration that API Management chooses to store the value should be based on how often the information changes and how tolerant users are to out-of-date information.

+It is important to realize that retrieving from the cache is still an out-of-process network request and potentially can add tens of milliseconds to the request. The benefits come when determining the user profile information takes longer than that due to needing to do database queries or aggregate information from multiple back-ends.

+You can choose to include the quotation marks as part of the token so that even when the replacement doesnΓÇÖt occur, the response is still a valid JSON.

+Once you combine these steps, the end result is a policy that looks like the following one.

+This caching approach is primarily used in websites where HTML is composed on the server side so that it can be rendered as a single page. It can also be useful in APIs where clients can't do client-side HTTP caching or it's desirable not to put that responsibility on the client.

+It's common practice for multiple different implementation versions of an API to be supported at any one time. For example, to support different environments (dev, test, production, etc.) or to support older versions of the API to give time for API consumers to migrate to newer versions.

+One approach to handling this, instead of requiring client developers to change the URLs from `/v1/customers` to `/v2/customers` is to store in the consumerΓÇÖs profile data which version of the API they currently wish to use and call the appropriate backend URL. To determine the correct backend URL to call for a particular client, it's necessary to query some configuration data. By caching this configuration data, API Management can minimize the performance penalty of doing this lookup.

+Then, API Management checks to see if it didn't find it in the cache.

+ | **GraphQL API endpoint** | The base URL with your GraphQL API endpoint name. <br /> For example: *`https://example.com/your-GraphQL-name`*. You can also use a common "Star Wars" GraphQL endpoint such as `https://swapi-graphql.azure-api.net/graphql` as a demo. |

+ Install-Package Azure.Identity

+Install Visual Studio 2022 with the [Azure development workload](/visualstudio/install/install-visual-studio#step-4choose-workloads).

+1. In the **Settings** section, choose **Show all settings**.

+Use Visual Studio 2022 to create a .NET Core console app that uses the WebJobs SDK to respond to Azure Storage Queue messages, run the project locally, and finally deploy it to Azure.

+* Visual Studio 2022 with the **Azure development** workload. [Install Visual Studio 2022](/visualstudio/install/).

+In this section, you start by creating a project in Visual Studio 2022. Next, you'll add tools for Azure development, code publishing, and functions that listen for triggers and call functions. Last, you'll set up console logging that disables a legacy monitoring tool and enables a console provider with default filtering.

+>The procedures in this article are verified for creating a .NET Core console app that runs on .NET 6.0.

+1. Choose your **Target framework** and select **Create**. This tutorial has been verified using .NET 6.0.

+1. Get the latest stable 4.x version of the [Microsoft.Azure.WebJobs.Extensions NuGet package](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions/).

+4. In the following command, replace `<4_X_VERSION>` with the current version number you found in step 1.

+ Install-Package Microsoft.Azure.WebJobs.Extensions -version <4_X_VERSION>

+1. Select the **Program.cs** tab, remove the existing contents, and add these `using` statements:

+1. Also under **Program.cs**, add the following code:

+ namespace WebJobsSDKSample

+ class Program

+ {

+ static async Task Main()

+ {

+ var builder = new HostBuilder();

+ builder.ConfigureWebJobs(b =>

+ var host = builder.Build();

+ using (host)

+ {

+ await host.RunAsync();

+ }

+ }

+2. In the following command, replace `<6_X_VERSION>` with the current version number you found in step 1. Each type of NuGet Package has a unique version number.

+ Install-Package Microsoft.Extensions.Logging.Console -version <6_X_VERSION>

+1. Get the latest stable version of the [Microsoft.Azure.WebJobs.Extensions.Storage](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Storage) NuGet package, version 5.x.

+1. In the following command, replace `<5_X_VERSION>` with the current version number you found in step 1. Each type of NuGet Package has a unique version number.

+ Install-Package Microsoft.Azure.WebJobs.Extensions.Storage -Version <5_X_VERSION>

+1. Continuing in **Program.cs**, in the `ConfigureWebJobs` extension method, add the `AddAzureStorageQueues` method on the [`HostBuilder`](/dotnet/api/microsoft.extensions.hosting.hostbuilder) instance (before the `Build` command) to initialize the Storage extension. At this point, the `ConfigureWebJobs` method looks like this:

+ b.AddAzureStorageQueues();

+ b.AddAzureStorageQueues();

+1. In the Azure portal, navigate to your storage account and select the **Queues** tab (1). Select **+ Queue** (2) and enter **queue** as the Queue name (3). Then, select **OK** (4).

+ 

+2. Click the new queue and select **Add message**.

+3. In the **Add Message** dialog, enter *Hello World!* as the **Message text**, and then select **OK**. There is now a message in the queue.

+4. Press **Ctrl+F5** to run the project.

+5. Go back to the **Queue** window and refresh it. The message is gone, since it has been processed by your function running locally.

+6. Close the console window.

+During deployment, you create an app service instance where you'll run your functions. When you publish a .NET console app to App Service in Azure, it automatically runs as a WebJob. To learn more about publishing, see [Develop and deploy WebJobs using Visual Studio](webjobs-dotnet-deploy-vs.md).

+1. In the **Publish** page under **Hosting**, select the edit button and change the **WebJob Type** to `Continuous` and select **Save**. This makes sure that the WebJob is running when messages are added to the queue. Triggered WebJobs are typically used only for manual webhooks.

+ 

+2. Select the **Publish** button at the top right corner of the **Publish** page. When the operation completes, your WebJob is running on Azure.

+1. As before, use the Azure portal to create a queue message like you did [earlier](#test-locally), except enter *Hello App Insights!* as the message text.

+### Add bindings

+Input bindings simplify code that reads data. For this example, the queue message is the name of a blob, which you'll use to find and read a blob in Azure Storage. You will then use output bindings to write a copy of the file to the same container.

+1. In **Functions.cs**, add a `using`:

+ ```cs

+ using System.IO;

+ ```

+2. Replace the `ProcessQueueMessage` method with the following code:

+ [Blob("container/copy-{queueTrigger}", FileAccess.Write)] Stream outputBlob,

+ myBlob.CopyTo(outputBlob);

+

+ This code uses output bindings to create a copy of the file identified by the queue message. The file copy is prefixed with *copy-*.

+3. In **Program.cs**, in the `ConfigureWebJobs` extension method, add the `AddAzureStorageBlobs` method on the [`HostBuilder`](/dotnet/api/microsoft.extensions.hosting.hostbuilder) instance (before the `Build` command) to initialize the Storage extension. At this point, the `ConfigureWebJobs` method looks like this:

+ ```cs

+ builder.ConfigureWebJobs(b =>

+ {

+ b.AddAzureStorageCoreServices();

+ b.AddAzureStorageQueues();

+ b.AddAzureStorageBlobs();

+ });

+ ```

+4. Create a blob container in your storage account.

+ a. In the Azure portal, navigate to the **Containers** tab below **Data storage** and select **+ Container**

+ b. In the **New container** dialog, enter *container* as the container name, and then select **Create**.

+5. Upload the *Program.cs* file to the blob container. (This file is used here as an example; you could upload any text file and create a queue message with the file's name.)

+ a. Select the new container you created

+ b. Select the **Upload** button.

+1. Create a queue message in the queue you created earlier, with *Program.cs* as the text of the message.

+ 

+1. A copy of the file, *copy-Program.cs*, will appear in the blob container.

+In this article, you learn how to use Visual Studio 2022 to locally create and test a "hello world" durable function. This function orchestrates and chains-together calls to other functions. You then publish the function code to Azure. These tools are available as part of the Azure development workload in Visual Studio 2022.

+* Install [Visual Studio 2022](https://visualstudio.microsoft.com/vs/). Make sure that the **Azure development** workload is also installed. Visual Studio 2019 also supports Durable Functions development, but the UI and steps differ.

+1. Under **Additional information**, use the settings specified in the table that follows the image.

+ | **Functions worker** | .NET 6 | Creates a function project that supports .NET 6 and the Azure Functions Runtime 4.0. For more information, see [How to target Azure Functions runtime version](../functions-versions.md). |

+ | **Function** | Empty | Creates an empty function app. |

+1. Select the **Durable Functions Orchestration** template and then select **Add**.

+ "name": "Durable",

+| **connectionStringSetting** | Required. The name of an app setting that contains the connection string for the database against which the query or stored procedure is being executed. This value isn't the actual connection string and must instead resolve to an environment variable name. Optional keywords in the connection string value are [available to refine SQL bindings connectivity](./functions-bindings-azure-sql.md#sql-connection-string). |

+The attribute's constructor takes the SQL command text, the command type, parameters, and the connection string setting name. The command can be a Transact-SQL (T-SQL) query with the command type `System.Data.CommandType.Text` or stored procedure name with the command type `System.Data.CommandType.StoredProcedure`. The connection string setting name corresponds to the application setting (in `local.settings.json` for local development) that contains the [connection string](/dotnet/api/microsoft.data.sqlclient.sqlconnection.connectionstring?view=sqlclient-dotnet-core-3.1&preserve-view=true#Microsoft_Data_SqlClient_SqlConnection_ConnectionString) to the Azure SQL or SQL Server instance.

+| **connectionStringSetting** | Required. The name of an app setting that contains the connection string for the database to which data is being written. This isn't the actual connection string and must instead resolve to an environment variable. Optional keywords in the connection string value are [available to refine SQL bindings connectivity](./functions-bindings-azure-sql.md#sql-connection-string). |

+The `CommandText` property is the name of the table where the data is to be stored. The connection string setting name corresponds to the application setting that contains the [connection string](/dotnet/api/microsoft.data.sqlclient.sqlconnection.connectionstring?view=sqlclient-dotnet-core-3.1&preserve-view=true#Microsoft_Data_SqlClient_SqlConnection_ConnectionString) to the Azure SQL or SQL Server instance.

+## SQL connection string

+Azure SQL bindings for Azure Functions have a required property for connection string on both [input](./functions-bindings-azure-sql-input.md) and [output](./functions-bindings-azure-sql-output.md) bindings. SQL bindings passes the connection string to the Microsoft.Data.SqlClient library and supports the connection string as defined in the [SqlClient ConnectionString documentation](/dotnet/api/microsoft.data.sqlclient.sqlconnection.connectionstring?view=sqlclient-dotnet-core-3.1&preserve-view=true). Notable keywords include:

+- `Authentication` allows a function to connect to Azure SQL with Azure Active Directory, including [Active Directory Managed Identity](./functions-identity-access-azure-sql-with-managed-identity.md)

+- `Command Timeout` allows a function to wait for specified amount of time in seconds before terminating a query (default 30 seconds)

+- `ConnectRetryCount` allows a function to automatically make additional reconnection attempts, especially applicable to Azure SQL Database serverless tier (default 1)

+1. For the **Additional information** settings, use the values in the following table:

+ | **Functions worker** | **.NET 6** or **.NET 6 Isolated** | When you choose **.NET 6**, you create a project that runs in-process with version 4.x of the Azure Functions runtime. When you choose **.NET 6 Isolated**, you create a project that runs in a separate worker process. Azure Functions 1.x supports the .NET Framework. For more information, see [Azure Functions runtime versions overview](./functions-versions.md). |

+ | **Function** | **HTTP trigger** | This value creates a function triggered by an HTTP request. |

+ | **Use Azurite for runtime storage account (AzureWebJobsStorage)** | Enable | Because a function app in Azure requires a storage account, one is assigned or created when you publish your project to Azure. An HTTP trigger doesn't use an Azure Storage account connection string; all other trigger types require a valid Azure Storage account connection string. When you select this option, the Azurite emulator is used. |

+2. Select **Create** to create the function project and HTTP trigger function.

+description: Learn how to develop and test Azure Functions by using Azure Functions Tools for Visual Studio 2022.

+Unless otherwise noted, procedures and examples shown are for Visual Studio 2022.

+- Azure Functions Tools. To add Azure Function Tools, include the **Azure development** workload in your Visual Studio installation. If you are using Visual Studio 2017, you may need to [follow some additional installation steps](#azure-functions-tools-with-visual-studio-2017).

+ >Because the local.settings.json file can contain secrets, you must exclude it from your project source control. Make sure the **Copy to Output Directory** setting for this file is set to **Copy if newer**.

+1. In the Azure portal, navigate to your storage account.

+2. In the **Access keys** tab, below **Security + networking**, copy the **Connection string** of **key1**.

+3. Choose your trigger, set the binding properties, and then select **Add**. The following example shows the settings for creating a Queue storage trigger function.

+ You will then be prompted to choose between two Azure storage emulators or referencing a provisioned Azure storage account.

+ This trigger example uses a connection string with a key named `QueueStorage`. This key, stored in the [local.settings.json file](functions-develop-local.md#local-settings-file), either references the Azure storage emulators or an Azure storage account.

+The easiest way to upload the required settings to your function app in Azure is to expand the three dots next to the **Hosting** section and select the **Manage Azure App Service settings** link that appears after you successfully publish your project.

+4. [Create an xUnit Test app](https://xunit.net/docs/getting-started/netcore/cmdline) in the solution and name it **Functions.Tests**. Remove the default test files.

+ new MyTimerTrigger().Run(null, logger);

+- **Timer_should_log_message**: This test creates an instance of `ListLogger` and passes it to a timer function. Once the function is run, then the log is checked to make sure the expected message is present.

+To run the tests, navigate to the **Test Explorer** and select **Run All Tests in View**.

+## Azure Functions tools with Visual Studio 2017

+Azure Functions Tools is available in the Azure development workload starting with Visual Studio 2017. In Visual Studio 2017, the Azure development workload installs Azure Functions Tools as a separate extension. In Visual Studio 2019 and later, the Azure Functions tools extension is updated as part of Visual Studio.

+When you update your Visual Studio 2017 installation, make sure that you're using the [most recent version](#check-your-tools-version) of the Azure Functions Tools. The following sections show you how to check and (if needed) update your Azure Functions Tools extension in Visual Studio 2017.

+### <a name="check-your-tools-version"></a>Check your tools version in Visual Studio 2017

+1. From the **Tools** menu, choose **Extensions and Updates**. Expand **Installed** > **Tools**, and then choose **Azure Functions and Web Jobs Tools**.

+ 

+1. Note the installed **Version** and compare this version with the latest version listed in the [release notes](https://github.com/Azure/Azure-Functions/blob/master/VS-AzureTools-ReleaseNotes.md).

+1. If your version is older, update your tools in Visual Studio as shown in the following section.

+### Update your tools in Visual Studio 2017

+1. In the **Extensions and Updates** dialog, expand **Updates** > **Visual Studio Marketplace**, choose **Azure Functions and Web Jobs Tools** and select **Update**.

+ 

+1. After the tools update is downloaded, select **Close**, and then close Visual Studio to trigger the tools update with VSIX Installer.

+1. In VSIX Installer, choose **Modify** to update the tools.

+1. After the update is complete, choose **Close**, and then restart Visual Studio.

+1. Open your local function app project in Visual Studio 2022.

+1. In the **System.Data.SqlClient** page, select version `4.8.3` and then click **Install**.

+1. In the **New Azure function** dialog box, choose **Timer trigger** and then **Add**. This dialog creates a code file for the timer triggered function.

+If you plan to [publish this function](functions-develop-vs.md#publish-to-azure), remember to change the `TimerTrigger` attribute to a more reasonable [cron schedule](functions-bindings-timer.md#ncrontab-expressions) than every 15 seconds. Also, you need to ensure that the Function Apps instance has network access to the Azure SQL Database instance by granting access to Azure IP addresses.

+> The OpenAPI and API Management integration featured in this article is currently in preview. This method for exposing a serverless API is only supported for [in-process](functions-dotnet-class-library.md) C# class library functions. [Isolated process](dotnet-isolated-process-guide.md) C# class library functions and all other language runtimes should instead [use Azure API Management integration from the portal](functions-openapi-definition.md).

+ | **Functions worker** | **.NET 6** | This value creates a function project that runs in-process on version 4.x of the Azure Functions runtime. OpenAPI file generation is only supported for versions 3.x and 4.x of the Functions runtime, and isolated process isn't supported. |

+ | **Use Azurite for runtime storage account (AzureWebJobsStorage)** | **Selected** | You can use the emulator for local development of HTTP trigger functions. Because a function app in Azure requires a storage account, one is assigned or created when you publish your project to Azure. |

+1. Under **APIs**, select **OpenAPI Document on Azure Functions** > **POST Run**, then under **Inbound processing** select **Add policy**.

+1. Below **Inbound processing**, in **Set query parameters**, type `code` for **Name**, select **+Value**, paste in the copied function key, and select **Save**. API Management includes the function key when it passes calls through to the function endpoint.

+ :::image type="content" source="media/openapi-apim-integrate-vs/inbound-processing-rule.png" alt-text="Provide Function credentials to the API inbound processing rule":::

+1. 1. Under **APIs**, select **OpenAPI Document on Azure Functions**, select the ellipses (**...**), and select **Export**.

+You've used Visual Studio 2022 to create a function that is self-documenting because of the [OpenAPI Extension](https://github.com/Azure/azure-functions-openapi-extension) and integrated with API Management. You can now refine the definition in API Management in the portal. You can also [learn more about API Management](../api-management/api-management-key-concepts.md).

+description: This quickstart shows you how to deploy a STIG-compliant Linux VM (Preview) from the Azure portal or Azure Government portal.

+description: This quickstart shows you how to deploy a STIG-compliant Windows VM (Preview) from the Azure portal or Azure Government portal.

+> [!NOTE]

+> For Dependency Agent, please additionally check for supported kernel versions. See "Dependency agent Linux kernel support" table below for details

+| Ubuntu 20.04 LTS | X | X | X | X ⁴ |

+⁴ Not all kernel versions are supported, check supported kernel versions below.

+|Azure CLI | [az monitor alert](/cli/monitor/alert) | [az monitor metrics alert](/cli/azure/monitor/metrics/alert) |

+- [Understand how the migration tool works](alerts-understand-migration.md)

+Install the OpenCensus logging integration:

+```console

+python -m pip install opencensus-ext-logging

+```

+1. The exporter sends metric data to Azure Monitor at a fixed interval. The default is every 15 seconds. To modify the export interval, pass in `export_interval` as a parameter in seconds to `new_metrics_exporter()`. We're tracking a single metric, so this metric data, with whatever value and time stamp it contains, is sent every interval. The value is cumulative, can only increase and resets to 0 on restart. You can find the data under `customMetrics`, but `customMetrics` properties valueCount, valueSum, valueMin, valueMax, and valueStdDev are not effectively used.

+- Support operations at scale with [automated actions](alerts/alerts-action-rules.md).

+ Title: Profile ASP.NET Core Azure Linux web apps with Application Insights Profiler | Microsoft Docs

+description: A conceptual overview and step-by-step tutorial on how to use Application Insights Profiler.

+ms.devlang: csharp

+# Profile ASP.NET Core Azure Linux web apps with Application Insights Profiler

+This feature is currently in preview.

+Find out how much time is spent in each method of your live web application when using [Application Insights](../app/app-insights-overview.md). Application Insights Profiler is now available for ASP.NET Core web apps that are hosted in Linux on Azure App Service. This guide provides step-by-step instructions on how the Profiler traces can be collected for ASP.NET Core Linux web apps.

+After you complete this walkthrough, your app can collect Profiler traces like the traces that are shown in the image. In this example, the Profiler trace indicates that a particular web request is slow because of time spent waiting. The *hot path* in the code that's slowing the app is marked by a flame icon. The **About** method in the **HomeController** section is slowing the web app because the method is calling the **Thread.Sleep** function.

+

+## Prerequisites

+The following instructions apply to all Windows, Linux, and Mac development environments:

+* Install the [.NET Core SDK 3.1 or later](https://dotnet.microsoft.com/download/dotnet).

+* Install Git by following the instructions at [Getting Started - Installing Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).

+## Set up the project locally

+1. Open a Command Prompt window on your machine. The following instructions work for all Windows, Linux, and Mac development environments.

+1. Create an ASP.NET Core MVC web application:

+ ```console

+ dotnet new mvc -n LinuxProfilerTest

+ ```

+1. Change the working directory to the root folder for the project.

+1. Add the NuGet package to collect the Profiler traces:

+ ```console

+ dotnet add package Microsoft.ApplicationInsights.Profiler.AspNetCore

+ ```

+1. Enable Application Insights and Profiler in Startup.cs:

+ ```csharp

+ public void ConfigureServices(IServiceCollection services)

+ {

+ services.AddApplicationInsightsTelemetry(); // Add this line of code to enable Application Insights.

+ services.AddServiceProfiler(); // Add this line of code to Enable Profiler

+ services.AddControllersWithViews();

+ }

+ ```

+1. Add a line of code in the **HomeController.cs** section to randomly delay a few seconds:

+ ```csharp

+ using System.Threading;

+ ...

+ public IActionResult About()

+ {

+ Random r = new Random();

+ int delay = r.Next(5000, 10000);

+ Thread.Sleep(delay);

+ return View();

+ }

+ ```

+1. Save and commit your changes to the local repository:

+ ```console

+ git init

+ git add .

+ git commit -m "first commit"

+ ```

+## Create the Linux web app to host your project

+1. Create the web app environment by using App Service on Linux:

+ :::image type="content" source="./media/profiler-aspnetcore-linux/create-linux-app-service.png" alt-text="Create the Linux web app":::

+2. Create the deployment credentials:

+ > [!NOTE]

+ > Record your password to use later when deploying your web app.

+ 

+3. Choose the deployment options. Set up a local Git repository in the web app by following the instructions on the Azure portal. A Git repository is automatically created.

+ 

+For more deployment options, see [App Service documentation](../../app-service/index.yml).

+## Deploy your project

+1. In your Command Prompt window, browse to the root folder for your project. Add a Git remote repository to point to the repository on App Service:

+ ```console

+ git remote add azure https://<username>@<app_name>.scm.azurewebsites.net:443/<app_name>.git

+ ```

+ * Use the **username** that you used to create the deployment credentials.

+ * Use the **app name** that you used to create the web app by using App Service on Linux.

+2. Deploy the project by pushing the changes to Azure:

+ ```console

+ git push azure main

+ ```

+ You should see output similar to the following example:

+ ```output

+ Counting objects: 9, done.

+ Delta compression using up to 8 threads.

+ Compressing objects: 100% (8/8), done.

+ Writing objects: 100% (9/9), 1.78 KiB | 911.00 KiB/s, done.

+ Total 9 (delta 3), reused 0 (delta 0)

+ remote: Updating branch 'main'.

+ remote: Updating submodules.

+ remote: Preparing deployment for commit id 'd7369a99d7'.

+ remote: Generating deployment script.

+ remote: Running deployment command...

+ remote: Handling ASP.NET Core Web Application deployment.

+ remote: ......

+ remote: Restoring packages for /home/site/repository/EventPipeExampleLinux.csproj...

+ remote: .

+ remote: Installing Newtonsoft.Json 10.0.3.

+ remote: Installing Microsoft.ApplicationInsights.Profiler.Core 1.1.0-LKG

+ ...

+ ```

+## Add Application Insights to monitor your web apps

+1. [Create an Application Insights resource](../app/create-new-resource.md).

+2. Copy the **iKey** value of the Application Insights resource and set the following settings in your web apps:

+ `APPINSIGHTS_INSTRUMENTATIONKEY: [YOUR_APPINSIGHTS_KEY]`

+ When the app settings are changed, the site automatically restarts. After the new settings are applied, the Profiler immediately runs for two minutes. The Profiler then runs for two minutes every hour.

+3. Generate some traffic to your website. You can generate traffic by refreshing the site **About** page a few times.

+4. Wait two to five minutes for the events to aggregate to Application Insights.

+5. Browse to the Application Insights **Performance** pane in the Azure portal. You can view the Profiler traces at the bottom right of the pane.

+ 

+## Next steps

+If you use custom containers that are hosted by Azure App Service, follow the instructions in [

+Enable Service Profiler for a containerized ASP.NET Core application](https://github.com/Microsoft/ApplicationInsights-Profiler-AspNetCore/tree/master/examples/EnableServiceProfilerForContainerApp) to enable Application Insights Profiler.

+Report any issues or suggestions to the Application Insights GitHub repository:

+[ApplicationInsights-Profiler-AspNetCore: Issues](https://github.com/Microsoft/ApplicationInsights-Profiler-AspNetCore/issues).

+ Title: Profile Azure Functions app with Application Insights Profiler

+description: Enable Application Insights Profiler for Azure Functions app.

+ms.contributor: charles.weininger

+# Profile live Azure Functions app with Application Insights

+In this article, you'll use the Azure portal to:

+- View the current app settings for your Functions app.

+- Add two new app settings to enable Profiler on the Functions app.

+- Navigate to the Profiler for your Functions app to view data.

+> [!NOTE]

+> You can enable the Application Insights Profiler for Azure Functions apps on the **App Service** plan.

+## Pre-requisites

+- [An Azure Functions app](../../azure-functions/functions-create-function-app-portal.md). Verify your Functions app is on the **App Service** plan.

+

+ :::image type="content" source="./media/profiler-azure-functions/choose-plan.png" alt-text="Screenshot of where to select App Service plan from drop-down in Functions app creation.":::

+- Linked to [an Application Insights resource](../app/create-new-resource.md). Make note of the instrumentation key.

+## App settings for enabling Profiler

+|App Setting | Value |

+||-|

+|APPINSIGHTS_PROFILERFEATURE_VERSION | 1.0.0 |

+|DiagnosticServices_EXTENSION_VERSION | ~3 |

+## Add app settings to your Azure Functions app

+From your Functions app overview page in the Azure portal:

+1. Under **Settings**, select **Configuration**.

+ :::image type="content" source="./media/profiler-azure-functions/configuration-menu.png" alt-text="Screenshot of selecting Configuration from under the Settings section of the left side menu.":::

+1. In the **Application settings** tab, verify the `APPINSIGHTS_INSTRUMENTATIONKEY` setting is included in the settings list.

+ :::image type="content" source="./media/profiler-azure-functions/app-insights-key.png" alt-text="Screenshot showing the App Insights Instrumentation Key setting in the list.":::

+1. Select **New application setting**.

+ :::image type="content" source="./media/profiler-azure-functions/new-setting-button.png" alt-text="Screenshot outlining the new application setting button.":::

+1. Copy the **App Setting** and its **Value** from the [table above](#app-settings-for-enabling-profiler) and paste into the corresponding fields.

+ :::image type="content" source="./media/profiler-azure-functions/app-setting-1.png" alt-text="Screenshot adding the app insights profiler feature version setting.":::

+ :::image type="content" source="./media/profiler-azure-functions/app-setting-2.png" alt-text="Screenshot adding the diagnostic services extension version setting.":::

+ Leave the **Deployment slot setting** blank for now.

+1. Click **OK**.

+1. Click **Save** in the top menu, then **Continue**.

+ :::image type="content" source="./media/profiler-azure-functions/save-button.png" alt-text="Screenshot outlining the save button in the top menu of the configuration blade.":::

+ :::image type="content" source="./media/profiler-azure-functions/continue-button.png" alt-text="Screenshot outlining the continue button in the dialog after saving.":::

+The app settings now show up in the table:

+ :::image type="content" source="./media/profiler-azure-functions/app-settings-table.png" alt-text="Screenshot showing the two new app settings in the table on the configuration blade.":::

+## View the Profiler data for your Azure Functions app

+1. Under **Settings**, select **Application Insights (preview)** from the left menu.

+ :::image type="content" source="./media/profiler-azure-functions/app-insights-menu.png" alt-text="Screenshot showing application insights from the left menu of the Functions app.":::

+1. Select **View Application Insights data**.

+ :::image type="content" source="./media/profiler-azure-functions/view-app-insights-data.png" alt-text="Screenshot showing the button for viewing application insights data for the Functions app.":::

+1. On the App Insights page for your Functions app, select **Performance** from the left menu.

+ :::image type="content" source="./media/profiler-azure-functions/performance-menu.png" alt-text="Screenshot showing the performance link in the left menu of the app insights blade of the functions app.":::

+1. Select **Profiler** from the top menu of the Performance blade.

+ :::image type="content" source="./media/profiler-azure-functions/profiler-function-app.png" alt-text="Screenshot showing link to profiler for functions app.":::

+## Next Steps

+- Set these values using [Azure Resource Manager Templates](../app/azure-web-apps-net-core.md#app-service-application-settings-with-azure-resource-manager), [Azure PowerShell](/powershell/module/az.websites/set-azwebapp), or the [Azure CLI](/cli/azure/webapp/config/appsettings).

+- Learn more about [Profiler settings](profiler-settings.md).

+ Title: Configure BYOS (Bring Your Own Storage) for Profiler & Snapshot Debugger

+description: Configure BYOS (Bring Your Own Storage) for Profiler & Snapshot Debugger

+# Configure Bring Your Own Storage (BYOS) for Application Insights Profiler and Snapshot Debugger

+## What is Bring Your Own Storage (BYOS) and why might I need it?

+When you use Application Insights Profiler or Snapshot Debugger, artifacts generated by your application are uploaded into Azure storage accounts over the public Internet. Those accounts are paid and controlled by Microsoft for processing and analysis. Microsoft controls the encryption-at-rest and lifetime management policies for those artifacts.

+With Bring Your Own Storage, these artifacts are uploaded into a storage account that you control. That means you control the encryption-at-rest policy, the lifetime management policy and network access. You will, however, be responsible for the costs associated with that storage account.

+> [!NOTE]

+> If you are enabling Private Link, Bring Your Own Storage is a requirement. For more information about Private Link for Application Insights, [see the documentation.](../logs/private-link-security.md)

+>

+> If you are enabling Customer-Managed Keys, Bring Your Own Storage is a requirement. For more information about Customer-Managed Keys for Application Insights, [see the documentation.](../logs/customer-managed-keys.md).

+## How will my storage account be accessed?

+1. Agents running in your Virtual Machines or App Service will upload artifacts (profiles, snapshots, and symbols) to blob containers in your account. This process involves contacting the Application Insights Profiler or Snapshot Debugger service to obtain a SAS (Shared Access Signature) token to a new blob in your storage account.

+1. The Application Insights Profiler or Snapshot Debugger service will analyze the incoming blob and write back the analysis results and log files into blob storage. Depending on available compute capacity, this process may occur anytime after upload.

+1. When you view the profiler traces, or snapshot debugger analysis, the service will fetch the analysis results from blob storage.

+## Prerequisites

+* Make sure to create your Storage Account in the same location as your Application Insights Resource. Ex. If your Application Insights resource is in West US 2, your Storage Account must be also in West US 2.

+* Grant the "Storage Blob Data Contributor" role to the AAD application "Diagnostic Services Trusted Storage Access" in your storage account via the Access Control (IAM) UI.

+* If Private Link enabled, configure the additional setting to allow connection to our Trusted Microsoft Service from your Virtual Network.

+## How to enable BYOS

+### Create Storage Account

+Create a brand-new Storage Account (if you don't have it) on the same location as your Application Insights resource.

+If your Application Insights resource it's on `West US 2`, then, your Storage Account must be in `West US 2`.

+### Grant Access to Diagnostic Services to your Storage Account

+A BYOS storage account will be linked to an Application Insights resource. There may be only one storage account per Application Insights resource and both must be in the same location. You may use the same storage account with more than one Application Insights resource.

+First, the Application Insights Profiler, and Snapshot Debugger service needs to be granted access to the storage account. To grant access, add the role `Storage Blob Data Contributor` to the AAD application named `Diagnostic Services Trusted Storage Access` via the Access Control (IAM) page in your storage account as shown in Figure 1.0.

+Steps:

+1. Select **Access control (IAM)**.

+1. Select **Add** > **Add role assignment** to open the Add role assignment page.

+1. Assign the following role. For detailed steps, see [Assign Azure roles using the Azure portal](../../role-based-access-control/role-assignments-portal.md).

+

+ | Setting | Value |

+ | | |

+ | Role | Storage Blob Data Contributor |

+ | Assign access to | User, group, or service principal |

+ | Members | Diagnostic Services Trusted Storage Access |

+ 

+After you added the role, it will appear under the "Role assignments" section, like the below Figure 1.1.

+__

+_Figure 1.1_

+If you're also using Private Link, it's required one additional configuration to allow connection to our Trusted Microsoft Service from your Virtual Network. Refer to the [Storage Network Security documentation](../../storage/common/storage-network-security.md#trusted-microsoft-services).

+### Link your Storage Account with your Application Insights resource

+To configure BYOS for code-level diagnostics (Profiler/Debugger), there are three options:

+* Using Azure PowerShell cmdlets

+* Using the Azure CLI

+* Using Azure Resource Manager templates

+#### Configure using Azure PowerShell Cmdlets

+1. Make sure you have installed Az PowerShell 4.2.0 or greater.

+ To install Azure PowerShell, refer to the [Official Azure PowerShell documentation](/powershell/azure/install-az-ps).

+1. Install the Application Insights PowerShell extension.

+ ```powershell

+ Install-Module -Name Az.ApplicationInsights -Force

+ ```

+1. Sign in with your Azure Account

+ ```powershell

+ Connect-AzAccount -Subscription "{subscription_id}"

+ ```

+ For more info of how to sign in, refer to the [Connect-AzAccount documentation](/powershell/module/az.accounts/connect-azaccount).

+1. Remove previous Storage Account linked to your Application Insights resource.

+ Pattern:

+ ```powershell

+ $appInsights = Get-AzApplicationInsights -ResourceGroupName "{resource_group_name}" -Name "{application_insights_name}"

+ Remove-AzApplicationInsightsLinkedStorageAccount -ResourceId $appInsights.Id

+ ```

+ Example:

+ ```powershell

+ $appInsights = Get-AzApplicationInsights -ResourceGroupName "byos-test" -Name "byos-test-westus2-ai"

+ Remove-AzApplicationInsightsLinkedStorageAccount -ResourceId $appInsights.Id

+ ```

+1. Connect your Storage Account with your Application Insights resource.

+

+ Pattern:

+ ```powershell

+ $storageAccount = Get-AzStorageAccount -ResourceGroupName "{resource_group_name}" -Name "{storage_account_name}"

+ $appInsights = Get-AzApplicationInsights -ResourceGroupName "{resource_group_name}" -Name "{application_insights_name}"

+ New-AzApplicationInsightsLinkedStorageAccount -ResourceId $appInsights.Id -LinkedStorageAccountResourceId $storageAccount.Id

+ ```

+ Example:

+ ```powershell

+ $storageAccount = Get-AzStorageAccount -ResourceGroupName "byos-test" -Name "byosteststoragewestus2"

+ $appInsights = Get-AzApplicationInsights -ResourceGroupName "byos-test" -Name "byos-test-westus2-ai"

+ New-AzApplicationInsightsLinkedStorageAccount -ResourceId $appInsights.Id -LinkedStorageAccountResourceId $storageAccount.Id

+ ```

+#### Configure using Azure CLI

+1. Make sure you have installed Azure CLI.

+ To install Azure CLI, refer to the [Official Azure CLI documentation](/cli/azure/install-azure-cli).

+1. Install the Application Insights CLI extension.

+ ```azurecli

+ az extension add -n application-insights

+ ```

+1. Connect your Storage Account with your Application Insights resource.

+ Pattern:

+ ```azurecli

+ az monitor app-insights component linked-storage link --resource-group "{resource_group_name}" --app "{application_insights_name}" --storage-account "{storage_account_name}"

+ ```

+

+ Example:

+ ```azurecli

+ az monitor app-insights component linked-storage link --resource-group "byos-test" --app "byos-test-westus2-ai" --storage-account "byosteststoragewestus2"

+ ```

+

+ Expected output:

+ ```powershell

+ {

+ "id": "/subscriptions/{subscription}/resourcegroups/byos-test/providers/microsoft.insights/components/byos-test-westus2-ai/linkedstorageaccounts/serviceprofiler",

+ "linkedStorageAccount": "/subscriptions/{subscription}/resourceGroups/byos-test/providers/Microsoft.Storage/storageAccounts/byosteststoragewestus2",

+ "name": "serviceprofiler",

+ "resourceGroup": "byos-test",

+ "type": "microsoft.insights/components/linkedstorageaccounts"

+ }

+ ```

+ > [!NOTE]

+ > For performing updates on the linked Storage Accounts to your Application Insights resource, refer to the [Application Insights CLI documentation](/cli/azure/monitor/app-insights/component/linked-storage).

+#### Configure using Azure Resource Manager template

+1. Create an Azure Resource Manager template file with the following content (byos.template.json).

+ ```json

+ {

+ "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",

+ "contentVersion": "1.0.0.0",

+ "parameters": {

+ "applicationinsights_name": {

+ "type": "String"

+ },

+ "storageaccount_name": {

+ "type": "String"

+ }

+ },

+ "variables": {},

+ "resources": [

+ {

+ "name": "[concat(parameters('applicationinsights_name'), '/serviceprofiler')]",

+ "type": "Microsoft.Insights/components/linkedStorageAccounts",

+ "apiVersion": "2020-03-01-preview",

+ "properties": {

+ "linkedStorageAccount": "[resourceId('Microsoft.Storage/storageAccounts', parameters('storageaccount_name'))]"

+ }

+ }

+ ],

+ "outputs": {}

+ }

+ ```

+1. Run the following PowerShell command to deploy previous template (create Linked Storage Account).

+ Pattern:

+ ```powershell

+ New-AzResourceGroupDeployment -ResourceGroupName "{your_resource_name}" -TemplateFile "{local_path_to_arm_template}"

+ ```

+ Example:

+ ```powershell

+ New-AzResourceGroupDeployment -ResourceGroupName "byos-test" -TemplateFile "D:\Docs\byos.template.json"

+ ```

+1. Provide the following parameters when prompted in the PowerShell console:

+

+ | Parameter | Description |

+ |-|--|

+ | application_insights_name | The name of the Application Insights resource to enable BYOS. |

+ | storage_account_name | The name of the Storage Account resource that you'll use as your BYOS. |

+

+ Expected output:

+ ```powershell

+ Supply values for the following parameters:

+ (Type !? for Help.)

+ application_insights_name: byos-test-westus2-ai

+ storage_account_name: byosteststoragewestus2

+

+ DeploymentName : byos.template

+ ResourceGroupName : byos-test

+ ProvisioningState : Succeeded

+ Timestamp : 4/16/2020 1:24:57 AM

+ Mode : Incremental

+ TemplateLink :

+ Parameters :

+ Name Type Value

+ ============================== ========================= ==========

+ application_insights_name String byos-test-westus2-ai

+ storage_account_name String byosteststoragewestus2

+

+ Outputs :

+ DeploymentDebugLogLevel :

+ ```

+1. Enable code-level diagnostics (Profiler/Debugger) on the workload of interest through the Azure portal. (App Service > Application Insights)

+__

+_Figure 2.0_

+## Troubleshooting

+### Template schema '{schema_uri}' isn't supported.

+* Make sure that the `$schema` property of the template is valid. It must follow the following pattern:

+`https://schema.management.azure.com/schemas/{schema_version}/deploymentTemplate.json#`

+* Make sure that the `schema_version` of the template is within valid values: `2014-04-01-preview, 2015-01-01, 2018-05-01, 2019-04-01, 2019-08-01`.

+ Error message:

+ ```powershell

+ New-AzResourceGroupDeployment : 11:53:49 AM - Error: Code=InvalidTemplate; Message=Deployment template validation failed: 'Template schema

+ 'https://schema.management.azure.com/schemas/2020-01-01/deploymentTemplate.json#' is not supported. Supported versions are

+ '2014-04-01-preview,2015-01-01,2018-05-01,2019-04-01,2019-08-01'. Please see https://aka.ms/arm-template for usage details.'.

+ ```

+### No registered resource provider found for location '{location}'.

+* Make sure that the `apiVersion` of the resource `microsoft.insights/components` is `2015-05-01`.

+* Make sure that the `apiVersion` of the resource `linkedStorageAccount` is `2020-03-01-preview`.

+ Error message:

+ ```powershell

+ New-AzResourceGroupDeployment : 6:18:03 PM - Resource microsoft.insights/components 'byos-test-westus2-ai' failed with message '{

+ "error": {

+ "code": "NoRegisteredProviderFound",

+ "message": "No registered resource provider found for location 'westus2' and API version '2020-03-01-preview' for type 'components'. The supported api-versions are '2014-04-01,

+ 2014-08-01, 2014-12-01-preview, 2015-05-01, 2018-05-01-preview'. The supported locations are ', eastus, southcentralus, northeurope, westeurope, southeastasia, westus2, uksouth,

+ canadacentral, centralindia, japaneast, australiaeast, koreacentral, francecentral, centralus, eastus2, eastasia, westus, southafricanorth, northcentralus, brazilsouth, switzerlandnorth,

+ australiasoutheast'."

+ }

+ }'

+ ```

+### Storage account location should match AI component location.

+* Make sure that the location of the Application Insights resource is the same as the Storage Account.

+ Error message:

+ ```powershell

+ New-AzResourceGroupDeployment : 1:01:12 PM - Resource microsoft.insights/components/linkedStorageAccounts 'byos-test-centralus-ai/serviceprofiler' failed with message '{

+ "error": {

+ "code": "BadRequest",

+ "message": "Storage account location should match AI component location",

+ "innererror": {

+ "trace": [

+ "System.ArgumentException"

+ ]

+ }

+ }

+ }'

+ ```

+For general Profiler troubleshooting, refer to the [Profiler Troubleshoot documentation](profiler-troubleshooting.md).

+For general Snapshot Debugger troubleshooting, refer to the [Snapshot Debugger Troubleshoot documentation](../app/snapshot-debugger-troubleshoot.md).

+## FAQs

+* If I have Profiler or Snapshot enabled, and then I enabled BYOS, will my data be migrated into my Storage Account?

+ _No, it won't._

+* Will BYOS work with Encryption at Rest and Customer-Managed Key?

+ _Yes, to be precise, BYOS is a requisite to have profiler/debugger enabled with Customer-Manager Keys._

+* Will BYOS work in an environment isolated from the Internet?

+ _Yes. In fact, BYOS is a requirement for isolated network scenarios._

+* Will BYOS work when, both, Customer-Managed Keys and Private Link were enabled?

+ _Yes, it can be possible._

+* If I have enabled BYOS, can I go back using Diagnostic Services storage accounts to store my data collected?

+ _Yes, you can, but, right now we don't support data migration from your BYOS._

+* After enabling BYOS, will I take over of all the related costs of it, which are Storage and Networking?

+ _Yes_

+ Title: Profile live Azure Cloud Services with Application Insights | Microsoft Docs

+description: Enable Application Insights Profiler for Azure Cloud Services.

+# Profile live Azure Cloud Services with Application Insights

+You can also deploy Application Insights Profiler on these

+* [Azure App Service](profiler.md?toc=/azure/azure-monitor/toc.json)

+* [Azure Service Fabric applications](profiler-servicefabric.md?toc=/azure/azure-monitor/toc.json)

+* [Azure Virtual Machines](profiler-vm.md?toc=/azure/azure-monitor/toc.json)

+Application Insights Profiler is installed with the Azure Diagnostics extension. You just need to configure Azure Diagnostics to install Profiler and send profiles to your Application Insights resource.

+## Enable Profiler for Azure Cloud Services

+1. Check to make sure that you're using [.NET Framework 4.6.1](/dotnet/framework/migration-guide/how-to-determine-which-versions-are-installed) or newer. If you are using OS family 4, you'll need to install .NET Framework 4.6.1 or newer with a [startup task](../../cloud-services/cloud-services-dotnet-install-dotnet.md). OS Family 5 includes a compatible version of .NET Framework by default.

+1. Add [Application Insights SDK to Azure Cloud Services](../app/cloudservices.md?toc=%2fazure%2fazure-monitor%2ftoc.json).

+ **The bug in the profiler that ships in the WAD for Cloud Services has been fixed.** The latest version of WAD (1.12.2.0) for Cloud Services works with all recent versions of the App Insights SDK. Cloud Service hosts will upgrade WAD automatically, but it isn't immediate. To force an upgrade, you can redeploy your service or reboot the node.

+1. Track requests with Application Insights:

+ * For ASP.NET web roles, Application Insights can track the requests automatically.

+ * For worker roles, [add code to track requests](profiler-trackrequests.md?toc=/azure/azure-monitor/toc.json).

+1. Configure the Azure Diagnostics extension to enable Profiler:

+ a. Locate the [Azure Diagnostics](../agents/diagnostics-extension-overview.md) *diagnostics.wadcfgx* file for your application role, as shown here:

+ 

+ If you can't find the file, see [Set up diagnostics for Azure Cloud Services and Virtual Machines](/visualstudio/azure/vs-azure-tools-diagnostics-for-cloud-services-and-virtual-machines).

+ b. Add the following `SinksConfig` section as a child element of `WadCfg`:

+ ```xml

+ <WadCfg>

+ <DiagnosticMonitorConfiguration>...</DiagnosticMonitorConfiguration>

+ <SinksConfig>

+ <Sink name="MyApplicationInsightsProfiler">

+ <!-- Replace with your own Application Insights instrumentation key. -->

+ <ApplicationInsightsProfiler>00000000-0000-0000-0000-000000000000</ApplicationInsightsProfiler>

+ </Sink>

+ </SinksConfig>

+ </WadCfg>

+ ```

+ > [!NOTE]

+ > If the *diagnostics.wadcfgx* file also contains another sink of type ApplicationInsights, all three of the following instrumentation keys must match:

+ > * The key that's used by your application.

+ > * The key that's used by the ApplicationInsights sink.

+ > * The key that's used by the ApplicationInsightsProfiler sink.

+ >

+ > You can find the actual instrumentation key value that's used by the `ApplicationInsights` sink in the *ServiceConfiguration.\*.cscfg* files.

+ > After the Visual Studio 15.5 Azure SDK release, only the instrumentation keys that are used by the application and the ApplicationInsightsProfiler sink need to match each other.

+1. Deploy your service with the new Diagnostics configuration, and Application Insights Profiler is configured to run on your service.

+

+## Next steps

+* Generate traffic to your application (for example, launch an [availability test](../app/monitor-web-app-availability.md)). Then, wait 10 to 15 minutes for traces to start to be sent to the Application Insights instance.

+* See [Profiler traces](profiler-overview.md?toc=/azure/azure-monitor/toc.json) in the Azure portal.

+* To troubleshoot Profiler issues, see [Profiler troubleshooting](profiler-troubleshooting.md?toc=/azure/azure-monitor/toc.json).

+ Title: Profile Azure Containers with Application Insights Profiler

+description: Enable Application Insights Profiler for Azure Containers.

+ms.contributor: charles.weininger

+# Profile live Azure containers with Application Insights

+You can enable the Application Insights Profiler for ASP.NET Core application running in your container almost without code. To enable the Application Insights Profiler on your container instance, you'll need to:

+* Add the reference to the NuGet package.

+* Set the environment variables to enable it.

+In this article, you'll learn the various ways you can:

+- Install the NuGet package in the project.

+- Set the environment variable via the orchestrator (like Kubernetes).

+- Learn security considerations around production deployment, like protecting your Application Insights Instrumentation key.

+## Pre-requisites

+- [An Application Insights resource](../app/create-new-resource.md). Make note of the instrumentation key.

+- [Docker Desktop](https://www.docker.com/products/docker-desktop/) to build docker images.

+- [.NET 6 SDK](https://dotnet.microsoft.com/download/dotnet/6.0) installed.

+## Set up the environment

+1. Clone and use the following [sample project](https://github.com/microsoft/ApplicationInsights-Profiler-AspNetCore/tree/main/examples/EnableServiceProfilerForContainerAppNet6):

+

+ ```bash

+ git clone https://github.com/microsoft/ApplicationInsights-Profiler-AspNetCore.git

+ ```

+1. Navigate to the Container App example:

+ ```bash

+ cd examples/EnableServiceProfilerForContainerAppNet6

+ ```

+1. This example is a bare bone project created by calling the following CLI command:

+ ```powershell

+ dotnet new mvc -n EnableServiceProfilerForContainerApp

+ ```

+ Note that we've added delay in the `Controllers/WeatherForecastController.cs` project to simulate the bottleneck.

+ ```CSharp

+ [HttpGet(Name = "GetWeatherForecast")]

+ public IEnumerable<WeatherForecast> Get()

+ {

+ SimulateDelay();

+ ...

+ // Other existing code.

+ }

+ private void SimulateDelay()

+ {

+ // Delay for 500ms to 2s to simulate a bottleneck.

+ Thread.Sleep((new Random()).Next(500, 2000));

+ }

+ ```

+1. Enable Application Insights and Profiler in `Startup.cs`:

+ ```csharp

+ public void ConfigureServices(IServiceCollection services)

+ {

+ services.AddApplicationInsightsTelemetry(); // Add this line of code to enable Application Insights.

+ services.AddServiceProfiler(); // Add this line of code to Enable Profiler

+ services.AddControllersWithViews();

+ }

+ ```

+## Pull the latest ASP.NET Core build/runtime images

+1. Navigate to the .NET Core 6.0 example directory.

+ ```bash

+ cd examples/EnableServiceProfilerForContainerAppNet6

+ ```

+1. Pull the latest ASP.NET Core images

+ ```shell

+ docker pull mcr.microsoft.com/dotnet/sdk:6.0

+ docker pull mcr.microsoft.com/dotnet/aspnet:6.0

+ ```

+> [!TIP]

+> Find the official images for Docker [SDK](https://hub.docker.com/_/microsoft-dotnet-sdk) and [runtime](https://hub.docker.com/_/microsoft-dotnet-aspnet).

+## Add your Application Insights key

+1. Via your Application Insights resource in the Azure portal, take note of your Application Insights instrumentation key.

+ :::image type="content" source="./media/profiler-containerinstances/application-insights-key.png" alt-text="Find instrumentation key in Azure portal":::

+1. Open `appsettings.json` and add your Application Insights instrumentation key to this code section:

+ ```json

+ {

+ "ApplicationInsights":

+ {

+ "InstrumentationKey": "Your instrumentation key"

+ }

+ }

+ ```

+## Build and run the Docker image

+1. Review the `Dockerfile`.

+1. Build the example image:

+ ```bash

+ docker build -t profilerapp .

+ ```

+1. Run the container:

+ ```bash

+ docker run -d -p 8080:80 --name testapp profilerapp

+ ```

+## View the container via your browser

+To hit the endpoint, either:

+- Visit `http://localhost:8080/weatherforecast` in your browser, or

+- Use curl:

+

+ ```terraform

+ curl http://localhost:8080/weatherforecast

+ ```

+## Inspect the logs

+Optionally, inspect the local log to see if a session of profiling finished:

+```bash

+docker logs testapp

+```

+In the local logs, note the following events:

+

+```output

+Starting application insights profiler with instrumentation key: your-instrumentation key # Double check the instrumentation key

+Service Profiler session started. # Profiler started.

+Finished calling trace uploader. Exit code: 0 # Uploader is called with exit code 0.

+Service Profiler session finished. # A profiling session is completed.

+```

+## View the Service Profiler traces

+1. Wait for 2-5 minutes so the events can be aggregated to Application Insights.

+1. Open the **Performance** blade in your Application Insights resource.

+1. Once the trace process is complete, you will see the Profiler Traces button like it below:

+ :::image type="content" source="./media/profiler-containerinstances/profiler-traces.png" alt-text="Profile traces in the performance blade":::

+## Clean up resources

+Run the following command to stop the example project:

+```bash

+docker rm -f testapp

+```

+## Next Steps

+- Learn more about [Application Insights Profiler](./profiler-overview.md).

+- Learn how to enable Profiler in your [ASP.NET Core applications run on Linux](./profiler-aspnetcore-linux.md).

+ Title: Profile production apps in Azure with Application Insights Profiler

+description: Identify the hot path in your web server code with a low-footprint profiler

+ms.contributor: charles.weininger

+# Profile production applications in Azure with Application Insights

+Azure Application Insights Profiler provides performance traces for applications running in production in Azure. Profiler:

+- Captures the data automatically at scale without negatively affecting your users.

+- Helps you identify the ΓÇ£hotΓÇ¥ code path spending the most time handling a particular web request.

+## Enable Application Insights Profiler for your application

+### Supported in Profiler

+Profiler works with .NET applications deployed on the following Azure services. View specific instructions for enabling Profiler for each service type in the links below.

+| Compute platform | .NET (>= 4.6) | .NET Core | Java |

+| - | - | | - |

+| [Azure App Service](profiler.md) | Yes | Yes | No |

+| [Azure Virtual Machines and virtual machine scale sets for Windows](profiler-vm.md) | Yes | Yes | No |

+| [Azure Virtual Machines and virtual machine scale sets for Linux](profiler-aspnetcore-linux.md) | No | Yes | No |

+| [Azure Cloud Services](profiler-cloudservice.md) | Yes | Yes | N/A |

+| [Azure Container Instances for Windows](profiler-containers.md) | No | Yes | No |

+| [Azure Container Instances for Linux](profiler-containers.md) | No | Yes | No |

+| Kubernetes | No | Yes | No |

+| Azure Functions | Yes | Yes | No |

+| Azure Spring Cloud | N/A | No | No |

+| [Azure Service Fabric](profiler-servicefabric.md) | Yes | Yes | No |

+If you've enabled Profiler but aren't seeing traces, check our [Troubleshooting guide](profiler-troubleshooting.md?toc=/azure/azure-monitor/toc.json).

+## How to generate load to view Profiler data

+For Profiler to upload traces, your application must be actively handling requests. You can trigger Profiler manually with a single click.

+Suppose you're running a web performance test. You'll need traces to help you understand how your web app is running under load. By controlling when traces are captured, you'll know when the load test will be running, while the random sampling interval might miss it.

+### Generate traffic to your web app by starting a web performance test

+If you've newly enabled Profiler, you can run a short [load test](/vsts/load-test/app-service-web-app-performance-test). If your web app already has incoming traffic or if you just want to manually generate traffic, skip the load test and start a Profiler on-demand session.

+### Start a Profiler on-demand session

+1. From the Application Insights overview page, select **Performance** from the left menu.

+1. On the **Performance** pane, select **Profiler** from the top menu for Profiler settings.

+ :::image type="content" source="./media/profiler-overview/profiler-button-inline.png" alt-text="Screenshot of the Profiler button from the Performance blade" lightbox="media/profiler-settings/profiler-button.png":::

+1. Once the Profiler settings page loads, select **Profile Now**.

+ :::image type="content" source="./media/profiler-settings/configure-blade-inline.png" alt-text="Profiler page features and settings" lightbox="media/profiler-settings/configure-blade.png":::

+### View traces

+1. After the Profiler sessions finish running, return to the **Performance** pane.

+1. Under **Drill into...**, select **Profiler traces** to view the traces.

+ :::image type="content" source="./media/profiler-overview/trace-explorer-inline.png" alt-text="Screenshot of trace explorer page" lightbox="media/profiler-overview/trace-explorer.png":::

+The trace explorer displays the following information:

+| Filter | Description |

+| | -- |

+| Profile tree v. Flame graph | View the traces as either a tree or in graph form. |

+| Hot path | Select to open the biggest leaf node. In most cases, this node is near a performance bottleneck. |

+| Framework dependencies | Select to view each of the traced framework dependencies associated with the traces. |

+| Hide events | Type in strings to hide from the trace view. Select *Suggested events* for suggestions. |

+| Event | Event or function name. The tree displays a mix of code and events that occurred, such as SQL and HTTP events. The top event represents the overall request duration. |

+| Module | The module where the traced event or function occurred. |

+| Thread time | The time interval between the start of the operation and the end of the operation. |

+| Timeline | The time when the function or event was running in relation to other functions. |

+## How to read performance data

+The Microsoft service profiler uses a combination of sampling methods and instrumentation to analyze the performance of your application. When detailed collection is in progress, the service profiler samples the instruction pointer of each machine CPU every millisecond. Each sample captures the complete call stack of the thread that's currently executing. It gives detailed information about what that thread was doing, at both a high level and a low level of abstraction. The service profiler also collects other events to track activity correlation and causality, including context switching events, Task Parallel Library (TPL) events, and thread pool events.

+The call stack displayed in the timeline view is the result of the sampling and instrumentation. Because each sample captures the complete call stack of the thread, it includes code from Microsoft .NET Framework and other frameworks that you reference.

+### <a id="jitnewobj"></a>Object allocation (clr!JIT\_New or clr!JIT\_Newarr1)

+**clr!JIT\_New** and **clr!JIT\_Newarr1** are helper functions in .NET Framework that allocate memory from a managed heap.

+- **clr!JIT\_New** is invoked when an object is allocated.

+- **clr!JIT\_Newarr1** is invoked when an object array is allocated.

+These two functions usually work quickly. If **clr!JIT\_New** or **clr!JIT\_Newarr1** take up time in your timeline, the code might be allocating many objects and consuming significant amounts of memory.

+### <a id="theprestub"></a>Loading code (clr!ThePreStub)

+**clr!ThePreStub** is a helper function in .NET Framework that prepares the code for initial execution, which usually includes just-in-time (JIT) compilation. For each C# method, **clr!ThePreStub** should be invoked, at most, once during a process.

+If **clr!ThePreStub** takes extra time for a request, it's the first request to execute that method. The .NET Framework runtime takes a significant amount of time to load the first method. Consider:

+- Using a warmup process that executes that portion of the code before your users access it.

+- Running Native Image Generator (ngen.exe) on your assemblies.

+### <a id="lockcontention"></a>Lock contention (clr!JITutil\_MonContention or clr!JITutil\_MonEnterWorker)

+**clr!JITutil\_MonContention** or **clr!JITutil\_MonEnterWorker** indicate that the current thread is waiting for a lock to be released. This text is often displayed when you:

+- Execute a C# **LOCK** statement,

+- Invoke the **Monitor.Enter** method, or

+- Invoke a method with the **MethodImplOptions.Synchronized** attribute.

+Lock contention usually occurs when thread _A_ acquires a lock and thread _B_ tries to acquire the same lock before thread _A_ releases it.

+### <a id="ngencold"></a>Loading code ([COLD])

+If the .NET Framework runtime is executing [unoptimized code](/cpp/build/profile-guided-optimizations) for the first time, the method name will contain **[COLD]**:

+`mscorlib.ni![COLD]System.Reflection.CustomAttribute.IsDefined`

+For each method, it should be displayed once during the process, at most.

+If loading code takes a substantial amount of time for a request, it's the request's initiate execute of the unoptimized portion of the method. Consider using a warmup process that executes that portion of the code before your users access it.

+### <a id="httpclientsend"></a>Send HTTP request

+Methods such as **HttpClient.Send** indicate that the code is waiting for an HTTP request to be completed.

+### <a id="sqlcommand"></a>Database operation

+Methods such as **SqlCommand.Execute** indicate that the code is waiting for a database operation to finish.

+### <a id="await"></a>Waiting (AWAIT\_TIME)

+**AWAIT\_TIME** indicates that the code is waiting for another task to finish. This delay occurs with the C# **AWAIT** statement. When the code does a C# **AWAIT**:

+- The thread unwinds and returns control to the thread pool.

+- There's no blocked thread waiting for the **AWAIT** to finish.

+However, logically, the thread that did the **AWAIT** is "blocked", waiting for the operation to finish. The **AWAIT\_TIME** statement indicates the blocked time, waiting for the task to finish.

+### <a id="block"></a>Blocked time

+**BLOCKED_TIME** indicates that the code is waiting for another resource to be available. For example, it might be waiting for:

+- A synchronization object

+- A thread to be available

+- A request to finish

+### Unmanaged Async

+In order for async calls to be tracked across threads, .NET Framework emits ETW events and passes activity ids between threads. Since unmanaged (native) code and some older styles of asynchronous code lack these events and activity ids, the Profiler can't track the thread and functions running on the thread. This is labeled **Unmanaged Async** in the call stack. Download the ETW file to use [PerfView](https://github.com/Microsoft/perfview/blob/master/documentation/Downloading.md) for more insight.

+### <a id="cpu"></a>CPU time

+The CPU is busy executing the instructions.

+### <a id="disk"></a>Disk time

+The application is performing disk operations.

+### <a id="network"></a>Network time

+The application is performing network operations.

+### <a id="when"></a>When column

+The **When** column is a visualization of the variety of _inclusive_ samples collected for a node over time. The total range of the request is divided into 32 time buckets, where the node's inclusive samples accumulate. Each bucket is represented as a bar. The height of the bar represents a scaled value. For the following nodes, the bar represents the consumption of one of the resources during the bucket:

+- Nodes marked **CPU_TIME** or **BLOCKED_TIME**.

+- Nodes with an obvious relationship to consuming a resource (for example, a CPU, disk, or thread).

+For these metrics, you can get a value of greater than 100% by consuming multiple resources. For example, if you use two CPUs during an interval on average, you get 200%.

+## Limitations

+The default data retention period is five days.

+There are no charges for using the Profiler service. To use it, your web app must be hosted in the basic tier of the Web Apps feature of Azure App Service, at minimum.

+## Overhead and sampling algorithm

+Profiler randomly runs two minutes/hour on each virtual machine hosting the application with Profiler enabled for capturing traces. When Profiler is running, it adds from 5-15% CPU overhead to the server.

+## Next steps

+Enable Application Insights Profiler for your Azure application. Also see:

+* [App Services](profiler.md?toc=/azure/azure-monitor/toc.json)

+* [Azure Cloud Services](profiler-cloudservice.md?toc=/azure/azure-monitor/toc.json)

+* [Azure Service Fabric](profiler-servicefabric.md?toc=/azure/azure-monitor/toc.json)

+* [Azure Virtual Machines and virtual machine scale sets](profiler-vm.md?toc=/azure/azure-monitor/toc.json)

+[performance-blade]: ./media/profiler-overview/performance-blade-v2-examples.png

+[trace-explorer]: ./media/profiler-overview/trace-explorer.png

+ Title: Profile live Azure Service Fabric apps with Application Insights

+description: Enable Profiler for a Service Fabric application

+# Profile live Azure Service Fabric applications with Application Insights

+You can also deploy Application Insights Profiler on these

+* [Azure App Service](profiler.md?toc=/azure/azure-monitor/toc.json)

+* [Azure Cloud Services](profiler-cloudservice.md?toc=/azure/azure-monitor/toc.json)

+* [Azure Virtual Machines](profiler-vm.md?toc=/azure/azure-monitor/toc.json)

+## Set up the environment deployment definition

+Application Insights Profiler is included with Azure Diagnostics. You can install the Azure Diagnostics extension by using an Azure Resource Manager template for your Service Fabric cluster. Get a [template that installs Azure Diagnostics on a Service Fabric Cluster](https://github.com/Azure/azure-docs-json-samples/blob/master/application-insights/ServiceFabricCluster.json).

+To set up your environment, take the following actions:

+1. Profiler supports .NET Framework and .Net Core. If you're using .NET Framework, make sure you're using [.NET Framework 4.6.1](/dotnet/framework/migration-guide/how-to-determine-which-versions-are-installed) or later. It's sufficient to confirm that the deployed OS is `Windows Server 2012 R2` or later. Profiler supports .NET Core [LTS](https://dotnet.microsoft.com/platform/support/policy/dotnet-core) and newer applications.

+1. Search for the [Azure Diagnostics](../agents/diagnostics-extension-overview.md) extension in the deployment template file.

+1. Add the following `SinksConfig` section as a child element of `WadCfg`. Replace the `ApplicationInsightsProfiler` property value with your own Application Insights instrumentation key:

+ ```json

+ "SinksConfig": {

+ "Sink": [

+ {

+ "name": "MyApplicationInsightsProfilerSink",

+ "ApplicationInsightsProfiler": "00000000-0000-0000-0000-000000000000"

+ }

+ ]

+ }

+ ```

+ For information about adding the Diagnostics extension to your deployment template, see [Use monitoring and diagnostics with a Windows VM and Azure Resource Manager templates](../../virtual-machines/extensions/diagnostics-template.md?toc=/azure/virtual-machines/windows/toc.json).

+1. Deploy your Service Fabric cluster by using your Azure Resource Manager template.

+ If your settings are correct, Application Insights Profiler will be installed and enabled when the Azure Diagnostics extension is installed.

+1. Add Application Insights to your Service Fabric application.

+ For Profiler to collect profiles for your requests, your application must be tracking operations with Application Insights. For stateless APIs, you can refer to instructions for [tracking Requests for profiling](profiler-trackrequests.md?toc=/azure/azure-monitor/toc.json). For more information about tracking custom operations in other kinds of apps, see [track custom operations with Application Insights .NET SDK](../app/custom-operations-tracking.md).

+1. Redeploy your application.

+## Next steps

+* Generate traffic to your application (for example, launch an [availability test](../app/monitor-web-app-availability.md)). Then, wait 10 to 15 minutes for traces to start to be sent to the Application Insights instance.

+* See [Profiler traces](profiler-overview.md?toc=/azure/azure-monitor/toc.json) in the Azure portal.

+* For help with troubleshooting Profiler issues, see [Profiler troubleshooting](profiler-troubleshooting.md?toc=/azure/azure-monitor/toc.json).

+ Title: Configure Application Insights Profiler | Microsoft Docs

+description: Use the Azure Application Insights Profiler settings pane to see Profiler status and start profiling sessions

+ms.contributor: Charles.Weininger

+# Configure Application Insights Profiler

+To open the Azure Application Insights Profiler settings pane, select **Performance** from the left menu within your Application Insights page.

+View profiler traces across your Azure resources via two methods:

+**Profiler button**

+Select the **Profiler** button from the top menu.

+**By operation**

+1. Select an operation from the **Operation name** list ("Overall" is highlighted by default).

+1. Select the **Profiler traces** button.

+

+ :::image type="content" source="./media/profiler-settings/operation-entry-inline.png" alt-text="Select operation and Profiler traces to view all profiler traces" lightbox="media/profiler-settings/operation-entry.png":::

+1. Select one of the requests from the list to the left.

+1. Select **Configure Profiler**.

+ :::image type="content" source="./media/profiler-settings/configure-profiler-inline.png" alt-text="Overall selection and clicking Profiler traces to view all profiler traces" lightbox="media/profiler-settings/configure-profiler.png":::

+Once within the Profiler, you can configure and view the Profiler. The **Application Insights Profiler** page has these features:

+| Feature | Description |

+|-|-|

+Profile Now | Starts profiling sessions for all apps that are linked to this instance of Application Insights.

+Triggers | Allows you to configure triggers that cause the profiler to run.

+Recent profiling sessions | Displays information about past profiling sessions, which you can sort using the filters at the top of the page.

+## Profile Now

+Select **Profile Now** to start a profiling session on demand. When you click this link, all profiler agents that are sending data to this Application Insights instance will start to capture a profile. After 5 to 10 minutes, the profile session will show in the list below.

+To manually trigger a profiler session, you'll need, at minimum, *write* access on your role for the Application Insights component. In most cases, you get write access automatically. If you're having issues, you'll need the "Application Insights Component Contributor" subscription scope role added. [See more about role access control with Azure Monitoring](../app/resources-roles-access-control.md).

+## Trigger Settings

+Select the Triggers button on the menu bar to open the CPU, Memory, and Sampling trigger settings pane.

+**CPU or Memory triggers**

+You can set up a trigger to start profiling when the percentage of CPU or Memory use hits the level you set.

+| Setting | Description |

+|-|-|

+On / Off Button | On: profiler can be started by this trigger; Off: profiler won't be started by this trigger.

+Memory threshold | When this percentage of memory is in use, the profiler will be started.

+Duration | Sets the length of time the profiler will run when triggered.

+Cooldown | Sets the length of time the profiler will wait before checking for the memory or CPU usage again after it's triggered.

+**Sampling trigger**

+Unlike CPU or memory triggers, the Sampling trigger isn't triggered by an event. Instead, it's triggered randomly to get a truly random sample of your application's performance. You can:

+- Turn this trigger off to disable random sampling.

+- Set how often profiling will occur and the duration of the profiling session.

+| Setting | Description |

+|-|-|

+On / Off Button | On: profiler can be started by this trigger; Off: profiler won't be started by this trigger.

+Sample rate | The rate at which the profiler can occur. </br> <ul><li>The **Normal** setting collects data 5% of the time, which is about 2 minutes per hour.</li><li>The **High** setting profiles 50% of the time.</li><li>The **Maximum** setting profiles 75% of the time.</li></ul> </br> Normal is recommended for production environments.

+Duration | Sets the length of time the profiler will run when triggered.

+## Recent Profiling Sessions

+This section of the Profiler page displays recent profiling session information. A profiling session represents the time taken by the profiler agent while profiling one of the machines hosting your application. Open the profiles from a session by clicking on one of the rows. For each session, we show:

+| Setting | Description |

+|-|-|

+Triggered by | How the session was started, either by a trigger, Profile Now, or default sampling.

+App Name | Name of the application that was profiled.

+Machine Instance | Name of the machine the profiler agent ran on.

+Timestamp | Time when the profile was captured.

+Tracee | Number of traces that were attached to individual requests.

+CPU % | Percentage of CPU that was being used while the profiler was running.

+Memory % | Percentage of memory that was being used while the profiler was running.

+## Next steps

+[Enable Profiler and view traces](profiler-overview.md?toc=/azure/azure-monitor/toc.json)

+[profiler-on-demand]: ./media/profiler-settings/profiler-on-demand.png

+[performance-blade]: ./media/profiler-settings/performance-blade.png

+[configure-profiler-page]: ./media/profiler-settings/configureBlade.png

+[trigger-settings-flyout]: ./media/profiler-settings/trigger-central-p-u.png

+[create-performance-test]: ./media/profiler-settings/new-performance-test.png

+[configure-performance-test]: ./media/profiler-settings/configure-performance-test.png

+[load-test-queued]: ./media/profiler-settings/load-test-queued.png

+[load-test-in-progress]: ./media/profiler-settings/load-test-in-progress.png

+[enable-app-insights]: ./media/profiler-settings/enable-app-insights-blade-01.png

+[update-site-extension]: ./media/profiler-settings/update-site-extension-01.png

+[change-and-save-appinsights]: ./media/profiler-settings/change-and-save-app-insights-01.png

+[app-settings-for-profiler]: ./media/profiler-settings/app-settings-for-profiler-01.png

+[check-for-extension-update]: ./media/profiler-settings/check-extension-update-01.png

+[profiler-timeout]: ./media/profiler-settings/profiler-time-out.png

+ Title: Write code to track requests with Azure Application Insights | Microsoft Docs

+description: Write code to track requests with Application Insights so you can get profiles for your requests.

+# Write code to track requests with Application Insights

+To view profiles for your application on the Performance page, Azure Application Insights needs to track requests for your application. Application Insights can automatically track requests for applications that are built on already-instrumented frameworks. Two examples are ASP.NET and ASP.NET Core.

+For other applications, such as Azure Cloud Services worker roles and Service Fabric stateless APIs, you need to write code to tell Application Insights where your requests begin and end. After you've written this code, requests telemetry is sent to Application Insights. You can view the telemetry on the Performance page, and profiles are collected for those requests.

+To manually track requests, do the following:

+ 1. Early in the application lifetime, add the following code:

+ ```csharp

+ using Microsoft.ApplicationInsights.Extensibility;

+ ...

+ // Replace with your own Application Insights instrumentation key.

+ TelemetryConfiguration.Active.InstrumentationKey = "00000000-0000-0000-0000-000000000000";

+ ```

+ For more information about this global instrumentation key configuration, see [Use Service Fabric with Application Insights](https://github.com/Azure-Samples/service-fabric-dotnet-getting-started/blob/dev/appinsights/ApplicationInsights.md).

+ 1. For any piece of code that you want to instrument, add a `StartOperation<RequestTelemetry>` **using** statement around it, as shown in the following example:

+ ```csharp

+ using Microsoft.ApplicationInsights;

+ using Microsoft.ApplicationInsights.DataContracts;

+ ...

+ var client = new TelemetryClient();

+ ...

+ using (var operation = client.StartOperation<RequestTelemetry>("Insert_Your_Custom_Event_Unique_Name"))

+ {

+ // ... Code I want to profile.

+ }

+ ```

+ Calling `StartOperation<RequestTelemetry>` within another `StartOperation<RequestTelemetry>` scope isn't supported. You can use `StartOperation<DependencyTelemetry>` in the nested scope instead. For example:

+

+ ```csharp

+ using (var getDetailsOperation = client.StartOperation<RequestTelemetry>("GetProductDetails"))

+ {

+ try

+ {

+ ProductDetail details = new ProductDetail() { Id = productId };

+ getDetailsOperation.Telemetry.Properties["ProductId"] = productId.ToString();

+

+ // By using DependencyTelemetry, 'GetProductPrice' is correctly linked as part of the 'GetProductDetails' request.

+ using (var getPriceOperation = client.StartOperation<DependencyTelemetry>("GetProductPrice"))

+ {

+ double price = await _priceDataBase.GetAsync(productId);

+ if (IsTooCheap(price))

+ {

+ throw new PriceTooLowException(productId);

+ }

+ details.Price = price;

+ }

+

+ // Similarly, note how 'GetProductReviews' doesn't establish another RequestTelemetry.

+ using (var getReviewsOperation = client.StartOperation<DependencyTelemetry>("GetProductReviews"))

+ {

+ details.Reviews = await _reviewDataBase.GetAsync(productId);

+ }

+

+ getDetailsOperation.Telemetry.Success = true;

+ return details;

+ }

+ catch(Exception ex)

+ {

+ getDetailsOperation.Telemetry.Success = false;

+

+ // This exception gets linked to the 'GetProductDetails' request telemetry.

+ client.TrackException(ex);

+ throw;

+ }

+ }

+ ```

+ Title: Troubleshoot problems with Azure Application Insights Profiler

+description: This article presents troubleshooting steps and information to help developers enable and use Application Insights Profiler.

+# Troubleshoot problems enabling or viewing Application Insights Profiler

+## <a id="troubleshooting"></a>General troubleshooting

+### Make sure you're using the appropriate Profiler Endpoint

+Currently the only regions that require endpoint modifications are [Azure Government](../../azure-government/compare-azure-government-global-azure.md#application-insights) and [Azure China](/azure/china/resources-developer-guide).

+|App Setting | US Government Cloud | China Cloud |

+|||-|

+|ApplicationInsightsProfilerEndpoint | `https://profiler.monitor.azure.us` | `https://profiler.monitor.azure.cn` |

+|ApplicationInsightsEndpoint | `https://dc.applicationinsights.us` | `https://dc.applicationinsights.azure.cn` |

+### Profiles are uploaded only if there are requests to your application while Profiler is running

+Azure Application Insights Profiler collects data for two minutes each hour. It can also collect data when you select the **Profile Now** button in the **Configure Application Insights Profiler** pane.

+> [!NOTE]

+> The profiling data is uploaded only when it can be attached to a request that happened while Profiler was running.

+Profiler writes trace messages and custom events to your Application Insights resource. You can use these events to see how Profiler is running:

+1. Search for trace messages and custom events sent by Profiler to your Application Insights resource. You can use this search string to find the relevant data:

+ ```

+ stopprofiler OR startprofiler OR upload OR ServiceProfilerSample

+ ```

+ The following image displays two examples of searches from two AI resources:

+

+ * At the left, the application isn't receiving requests while Profiler is running. The message explains that the upload was canceled because of no activity.

+ * At the right, Profiler started and sent custom events when it detected requests that happened while Profiler was running. If the `ServiceProfilerSample` custom event is displayed, it means that a profile was captured and its available in the **Application Insights Performance** pane.

+ If no records are displayed, Profiler isn't running. To troubleshoot, see the troubleshooting sections for your specific app type later in this article.

+ ![Search Profiler telemetry][profiler-search-telemetry]

+### Other things to check

+* Make sure that your app is running on .NET Framework 4.6.

+* If your web app is an ASP.NET Core application, it must be running at least ASP.NET Core [LTS](https://dotnet.microsoft.com/platform/support/policy/dotnet-core).

+* If the data you're trying to view is older than a couple of weeks, try limiting your time filter and try again. Traces are deleted after seven days.

+* Make sure that proxies or a firewall haven't blocked access to https://gateway.azureserviceprofiler.net.

+* Profiler isn't supported on free or shared app service plans. If you're using one of those plans, try scaling up to one of the basic plans and Profiler should start working.

+### <a id="double-counting"></a>Double counting in parallel threads

+In some cases, the total time metric in the stack viewer is more than the duration of the request.

+This situation might occur when two or more parallel threads are associated with a request. In that case, the total thread time is more than the elapsed time.

+One thread might be waiting on the other to be completed. The viewer tries to detect this situation and omits the uninteresting wait. In doing so, it errs on the side of displaying too much information rather than omit what might be critical information.

+When you see parallel threads in your traces, determine which threads are waiting so that you can identify the hot path for the request.

+Usually, the thread that quickly goes into a wait state is simply waiting on the other threads. Concentrate on the other threads, and ignore the time in the waiting threads.

+### Error report in the profile viewer

+Submit a support ticket in the portal. Be sure to include the correlation ID from the error message.

+## Troubleshoot Profiler on Azure App Service

+For Profiler to work properly:

+* Your web app service plan must be Basic tier or higher.

+* Your web app must have Application Insights enabled.

+* Your web app must have the following app settings:

+ |App Setting | Value |

+ ||-|

+ |APPINSIGHTS_INSTRUMENTATIONKEY | iKey for your Application Insights resource |

+ |APPINSIGHTS_PROFILERFEATURE_VERSION | 1.0.0 |

+ |DiagnosticServices_EXTENSION_VERSION | ~3 |

+* The **ApplicationInsightsProfiler3** webjob must be running. To check the webjob:

+ 1. Go to [Kudu](/archive/blogs/cdndevs/the-kudu-debug-console-azure-websites-best-kept-secret).

+ 1. In the **Tools** menu, select **WebJobs Dashboard**.

+ The **WebJobs** pane opens.

+

+ ![Screenshot shows the WebJobs pane, which displays the name, status, and last run time of jobs.][profiler-webjob]

+

+ 1. To view the details of the webjob, including the log, select the **ApplicationInsightsProfiler3** link.

+ The **Continuous WebJob Details** pane opens.

+ ![Screenshot shows the Continuous WebJob Details pane.][profiler-webjob-log]

+If Profiler isn't working for you, you can download the log and send it to our team for assistance, serviceprofilerhelp@microsoft.com.

+### Check the Diagnostic Services site extension' Status Page

+If Profiler was enabled through the [Application Insights pane](profiler.md) in the portal, it was enabled by the Diagnostic Services site extension.

+> [!NOTE]

+> Codeless installation of Application Insights Profiler follows the .NET Core support policy.

+> For more information about supported runtimes, see [.NET Core Support Policy](https://dotnet.microsoft.com/platform/support/policy/dotnet-core).

+You can check the Status Page of this extension by going to the following url:

+`https://{site-name}.scm.azurewebsites.net/DiagnosticServices`

+> [!NOTE]

+> The domain of the Status Page link will vary depending on the cloud.

+This domain will be the same as the Kudu management site for App Service.

+This Status Page shows the installation state of the Profiler and Snapshot Collector agents. If there was an unexpected error, it will be displayed and show how to fix it.

+You can use the Kudu management site for App Service to get the base url of this Status Page:

+1. Open your App Service application in the Azure portal.

+2. Select **Advanced Tools**, or search for **Kudu**.

+3. Select **Go**.

+4. Once you are on the Kudu management site, in the URL, **append the following `/DiagnosticServices` and press enter**.

+ It will end like this: `https://<kudu-url>/DiagnosticServices`

+It will display a Status Page similar like the below:

+

+

+### Manual installation

+When you configure Profiler, updates are made to the web app's settings. If your environment requires it, you can apply the updates manually. An example might be that your application is running in a Web Apps environment for Power Apps. To apply updates manually:

+1. In the **Web App Control** pane, open **Settings**.

+1. Set **.NET Framework version** to **v4.6**.

+1. Set **Always On** to **On**.

+1. Create these app settings:

+ |App Setting | Value |

+ ||-|

+ |APPINSIGHTS_INSTRUMENTATIONKEY | iKey for your Application Insights resource |

+ |APPINSIGHTS_PROFILERFEATURE_VERSION | 1.0.0 |

+ |DiagnosticServices_EXTENSION_VERSION | ~3 |

+### Too many active profiling sessions

+You can enable Profiler on a maximum of four Web Apps that are running in the same service plan. If you've more than four, Profiler might throw a *Microsoft.ServiceProfiler.Exceptions.TooManyETWSessionException*. To solve it, move some web apps to a different service plan.

+### Deployment error: Directory Not Empty 'D:\\home\\site\\wwwroot\\App_Data\\jobs'

+If you're redeploying your web app to a Web Apps resource with Profiler enabled, you might see the following message:

+*Directory Not Empty 'D:\\home\\site\\wwwroot\\App_Data\\jobs'*

+This error occurs if you run Web Deploy from scripts or from the Azure Pipelines. The solution is to add the following deployment parameters to the Web Deploy task:

+```

+-skip:Directory='.*\\App_Data\\jobs\\continuous\\ApplicationInsightsProfiler.*' -skip:skipAction=Delete,objectname='dirPath',absolutepath='.*\\App_Data\\jobs\\continuous$' -skip:skipAction=Delete,objectname='dirPath',absolutepath='.*\\App_Data\\jobs$' -skip:skipAction=Delete,objectname='dirPath',absolutepath='.*\\App_Data$'

+```

+These parameters delete the folder that's used by Application Insights Profiler and unblock the redeploy process. They don't affect the Profiler instance that's currently running.

+### How do I determine whether Application Insights Profiler is running?

+Profiler runs as a continuous webjob in the web app. You can open the web app resource in the [Azure portal](https://portal.azure.com). In the **WebJobs** pane, check the status of **ApplicationInsightsProfiler**. If it isn't running, open **Logs** to get more information.

+## Troubleshoot VMs and Cloud Services

+>**The bug in the profiler that ships in the WAD for Cloud Services has been fixed.** The latest version of WAD (1.12.2.0) for Cloud Services works with all recent versions of the App Insights SDK. Cloud Service hosts will upgrade WAD automatically, but it isn't immediate. To force an upgrade, you can redeploy your service or reboot the node.

+To see whether Profiler is configured correctly by Azure Diagnostics, follow the below steps:

+1. Verify that the content of the Azure Diagnostics configuration deployed is what you expect.

+1. Second, make sure that Azure Diagnostics passes the proper iKey on the Profiler command line.

+1. Third, check the Profiler log file to see whether Profiler ran but returned an error.

+To check the settings that were used to configure Azure Diagnostics:

+1. Sign in to the virtual machine (VM), and then open the log file at this location. The plugin version may be newer on your machine.

+

+ For VMs:

+ ```

+ c:\WindowsAzure\logs\Plugins\Microsoft.Azure.Diagnostics.PaaSDiagnostics\1.11.3.12\DiagnosticsPlugin.log

+ ```

+

+ For Cloud

+ ```

+ c:\logs\Plugins\Microsoft.Azure.Diagnostics.PaaSDiagnostics\1.11.3.12\DiagnosticsPlugin.log

+ ```

+1. In the file, you can search for the string **WadCfg** to find the settings that were passed to the VM to configure Azure Diagnostics. You can check to see whether the iKey used by the Profiler sink is correct.

+1. Check the command line that's used to start Profiler. The arguments that are used to launch Profiler are in the following file. (The drive could be c: or d: and the directory may be hidden.)

+ For VMs:

+ ```

+ C:\ProgramData\ApplicationInsightsProfiler\config.json

+ ```

+

+ for Cloud

+ ```

+ D:\ProgramData\ApplicationInsightsProfiler\config.json

+ ```

+1. Make sure that the iKey on the Profiler command line is correct.

+1. Using the path found in the preceding *config.json* file, check the Profiler log file, called **BootstrapN.log**. It displays the debug information that indicates the settings that Profiler is using. It also displays status and error messages from Profiler.

+ For VMs, the file is here:

+ ```

+ C:\WindowsAzure\Logs\Plugins\Microsoft.Azure.Diagnostics.IaaSDiagnostics\1.17.0.6\ApplicationInsightsProfiler

+ ```

+ For Cloud

+ ```

+ C:\Logs\Plugins\Microsoft.Azure.Diagnostics.IaaSDiagnostics\1.17.0.6\ApplicationInsightsProfiler

+ ```

+ If Profiler is running while your application is receiving requests, the following message is displayed: *Activity detected from iKey*.

+ When the trace is being uploaded, the following message is displayed: *Start to upload trace*.

+## Edit network proxy or firewall rules

+If your application connects to the Internet via a proxy or a firewall, you may need to update the rules to communicate with the Profiler service.

+The IPs used by Application Insights Profiler are included in the Azure Monitor service tag. For more information, see [Service Tags documentation](../../virtual-network/service-tags-overview.md).

+[profiler-search-telemetry]:./media/profiler-troubleshooting/Profiler-Search-Telemetry.png

+[profiler-webjob]:./media/profiler-troubleshooting/profiler-web-job.png

+[profiler-webjob-log]:./media/profiler-troubleshooting/profiler-web-job-log.png

+ Title: Profile web apps on an Azure VM - Application Insights Profiler

+description: Profile web apps on an Azure VM by using Application Insights Profiler.

+# Profile web apps running on an Azure virtual machine or a virtual machine scale set by using Application Insights Profiler

+You can also deploy Azure Application Insights Profiler on these

+* [Azure App Service](./profiler.md?toc=%2fazure%2fazure-monitor%2ftoc.json)

+* [Azure Cloud Services](profiler-cloudservice.md?toc=/azure/azure-monitor/toc.json)

+* [Azure Service Fabric](?toc=%2fazure%2fazure-monitor%2ftoc.json)

+## Deploy Profiler on a virtual machine or a virtual machine scale set

+This article shows you how to get Application Insights Profiler running on your Azure virtual machine (VM) or Azure virtual machine scale set. Profiler is installed with the Azure Diagnostics extension for VMs. Configure the extension to run Profiler, and build the Application Insights SDK into your application.

+1. Add the Application Insights SDK to your [ASP.NET application](../app/asp-net.md).

+ To view profiles for your requests, you must send request telemetry to Application Insights.

+1. Install Azure Diagnostics extension on your VM. For full Resource Manager template examples, see:

+ * [Virtual machine](https://github.com/Azure/azure-docs-json-samples/blob/master/application-insights/WindowsVirtualMachine.json)

+ * [Virtual machine scale set](https://github.com/Azure/azure-docs-json-samples/blob/master/application-insights/WindowsVirtualMachineScaleSet.json)

+

+ The key part is the ApplicationInsightsProfilerSink in the WadCfg. To have Azure Diagnostics enable Profiler to send data to your iKey, add another sink to this section.

+

+ ```json

+ "SinksConfig": {

+ "Sink": [

+ {

+ "name": "ApplicationInsightsSink",

+ "ApplicationInsights": "85f73556-b1ba-46de-9534-606e08c6120f"

+ },

+ {

+ "name": "MyApplicationInsightsProfilerSink",

+ "ApplicationInsightsProfiler": "85f73556-b1ba-46de-9534-606e08c6120f"

+ }

+ ]

+ },

+ ```

+1. Deploy the modified environment deployment definition.

+ Applying the modifications usually involves a full template deployment or a cloud service-based publish through PowerShell cmdlets or Visual Studio.

+ The following PowerShell commands are an alternate approach for existing virtual machines that touch only the Azure Diagnostics extension. Add the previously mentioned ProfilerSink to the config that's returned by the Get-AzVMDiagnosticsExtension command. Then pass the updated config to the Set-AzVMDiagnosticsExtension command.

+ ```powershell

+ $ConfigFilePath = [IO.Path]::GetTempFileName()

+ # After you export the currently deployed Diagnostics config to a file, edit it to include the ApplicationInsightsProfiler sink.

+ (Get-AzVMDiagnosticsExtension -ResourceGroupName "MyRG" -VMName "MyVM").PublicSettings | Out-File -Verbose $ConfigFilePath

+ # Set-AzVMDiagnosticsExtension might require the -StorageAccountName argument

+ # If your original diagnostics configuration had the storageAccountName property in the protectedSettings section (which is not downloadable), be sure to pass the same original value you had in this cmdlet call.

+ Set-AzVMDiagnosticsExtension -ResourceGroupName "MyRG" -VMName "MyVM" -DiagnosticsConfigurationPath $ConfigFilePath

+ ```

+1. If the intended application is running through [IIS](https://www.microsoft.com/web/downloads/platform.aspx), enable the `IIS Http Tracing` Windows feature.

+ 1. Establish remote access to the environment, and then use the [Add Windows features](/iis/configuration/system.webserver/tracing/) window. Or run the following command in PowerShell (as administrator):

+ ```powershell

+ Enable-WindowsOptionalFeature -FeatureName IIS-HttpTracing -Online -All

+ ```

+

+ 1. If establishing remote access is a problem, you can use the [Azure CLI](/cli/azure/get-started-with-azure-cli) to run the following command:

+ ```azurecli

+ az vm run-command invoke -g MyResourceGroupName -n MyVirtualMachineName --command-id RunPowerShellScript --scripts "Enable-WindowsOptionalFeature -FeatureName IIS-HttpTracing -Online -All"

+ ```

+1. Deploy your application.

+## Set Profiler Sink using Azure Resource Explorer

+We don't yet have a way to set the Application Insights Profiler sink from the portal. Instead of using PowerShell as described above, you can use Azure Resource Explorer to set the sink. But note, if you deploy the VM again, the sink will be lost. You'll need to update the config you use when deploying the VM to preserve this setting.

+1. Check that the Windows Azure Diagnostics extension is installed by viewing the extensions installed for your virtual machine.

+ ![Check if WAD extension is installed][wadextension]

+2. Find the VM Diagnostics extension for your VM. Go to [https://resources.azure.com](https://resources.azure.com). Expand your resource group, Microsoft.Compute virtualMachines, virtual machine name, and extensions.

+ ![Navigate to WAD config in Azure Resource Explorer][azureresourceexplorer]

+3. Add the Application Insights Profiler sink to the SinksConfig node under WadCfg. If you don't already have a SinksConfig section, you may need to add one. Be sure to specify the proper Application Insights iKey in your settings. You'll need to switch the explorers mode to Read/Write in the upper right corner and Press the blue 'Edit' button.

+ ![Add Application Insights Profiler Sink][resourceexplorersinksconfig]

+4. When you're done editing the config, press 'Put'. If the put is successful, a green check will appear in the middle of the screen.

+ ![Send put request to apply changes][resourceexplorerput]

+## Can Profiler run on on-premises servers?

+We have no plan to support Application Insights Profiler for on-premises servers.

+## Next steps

+- Generate traffic to your application (for example, launch an [availability test](../app/monitor-web-app-availability.md)). Then, wait 10 to 15 minutes for traces to start to be sent to the Application Insights instance.

+- See [Profiler traces](profiler-overview.md?toc=/azure/azure-monitor/toc.json) in the Azure portal.

+- For help with troubleshooting Profiler issues, see [Profiler troubleshooting](profiler-troubleshooting.md?toc=/azure/azure-monitor/toc.json).

+[azureresourceexplorer]: ./media/profiler-vm/azure-resource-explorer.png

+[resourceexplorerput]: ./media/profiler-vm/resource-explorer-put.png

+[resourceexplorersinksconfig]: ./media/profiler-vm/resource-explorer-sinks-config.png

+[wadextension]: ./media/profiler-vm/wad-extension.png

+ Title: Enable Profiler for Azure App Service apps | Microsoft Docs

+description: Profile live apps on Azure App Service with Application Insights Profiler.

+# Enable Profiler for Azure App Service apps

+Application Insights Profiler is pre-installed as part of the App Services runtime. You can run Profiler on ASP.NET and ASP.NET Core apps running on Azure App Service using Basic service tier or higher. Follow these steps even if you've included the App Insights SDK in your application at build time.

+To enable Profiler on Linux, walk through the [ASP.NET Core Azure Linux web apps instructions](profiler-aspnetcore-linux.md).

+> [!NOTE]

+> Codeless installation of Application Insights Profiler follows the .NET Core support policy.

+> For more information about supported runtime, see [.NET Core Support Policy](https://dotnet.microsoft.com/platform/support/policy/dotnet-core).

+## Pre-requisites

+- An [Azure App Services ASP.NET/ASP.NET Core app](/app-service/quickstart-dotnetcore.md).

+- [Application Insights resource](../app/create-new-resource.md) connected to your App Service app.

+## Verify "Always On" setting is enabled

+1. In the Azure portal, navigate to your App Service.

+1. Under **Settings** in the left side menu, select **Configuration**.

+ :::image type="content" source="./media/profiler/configuration-menu.png" alt-text="Screenshot of selecting Configuration from the left side menu.":::

+1. Select the **General settings** tab.

+1. Verify **Always On** > **On** is selected.

+ :::image type="content" source="./media/profiler/always-on.png" alt-text="Screenshot of the General tab on the Configuration pane and showing the Always On being enabled.":::

+1. Select **Save** if you've made changes.

+## Enable Application Insights and Profiler

+1. Under **Settings** in the left side menu, select **Application Insights**.

+ :::image type="content" source="./media/profiler/app-insights-menu.png" alt-text="Screenshot of selecting Application Insights from the left side menu.":::

+1. Under **Application Insights**, select **Enable**.

+1. Verify you've connected an Application Insights resource to your app.

+ :::image type="content" source="./media/profiler/enable-app-insights.png" alt-text="Screenshot of enabling App Insights on your app.":::

+1. Scroll down and select the **.NET** or **.NET Core** tab, depending on your app.

+1. Verify **Collection Level** > **Recommended** is selected.

+1. Under **Profiler**, select **On**.

+ - If you chose the **Basic** collection level earlier, the Profiler setting is disabled.

+1. Select **Apply**, then **Yes** to confirm.

+ :::image type="content" source="./media/profiler/enable-profiler.png" alt-text="Screenshot of enabling Profiler on your app.":::

+## Enable Profiler using app settings

+If your Application Insights resource is in a different subscription from your App Service, you'll need to enable Profiler manually by creating app settings for your Azure App Service. You can automate the creation of these settings using a template or other means. The settings needed to enable the profiler:

+|App Setting | Value |

+||-|

+|APPINSIGHTS_INSTRUMENTATIONKEY | iKey for your Application Insights resource |

+|APPINSIGHTS_PROFILERFEATURE_VERSION | 1.0.0 |

+|DiagnosticServices_EXTENSION_VERSION | ~3 |

+Set these values using:

+- [Azure Resource Manager Templates](../app/azure-web-apps-net-core.md#app-service-application-settings-with-azure-resource-manager)

+- [Azure PowerShell](/powershell/module/az.websites/set-azwebapp)

+- [Azure CLI](/cli/azure/webapp/config/appsettings)

+## Enable Profiler for other clouds

+Currently the only regions that require endpoint modifications are [Azure Government](../../azure-government/compare-azure-government-global-azure.md#application-insights) and [Azure China](/azure/china/resources-developer-guide).

+|App Setting | US Government Cloud | China Cloud |

+|||-|

+|ApplicationInsightsProfilerEndpoint | `https://profiler.monitor.azure.us` | `https://profiler.monitor.azure.cn` |

+|ApplicationInsightsEndpoint | `https://dc.applicationinsights.us` | `https://dc.applicationinsights.azure.cn` |

+## Enable Azure Active Directory authentication for profile ingestion

+Application Insights Profiler supports Azure AD authentication for profiles ingestion. For all profiles of your application to be ingested, your application must be authenticated and provide the required application settings to the Profiler agent.

+Profiler only supports Azure AD authentication when you reference and configure Azure AD using the Application Insights SDK in your application.

+To enable Azure AD for profiles ingestion:

+1. Create and add the managed identity to authenticate against your Application Insights resource to your App Service.

+ a. [System-Assigned Managed identity documentation](../../app-service/overview-managed-identity.md?tabs=portal%2chttp#add-a-system-assigned-identity)

+ b. [User-Assigned Managed identity documentation](../../app-service/overview-managed-identity.md?tabs=portal%2chttp#add-a-user-assigned-identity)

+1. [Configure and enable Azure AD](../app/azure-ad-authentication.md?tabs=net#configuring-and-enabling-azure-ad-based-authentication) in your Application Insights resource.

+1. Add the following application setting to let the Profiler agent know which managed identity to use:

+ For System-Assigned Identity:

+ |App Setting | Value |

+ ||-|

+ |APPLICATIONINSIGHTS_AUTHENTICATION_STRING | Authorization=AAD |

+ For User-Assigned Identity:

+ |App Setting | Value |

+ ||-|

+ |APPLICATIONINSIGHTS_AUTHENTICATION_STRING | Authorization=AAD;ClientId={Client id of the User-Assigned Identity} |

+## Disable Profiler

+To stop or restart Profiler for an individual app's instance:

+1. Under **Settings** in the left side menu, select **WebJobs**.

+ :::image type="content" source="./media/profiler/web-jobs-menu.png" alt-text="Screenshot of selecting web jobs from the left side menu.":::

+1. Select the webjob named `ApplicationInsightsProfiler3`.

+1. Click **Stop** from the top menu.

+ :::image type="content" source="./media/profiler/stop-web-job.png" alt-text="Screenshot of selecting stop for stopping the webjob.":::

+1. Select **Yes** to confirm.

+We recommend that you have Profiler enabled on all your apps to discover any performance issues as early as possible.

+Profiler's files can be deleted when using WebDeploy to deploy changes to your web application. You can prevent the deletion by excluding the App_Data folder from being deleted during deployment.

+## Next steps

+* [Working with Application Insights in Visual Studio](../app/visual-studio.md)

+> [!IMPORTANT]

+> If deploying to a centralized virtual machine, then it will need to have the SAP HANA client installed and set up so the AzAcSnap user can run `hdbsql` and `hdbuserstore` commands. The SAP HANA Client can downloaded from https://tools.hana.ondemand.com/#hanatools.

+ > [!IMPORTANT]

+* [SAP System on Oracle Database on Azure - Azure Architecture Center](/azure/architecture/example-scenario/apps/sap-production)

+ For this tutorial, you use Azure Table storage, but any database or storage service works.

+Based on the `x-ms-customproviders-requestpath` header, you can create the *partitionKey* and *rowKey* parameters for your storage as shown in the following table:

+The **TriggerCustomAction** method accepts an incoming request and echoes back the response with a status code.

+The **CreateCustomResource** method updates the incoming request to include the Azure-specific fields **id**, **name**, and **type**. These fields are top-level properties used by services across Azure. They let the custom provider interoperate with other services like Azure Policy, Azure Resource Manager templates, and Azure Activity Log.

+ Title: Extend resources with custom providers

+# Extend resources with custom providers

+In this tutorial, you deploy a custom resource provider to Azure that extends the Azure Resource Manager API with the Microsoft.CustomProviders/associations resource type. The tutorial shows how to extend existing resources that are outside the resource group where the custom provider instance is located. In this tutorial, the custom resource provider is powered by an Azure logic app, but you can use any public API endpoint.

+To complete this tutorial, make sure you review the following:

+In this tutorial, there are two pieces that need to be deployed: **the custom provider** and **the association**. To make the process easier, you can optionally use a single template that deploys both.

+* [Microsoft.CustomProviders/resourceProviders](/azure/templates/microsoft.customproviders/resourcproviders)

+* [Microsoft.Logic/workflows](/azure/templates/microsoft.logic/workflows)

+* [Microsoft.CustomProviders/associations](/azure/templates/microsoft.customproviders/associations)

+ "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",

+ "apiVersion": "2021-04-01",

+ "apiVersion": "2019-05-01",

+ "endpoint": "[[listCallbackURL(concat(resourceId('Microsoft.Logic/workflows', parameters('logicAppName')), '/triggers/CustomProviderWebhook'), '2019-05-01').value]"

+Let's deploy the custom provider infrastructure. Either copy, save, and deploy the preceding template, or follow along and deploy the infrastructure using the Azure portal.

+4. Under **General**, enter a *Name* and *Description* for the new template:

+1. Go to the custom provider **Microsoft.CustomProviders/resourceProviders** resource in the resource group of the previous deployment. You need to select the **Show hidden types** check box:

+3. Search for *templates* in **All Services** or by using the main search box:

+You can go back to the logic app **Run history** and see that another call was made to the logic app. You can update the logic app to augment additional functionality for each created association.

+## Next steps

+In this article, you deployed a custom resource provider to Azure that extends the Azure Resource Manager API with the Microsoft.CustomProviders/associates resource type. To continue learning about custom providers, see:

+* [Deploy associations for a custom provider using Azure Policy](./concepts-built-in-policy.md)

+* [Azure Custom Providers resource onboarding overview](./concepts-resource-onboarding.md)

+## Quick evaluation using metrics

+ Before going through the factors that impact the performance, let's first introduce an easy way to monitor the pressure of your service. There's a metrics called **Server Load** on the Portal.

+

+ <kbd></kbd>

+ It shows the computing pressure of your SignalR service. You could test on your own scenario and check this metrics to decide whether to scale up. The latency inside SignalR service would remain low if the Server Load is below 70%.

+

+> [!NOTE]

+> If you are using unit 50 or unit 100 **and** your scenario is mainly sending to small groups (group size <100) or single connection, you need to check [sending to small group](#small-group) or [sending to connection](#send-to-connection) for reference. In those scenarios there is large routing cost which is not included in the Server Load.

+

+ Below are detailed concepts for evaluating performance.

+#### Rename and delete a person

+## Optimize the ability of your model to recognize a person

+To optimize your model ability to recognize the person, upload as many different images as possible and from different angles. To get optimal results, use high resolution images.

+You can use the **Azure vNet connect** feature to use an existing vNet or create a new vNet to connect to Azure VMware Solution. **Azure vNet connect** is a function to configure vNet connectivity, it does not record configuration state; browse the Azure portal to check what settings have been configured.

+1. Validate solution design is within Azure VMware Solution limits (https://docs.microsoft.com/azure/azure-resource-manager/management/azure-subscription-service-limits).

+ Title: Tutorial - Visualize IoT device data from IoT Hub using Azure Web PubSub service and Azure Functions

+description: A tutorial to walk through how to use Azure Web PubSub service and Azure Functions to monitor device data from IoT Hub.

+# Tutorial: Visualize IoT device data from IoT Hub using Azure Web PubSub service and Azure Functions

+In this tutorial, you learn how to use Azure Web PubSub service and Azure Functions to build a serverless application with real-time data visualization from IoT Hub.

+In this tutorial, you learn how to:

+> [!div class="checklist"]

+> * Build a serverless data visualization app

+> * Work together with Web PubSub function input and output bindings and Azure IoT hub

+> * Run the sample functions locally

+## Prerequisites

+# [JavaScript](#tab/javascript)

+* A code editor, such as [Visual Studio Code](https://code.visualstudio.com/)

+* [Node.js](https://nodejs.org/en/download/), version 10.x.

+ > [!NOTE]

+ > For more information about the supported versions of Node.js, see [Azure Functions runtime versions documentation](../azure-functions/functions-versions.md#languages).

+* [Azure Functions Core Tools](https://github.com/Azure/azure-functions-core-tools#installing) (v3 or higher preferred) to run Azure Function apps locally and deploy to Azure.

+* The [Azure CLI](/cli/azure) to manage Azure resources.

+## Create a Web PubSub instance

+If you already have a Web PubSub instance in your Azure subscription, you can skip this section.

+## Create and run the functions locally

+1. Make sure you have [Azure Functions Core Tools](https://github.com/Azure/azure-functions-core-tools#installing) installed. And then create an empty directory for the project. Run command under this working directory.

+ # [JavaScript](#tab/javascript)

+ ```bash

+ func init --worker-runtime javascript

+ ```

+

+2. Update `host.json`'s `extensionBundle` to version larger than _3.3.0_ which contains Web PubSub support.

+```json

+{

+ "version": "2.0",

+ "extensionBundle": {

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

+ "version": "[3.3.*, 4.0.0)"

+ }

+}

+```

+3. Create an `index` function to read and host a static web page for clients.

+ ```bash

+ func new -n index -t HttpTrigger

+ ```

+ # [JavaScript](#tab/javascript)

+ - Update `index/index.js` with following code that serve the html content as a static site.

+ ```js

+ var fs = require("fs");

+ var path = require("path");

+ module.exports = function (context, req) {

+ let index = path.join(

+ context.executionContext.functionDirectory,

+ "https://docsupdatetracker.net/index.html"

+ );

+ fs.readFile(index, "utf8", function (err, data) {

+ if (err) {

+ console.log(err);

+ context.done(err);

+ return;

+ }

+ context.res = {

+ status: 200,

+ headers: {

+ "Content-Type": "text/html",

+ },

+ body: data,

+ };

+ context.done();

+ });

+ };

+ ```

+4. Create this _https://docsupdatetracker.net/index.html_ file under the same folder as file _index.js_:

+ ```html

+ <!doctype html>

+ <html lang="en">

+ <head>

+ <!-- Required meta tags -->

+ <meta charset="utf-8">

+ <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">

+ <script src="https://cdn.jsdelivr.net/npm/chart.js@2.8.0/dist/Chart.min.js" type="text/javascript"

+ charset="utf-8"></script>

+ <script>

+ document.addEventListener("DOMContentLoaded", async function (event) {

+ const res = await fetch(`/api/negotiate?id=${1}`);

+ const data = await res.json();

+ const webSocket = new WebSocket(data.url);

+ class TrackedDevices {

+ constructor() {

+ // key as the deviceId, value as the temperature array

+ this.devices = new Map();

+ this.maxLen = 50;

+ this.timeData = new Array(this.maxLen);

+ }

+ // Find a device temperature based on its Id

+ findDevice(deviceId) {

+ return this.devices.get(deviceId);

+ }

+ addData(time, temperature, deviceId, dataSet, options) {

+ let containsDeviceId = false;

+ this.timeData.push(time);

+ for (const [key, value] of this.devices) {

+ if (key === deviceId) {

+ containsDeviceId = true;

+ value.push(temperature);

+ } else {

+ value.push(null);

+ }

+ }

+ if (!containsDeviceId) {

+ const data = getRandomDataSet(deviceId, 0);

+ let temperatures = new Array(this.maxLen);

+ temperatures.push(temperature);

+ this.devices.set(deviceId, temperatures);

+ data.data = temperatures;

+ dataSet.push(data);

+ }

+ if (this.timeData.length > this.maxLen) {

+ this.timeData.shift();

+ this.devices.forEach((value, key) => {

+ value.shift();

+ })

+ }

+ }

+ getDevicesCount() {

+ return this.devices.size;

+ }

+ }

+ const trackedDevices = new TrackedDevices();

+ function getRandom(max) {

+ return Math.floor((Math.random() * max) + 1)

+ }

+ function getRandomDataSet(id, axisId) {

+ return getDataSet(id, axisId, getRandom(255), getRandom(255), getRandom(255));

+ }

+ function getDataSet(id, axisId, r, g, b) {

+ return {

+ fill: false,

+ label: id,

+ yAxisID: axisId,

+ borderColor: `rgba(${r}, ${g}, ${b}, 1)`,

+ pointBoarderColor: `rgba(${r}, ${g}, ${b}, 1)`,

+ backgroundColor: `rgba(${r}, ${g}, ${b}, 0.4)`,

+ pointHoverBackgroundColor: `rgba(${r}, ${g}, ${b}, 1)`,

+ pointHoverBorderColor: `rgba(${r}, ${g}, ${b}, 1)`,

+ spanGaps: true,

+ };

+ }

+ function getYAxy(id, display) {

+ return {

+ id: id,

+ type: "linear",

+ scaleLabel: {

+ labelString: display || id,

+ display: true,

+ },

+ position: "left",

+ };

+ }

+ // Define the chart axes

+ const chartData = { datasets: [], };

+ // Temperature (┬║C), id as 0

+ const chartOptions = {

+ responsive: true,

+ animation: {

+ duration: 250 * 1.5,

+ easing: 'linear'

+ },

+ scales: {

+ yAxes: [

+ getYAxy(0, "Temperature (┬║C)"),

+ ],

+ },

+ };

+ // Get the context of the canvas element we want to select

+ const ctx = document.getElementById("chart").getContext("2d");

+ chartData.labels = trackedDevices.timeData;

+ const chart = new Chart(ctx, {

+ type: "line",

+ data: chartData,

+ options: chartOptions,

+ });

+ webSocket.onmessage = function onMessage(message) {

+ try {

+ const messageData = JSON.parse(message.data);

+ console.log(messageData);

+ // time and either temperature or humidity are required

+ if (!messageData.MessageDate ||

+ !messageData.IotData.temperature) {

+ return;

+ }

+ trackedDevices.addData(messageData.MessageDate, messageData.IotData.temperature, messageData.DeviceId, chartData.datasets, chartOptions.scales);

+ const numDevices = trackedDevices.getDevicesCount();

+ document.getElementById("deviceCount").innerText =

+ numDevices === 1 ? `${numDevices} device` : `${numDevices} devices`;

+ chart.update();

+ } catch (err) {

+ console.error(err);

+ }

+ };

+ });

+ </script>

+ <style>

+ body {

+ font: 14px "Lucida Grande", Helvetica, Arial, sans-serif;

+ padding: 50px;

+ margin: 0;

+ text-align: center;

+ }

+ .flexHeader {

+ display: flex;

+ flex-direction: row;

+ flex-wrap: nowrap;

+ justify-content: space-between;

+ }

+ #charts {

+ display: flex;

+ flex-direction: row;

+ flex-wrap: wrap;

+ justify-content: space-around;

+ align-content: stretch;

+ }

+ .chartContainer {

+ flex: 1;

+ flex-basis: 40%;

+ min-width: 30%;

+ max-width: 100%;

+ }

+ a {

+ color: #00B7FF;

+ }

+ </style>

+ <title>Temperature Real-time Data</title>

+ </head>

+ <body>

+ <h1 class="flexHeader">

+ <span>Temperature Real-time Data</span>

+ <span id="deviceCount">0 devices</span>

+ </h1>

+ <div id="charts">

+ <canvas id="chart"></canvas>

+ </div>

+ </body>

+ </html>

+ ```

+5. Create a `negotiate` function to help clients get service connection url with access token.

+ ```bash

+ func new -n negotiate -t HttpTrigger

+ ```

+ # [JavaScript](#tab/javascript)

+ - Update `negotiate/function.json` to include input binding [`WebPubSubConnection`](reference-functions-bindings.md#input-binding), with the following json codes.

+ ```json

+ {

+ "bindings": [

+ {

+ "authLevel": "anonymous",

+ "type": "httpTrigger",

+ "direction": "in",

+ "name": "req"

+ },

+ {

+ "type": "http",

+ "direction": "out",

+ "name": "res"

+ },

+ {

+ "type": "webPubSubConnection",

+ "name": "connection",

+ "hub": "%hubName%",

+ "direction": "in"

+ }

+ ]

+ }

+ ```

+ - Update `negotiate/index.js` and to return the `connection` binding which contains the generated token.

+ ```js

+ module.exports = function (context, req, connection) {

+ // Add your own auth logic here

+ context.res = { body: connection };

+ context.done();

+ };

+ ```

+6. Create a `messagehandler` function to generate notifications with template `"IoT Hub (Event Hub)"`.

+ ```bash

+ func new --template "IoT Hub (Event Hub)" --name messagehandler

+ ```

+ # [JavaScript](#tab/javascript)

+ - Update _messagehandler/function.json_ to add [Web PubSub output binding](reference-functions-bindings.md#output-binding) with the following json code. Please note that we use variable `%hubName%` as the hub name for both IoT eventHubName and Web PubSub hub.

+ ```json

+ {

+ "bindings": [

+ {

+ "type": "eventHubTrigger",

+ "name": "IoTHubMessages",

+ "direction": "in",

+ "eventHubName": "%hubName%",

+ "connection": "IOTHUBConnectionString",

+ "cardinality": "many",

+ "consumerGroup": "$Default",

+ "dataType": "string"

+ },

+ {

+ "type": "webPubSub",

+ "name": "actions",

+ "hub": "%hubName%",

+ "direction": "out"

+ }

+ ]

+ }

+ ```

+ - Update `messagehandler/index.js` with the following code. It sends every message from IoT hub to every client connected to Web PubSub service using Web PubSub output bindings.

+ ```js

+ module.exports = function (context, IoTHubMessages) {

+ IoTHubMessages.forEach((message) => {

+ const deviceMessage = JSON.parse(message);

+ context.log(`Processed message: ${message}`);

+ context.bindings.actions = {

+ actionName: "sendToAll",

+ data: JSON.stringify({

+ IotData: deviceMessage,

+ MessageDate: deviceMessage.date || new Date().toISOString(),

+ DeviceId: deviceMessage.deviceId,

+ }),

+ };

+ });

+ context.done();

+ };

+ ```

+7. Update the Function settings

+

+ 1. Add `hubName` setting and replace `{YourIoTHubName}` with the hub name you used when creating your IoT Hub：

+ ```bash

+ func settings add hubName "{YourIoTHubName}"

+ ```

+ 2. Get the **Service Connection String** for IoT Hub using below CLI command:

+ ```azcli

+ az iot hub connection-string show --policy-name service --hub-name {YourIoTHubName} --output table --default-eventhub

+ ```

+ And set `IOTHubConnectionString` using below command, replacing `<iot-connection-string>` with the value:

+ ```bash

+ func settings add IOTHubConnectionString "<iot-connection-string>"

+ ```

+ 3. Get the **Connection String** for Web PubSub using below CLI command:

+ ```azcli

+ az webpubsub key show --name "<your-unique-resource-name>" --resource-group "<your-resource-group>" --query primaryConnectionString

+ ```

+ And set `WebPubSubConnectionString` using below command, replacing `<webpubsub-connection-string>` with the value:

+ ```bash

+ func settings add WebPubSubConnectionString "<webpubsub-connection-string>"

+ ```

+ > [!NOTE]

+ > `IoT Hub (Event Hub)` Function trigger used in the sample has dependency on Azure Storage, but you can use local storage emulator when the Function is running locally. If you got some error like `There was an error performing a read operation on the Blob Storage Secret Repository. Please ensure the 'AzureWebJobsStorage' connection string is valid.`, you'll need to download and enable [Storage Emulator](../storage/common/storage-use-emulator.md).

+8. Run the function locally

+ Now you're able to run your local function by command below.

+ ```bash

+ func start

+ ```

+ And checking the running logs, you can visit your local host static page by visiting: `https://localhost:7071/api/index`.

+## Run the device to send data

+### Register a device

+A device must be registered with your IoT hub before it can connect.

+If you already have a device registered in your IoT hub, you can skip this section.

+1. Run the [az iot hub device-identity create](/cli/azure/iot/hub/device-identity#az-iot-hub-device-identity-create) command in Azure Cloud Shell to create the device identity.

+ **YourIoTHubName**: Replace this placeholder below with the name you chose for your IoT hub.

+ ```azurecli-interactive

+ az iot hub device-identity create --hub-name {YourIoTHubName} --device-id simDevice

+ ```

+2. Run the [az iot hub device-identity connection-string show](/cli/azure/iot/hub/device-identity/connection-string#az-iot-hub-device-identity-connection-string-show) command in Azure Cloud Shell to get the _device connection string_ for the device you just registered:

+ **YourIoTHubName**: Replace this placeholder below with the name you chose for your IoT hub.

+ ```azurecli-interactive

+ az iot hub device-identity connection-string show --hub-name {YourIoTHubName} --device-id simDevice --output table

+ ```

+ Make a note of the device connection string, which looks like:

+ `HostName={YourIoTHubName}.azure-devices.net;DeviceId=simDevice;SharedAccessKey={YourSharedAccessKey}`

+- For quickest results, simulate temperature data using the [Raspberry Pi Azure IoT Online Simulator](https://azure-samples.github.io/raspberry-pi-web-simulator/#Getstarted). Paste in the **device connection string**, and select the **Run** button.

+- If you have a physical Raspberry Pi and BME280 sensor, you may measure and report real temperature and humidity values by following the [Connect Raspberry Pi to Azure IoT Hub (Node.js)](/azure/iot-hub/iot-hub-raspberry-pi-kit-node-get-started) tutorial.

+## Run the visualization website

+Open function host index page: `http://localhost:7071/api/index` to view the real-time dashboard. Register multiple devices and you can see the dashboard updates multiple devices in real-time. Open multiple browsers and you can see every page are updated in real-time.

+## Clean up resources

+## Next steps

+In this quickstart, you learned how to run a serverless chat application. Now, you could start to build your own application.

+> [!div class="nextstepaction"]

+> [Tutorial: Create a simple chatroom with Azure Web PubSub](https://azure.github.io/azure-webpubsub/getting-started/create-a-chat-app/js-handle-events)

+> [!div class="nextstepaction"]

+> [Azure Web PubSub bindings for Azure Functions](https://azure.github.io/azure-webpubsub/references/functions-bindings)

+> [!div class="nextstepaction"]

+> [Explore more Azure Web PubSub samples](https://github.com/Azure/azure-webpubsub/tree/main/samples)

+ :::image type="content" source="./media/backup-azure-manage-vms/select-all-services.png" alt-text="Screenshot showing to select All services.":::

+ :::image type="content" source="./media/backup-azure-manage-vms/all-services.png" alt-text="Screenshot showing to enter and choose Recovery Services vaults.":::

+ :::image type="content" source="./media/backup-azure-manage-vms/full-view-rs-vault.png" alt-text="Screenshot showing to open the vault dashboard and Settings pane.":::

+ :::image type="content" source="./media/backup-azure-manage-vms/azure-virtual-machine.png" alt-text="Screenshot showing to open the Backup Items tile.":::

+ :::image type="content" source="./media/backup-azure-manage-vms/backup-items-blade-select-item.png" alt-text="Screenshot showing to view the Backup Items pane.":::

+ :::image type="content" source="./media/backup-azure-manage-vms/item-dashboard-settings.png" alt-text="Screenshot showing the Backup Items dashboard and the Settings pane.":::

+ :::image type="content" source="./media/backup-azure-manage-vms/azure-virtual-machine.png" alt-text="Screenshot showing to open the Backup Items tile.":::

+ :::image type="content" source="./media/backup-azure-manage-vms/backup-items-blade-select-item.png" alt-text="Screenshot showing to view the Backup Items pane.":::

+ :::image type="content" source="./media/backup-azure-manage-vms/backup-policy-create-new.png" alt-text="Screenshot showing to choose a backup policy.":::

+ :::image type="content" source="./media/backup-azure-manage-vms/backup-now-button.png" alt-text="Screenshot showing the Backup now option.":::

+ :::image type="content" source="./media/backup-azure-manage-vms/backup-now-check.png" alt-text="Screenshot showing the Backup Now calendar.":::

+ :::image type="content" source="./media/backup-azure-manage-vms/retain-backup-data.png" alt-text="Screenshot showing to retain Backup data.":::

+ :::image type="content" source="./media/backup-azure-manage-vms/delete-backup-data.png" alt-text="Screenshot showing to delete backup data.":::

+ :::image type="content" source="./media/backup-azure-manage-vms/success-message.png" alt-text="Screenshot showing message indicating a successfully protected VM.":::

+ :::image type="content" source="./media/backup-azure-manage-vms/stop-backup-button.png" alt-text="Screenshot showing to select Stop backup.":::

+ :::image type="content" source="./media/backup-azure-manage-vms/delete-backup-button.png" alt-text="Screenshot showing to select Delete backup.":::

+ :::image type="content" source="./media/backup-azure-manage-vms/delete-backup-data.png" alt-text="Screenshot showing to delete backup data.":::

+To use the [REST API](/rest/api/load-balancer/load-balancers/swap-public-ip-addresses) to swap to a new cloud services deployment in Azure Cloud Services (extended support), use the following command and JSON configuration:

+| Chinese (Mandarin, Simplified) | `zh-CN` | Male | `zh-CN-YunjianNeural` ^New | Optimized for broadcasting sports event, 2 new multiple styles available [using SSML](speech-synthesis-markup.md#adjust-speaking-styles) |

+| Chinese (Mandarin, Simplified) | `zh-CN` | Male | `zh-CN-YunhaoNeural` ^New | Optimized for promoting a product or service, 1 new multiple style available [using SSML](speech-synthesis-markup.md#adjust-speaking-styles) |

+| Chinese (Mandarin, Simplified) | `zh-CN` | Male | `zh-CN-YunfengNeural` ^New | General, multiple styles available [using SSML](speech-synthesis-markup.md#adjust-speaking-styles) |

+| English (United Kingdom) | `en-GB` | Female | `en-GB-AbbiNeural` | General |

+| English (United Kingdom) | `en-GB` | Female | `en-GB-BellaNeural` | General |

+| English (United Kingdom) | `en-GB` | Female | `en-GB-HollieNeural` | General |

+| English (United Kingdom) | `en-GB` | Female | `en-GB-OliviaNeural` | General |

+| English (United Kingdom) | `en-GB` | Female | `en-GB-MaisieNeural` | General, child voice |

+| English (United Kingdom) | `en-GB` | Male | `en-GB-AlfieNeural` | General |

+| English (United Kingdom) | `en-GB` | Male | `en-GB-ElliotNeural` | General |

+| English (United Kingdom) | `en-GB` | Male | `en-GB-EthanNeural` | General |

+| English (United Kingdom) | `en-GB` | Male | `en-GB-NoahNeural` | General |

+| English (United Kingdom) | `en-GB` | Male | `en-GB-OliverNeural` | General |

+| English (United Kingdom) | `en-GB` | Male | `en-GB-ThomasNeural` | General |

+| English (United States) | `en-US` | Male | `en-US-DavisNeural` ^New | General, multiple voice styles available [using SSML](speech-synthesis-markup.md#adjust-speaking-styles) |

+| English (United States) | `en-US` | Female | `en-US-JaneNeural` ^New | General, multiple voice styles available [using SSML](speech-synthesis-markup.md#adjust-speaking-styles) |

+| English (United States) | `en-US` | Male | `en-US-JasonNeural` ^New | General, multiple voice styles available [using SSML](speech-synthesis-markup.md#adjust-speaking-styles) |

+| English (United States) | `en-US` | Female | `en-US-NancyNeural` ^New | General, multiple voice styles available [using SSML](speech-synthesis-markup.md#adjust-speaking-styles) |

+| English (United States) | `en-US` | Male | `en-US-TonyNeural` ^New | General, multiple voice styles available [using SSML](speech-synthesis-markup.md#adjust-speaking-styles) |

+| French (France) | `fr-FR` | Female | `fr-FR-BrigitteNeural` | General |

+| French (France) | `fr-FR` | Female | `fr-FR-CelesteNeural` | General |

+| French (France) | `fr-FR` | Female | `fr-FR-CoralieNeural` | General |

+| French (France) | `fr-FR` | Female | `fr-FR-JacquelineNeural` | General |

+| French (France) | `fr-FR` | Female | `fr-FR-JosephineNeural` | General |

+| French (France) | `fr-FR` | Female | `fr-FR-YvetteNeural` | General |

+| French (France) | `fr-FR` | Female | `fr-FR-EloiseNeural` | General, child voice |

+| French (France) | `fr-FR` | Male | `fr-FR-AlainNeural` | General |

+| French (France) | `fr-FR` | Male | `fr-FR-ClaudeNeural` | General |

+| French (France) | `fr-FR` | Male | `fr-FR-JeromeNeural` | General |

+| French (France) | `fr-FR` | Male | `fr-FR-MauriceNeural` | General |

+| French (France) | `fr-FR` | Male | `fr-FR-YvesNeural` | General |

+| German (Germany) | `de-DE` | Female | `de-DE-AmalaNeural` | General |

+| German (Germany) | `de-DE` | Female | `de-DE-ElkeNeural` | General |

+| German (Germany) | `de-DE` | Female | `de-DE-KlarissaNeural` | General |

+| German (Germany) | `de-DE` | Female | `de-DE-LouisaNeural` | General |

+| German (Germany) | `de-DE` | Female | `de-DE-MajaNeural` | General |

+| German (Germany) | `de-DE` | Female | `de-DE-TanjaNeural` | General |

+| German (Germany) | `de-DE` | Female | `de-DE-GiselaNeural` | General, child voice |

+| German (Germany) | `de-DE` | Male | `de-DE-BerndNeural` | General |

+| German (Germany) | `de-DE` | Male | `de-DE-ChristophNeural` | General |

+| German (Germany) | `de-DE` | Male | `de-DE-KasperNeural` | General |

+| German (Germany) | `de-DE` | Male | `de-DE-KillianNeural` | General |

+| German (Germany) | `de-DE` | Male | `de-DE-KlausNeural` | General |

+| German (Germany) | `de-DE` | Male | `de-DE-RalfNeural` | General |

+|en-US-DavisNeural ^{Public preview}|`angry`, `chat`, `cheerful`, `excited`, `friendly`, `hopeful`, `sad`, `shouting`, `terrified`, `unfriendly`, `whispering`|||

+|en-US-JaneNeural ^{Public preview}|`angry`, `cheerful`, `excited`, `friendly`, `hopeful`, `sad`, `shouting`, `terrified`, `unfriendly`, `whispering`|||

+|en-US-JasonNeural ^{Public preview}|`angry`, `cheerful`, `excited`, `friendly`, `hopeful`, `sad`, `shouting`, `terrified`, `unfriendly`, `whispering`|||

+|en-US-NancyNeural ^{Public preview}|`angry`, `cheerful`, `excited`, `friendly`, `hopeful`, `sad`, `shouting`, `terrified`, `unfriendly`, `whispering`|||

+|en-US-TonyNeural ^{Public preview}|`angry`, `cheerful`, `excited`, `friendly`, `hopeful`, `sad`, `shouting`, `terrified`, `unfriendly`, `whispering`|||

+|fr-FR-DeniseNeural |`cheerful`, `sad`|||

+|zh-CN-YunjianNeural ^{Public preview}|`narration-relaxed`, `sports-commentary` ^{Public preview}, `sports-commentary-excited` ^{Public preview}|Supported||

+|zh-CN-YunhaoNeural ^{Public preview}|`general`, `advertisement-upbeat` ^{Public preview}|Supported||

+|zh-CN-YunfengNeural ^{Public preview}|`calm`, `angry`, ` disgruntled`, `cheerful`, `fearful`, `sad`, `serious`, `depressed`|Supported||

+⁵ See [additional explanations](#detailed-description-quota-adjustment-and-best-practices), [best practices](#general-best-practices-to-mitigate-throttling-during-autoscaling), and [adjustment instructions](#text-to-speech-increase-concurrent-request-limit).<br/>

+### Text-to-speech: increase concurrent request limit

+For the standard pricing tier, you can increase this amount. Before submitting the request, ensure that you're familiar with the material discussed earlier in this article, such as the best practices to mitigate throttling.

+|`style="advertisement-upbeat"`|Expresses an excited and high-energy tone for promoting a product or service.|

+|`style="sports-commentary"`|Expresses a relaxed and interesting tone for broadcasting a sports event.|

+|`style="sports-commentary-excited"`|Expresses an intensive and energetic tone for broadcasting exciting moments in a sports event.|

+## How do I control the none intent?

+You can control the none intent threshhold from UI through the project settings, by changing the none inten threshold value. The values can be between 0.0 and 1.0. Also, you can change this threshold from the APIs by changing the *confidenceThreshold* in settings object. Learn more about [none intent](./concepts/none-intent.md#none-score-threshold)

+8. You can review the knowledge bases you plan to migrate. There could be some validation errors in project names as we follow stricter validation rules for custom question answering projects. To resolve these errors occuring due to invalid characters, select the checkbox (in red) and click **Next**. This is a one-click method to replace the problematic charcaters in the name with the accepted characters. If there's a duplicate, a new unique project name is generated by the system.

+ > 

+9. After resolving the validation errors, select **Start migration**

+ > 

+[Fortanix](https://www.fortanix.com/) has portal and Command Line Interface (CLI) experiences to convert their containerized applications to SGX-capable confidential containers. You don't need to modify or recompile the application. Fortanix provides the flexibility to run and manage a broad set of applications. You can use existing applications, new enclave-native applications, and pre-packaged applications. Start with Fortanix's [Enclave Manager](https://em.fortanix.com/) UI or [REST APIs](https://www.fortanix.com/api/). Create confidential containers using the Fortanix's [quickstart guide for AKS](https://hubs.li/Q017JnNt0).

+Here's more information about the outputs from an HTTP trigger or action, which returns this information:

+* [TLS/SSL certificate](#tls-ssl-certificate-authentication): Add the app setting, `WEBSITE_LOAD_ROOT_CERTIFICATES`, and set the value to the thumbprint for your TLS/SSL certificate.

+Here's the same example that shows the HTTP action's JSON definition in the underlying workflow definition:

+Here's the same example that shows the HTTP action response that contains `Retry-After`:

+## Pagination support

+Sometimes, the target service responds by returning the results one page at a time. If the response specifies the next page with the **nextLink** or **@odata.nextLink** property, you can turn on the **Pagination** setting on the HTTP action. This setting causes the HTTP action to automatically follow these links and get the next page. However, if the response specifies the next page with any other tag, you might have to add a loop to your workflow. Make this loop follow that tag and manually get each page until the tag is null.

+ Title: Schedule and run recurring workflows

+description: Schedule and run recurring workflows with the generic Recurrence trigger in Azure Logic Apps.

+# Schedule and run recurring workflows with the Recurrence trigger in Azure Logic Apps

+To start and run your workflow on a schedule, you can use the generic Recurrence trigger as the first step. You can set a date, time, and time zone for starting the workflow and a recurrence for repeating that workflow. The following list includes some patterns that this trigger supports along with more advanced recurrences and complex schedules:

+* Run at a specific date and time, then repeat every *n* number of seconds, minutes, hours, days, weeks, or months.

+* Run immediately and repeat daily at one or more specific times, such as 8:00 AM and 5:00 PM.

+* Run immediately and repeat weekly on specific days, such as Saturday and Sunday.

+* Run immediately and repeat weekly on specific days and times, such as Monday through Friday at 8:00 AM and 5:00 PM.

+> [!NOTE]

+>

+> To start and run your workflow only once in the future, use workflow template named

+> **Scheduler: Run Once Jobs**. This template uses the Request trigger and HTTP action,

+> rather than the Recurrence trigger, which doesn't support this recurrence pattern.

+> For more information, see [Run jobs one time only](../logic-apps/concepts-schedule-automated-recurring-tasks-workflows.md#run-once).

+The Recurrence trigger isn't associated with any specific service, so you can use the trigger with almost any workflow, such as [Consumption logic app workflows and Standard logic app *stateful* workflows](../logic-apps/logic-apps-overview.md#resource-environment-differences). This trigger is currently unavailable for [Standard logic app *stateless* workflows](../logic-apps/logic-apps-overview.md#resource-environment-differences).

+The Recurrence trigger is part of the built-in Schedule connector and runs natively on the Azure Logic Apps runtime. For more information about the built-in Schedule triggers and actions, see [Schedule and run recurring automated, tasks, and workflows with Azure Logic Apps](../logic-apps/concepts-schedule-automated-recurring-tasks-workflows.md).

+* Basic knowledge about [logic app workflows](../logic-apps/logic-apps-overview.md). If you're new to logic apps, learn [how to create your first logic app workflow](../logic-apps/quickstart-create-first-logic-app-workflow.md).

+<a name="add-recurrence-trigger"></a>

+1. In the [Azure portal](https://portal.azure.com), create a blank logic app and workflow.

+ > [!NOTE]

+ >

+ > If you created a Standard logic app workflow, make sure to create a *stateful* workflow.

+ > The Recurrence trigger is currently unavailable for stateless workflows.

+1. In the designer, follow the corresponding steps, based on whether your logic app workflow is [Consumption or Standard](../logic-apps/logic-apps-overview.md#resource-environment-differences).

+ **Consumption**

+ 1. On the designer, under the search box, select **Built-in**.

+ 1. In the search box, enter **recurrence**.

+ 1. From the triggers list, select the trigger named **Recurrence**.

+ 

+ **Standard**

+ 1. On the designer, select **Choose operation**.

+ 1. On the **Add a trigger** pane, under the search box, select **Built-in**.

+ 1. In the search box, enter **recurrence**.

+ 1. From the triggers list, select the trigger named **Recurrence**.

+ 

+1. Set the interval and frequency for the recurrence. In this example, set these properties to run your workflow every week, for example:

+ **Consumption**

+ 

+ **Standard**

+ 

+ | **Interval** | `interval` | Yes | Integer | A positive integer that describes how often the workflow runs based on the frequency. Here are the minimum and maximum intervals: <br><br>- Month: 1-16 months <br>- Week: 1-71 weeks <br>- Day: 1-500 days <br>- Hour: 1-12,000 hours <br>- Minute: 1-72,000 minutes <br>- Second: 1-9,999,999 seconds<br><br>For example, if the interval is 6, and the frequency is "Month", then the recurrence is every 6 months. |

+ > If you use the **Day**, **Week**, or **Month** frequency, and you specify a future date and time,

+ > make sure that you set up the recurrence in advance. Otherwise, the workflow might skip the first recurrence.

+ > If a recurrence doesn't specify a specific [start date and time](../logic-apps/concepts-schedule-automated-recurring-tasks-workflows.md#start-time),

+ > the first recurrence runs immediately when you save or deploy the logic app, despite your trigger's recurrence setup. To avoid this behavior,

+ > provide a start date and time for when you want the first recurrence to run.

+ > the frequency is in days or longer, try the following options:

+ > * Provide a start date and time for the recurrence and the specific times to run subsequent recurrences. You can use the

+ > properties named **At these hours** and **At these minutes**, which are available only for the **Day** and **Week** frequencies.

+ > * For Consumption logic app workflows, use the [Sliding Window trigger](../connectors/connectors-native-sliding-window.md),

+ > rather than the Recurrence trigger.

+ **Consumption**

+ 

+ **Standard**

+ 

+ | **Start time** | `startTime` | No | String | Provide a start date and time, which has a maximum of 49 years in the future and must follow the [ISO 8601 date time specification](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) in [UTC date time format](https://en.wikipedia.org/wiki/Coordinated_Universal_Time), but without a [UTC offset](https://en.wikipedia.org/wiki/UTC_offset): <br><br>YYYY-MM-DDThh:mm:ss if you select a time zone <br><br>-or- <br><br>YYYY-MM-DDThh:mm:ssZ if you don't select a time zone <br><br>So for example, if you want September 18, 2020 at 2:00 PM, then specify "2020-09-18T14:00:00" and select a time zone such as Pacific Standard Time. Or, specify "2020-09-18T14:00:00Z" without a time zone. <br><br>**Important:** If you don't select a time zone, you must add the letter "Z" at the end without any spaces. This "Z" refers to the equivalent [nautical time](https://en.wikipedia.org/wiki/Nautical_time). If you select a time zone value, you don't need to add a "Z" to the end of your **Start time** value. If you do, Logic Apps ignores the time zone value because the "Z" signifies a UTC time format. <br><br>For simple schedules, the start time is the first occurrence, while for complex schedules, the trigger doesn't fire any sooner than the start time. [*What are the ways that I can use the start date and time?*](../logic-apps/concepts-schedule-automated-recurring-tasks-workflows.md#start-time) |

+ | **At these hours** | `hours` | No | Integer or integer array | If you select "Day" or "Week", you can select one or more integers from 0 to 23 as the hours of the day for when you want to run the workflow. <br><br>For example, if you specify "10", "12" and "14", you get 10 AM, 12 PM, and 2 PM for the hours of the day, but the minutes of the day are calculated based on when the recurrence starts. To set specific minutes of the day, for example, 10:00 AM, 12:00 PM, and 2:00 PM, specify those values by using the property named **At these minutes**. |

+ | **At these minutes** | `minutes` | No | Integer or integer array | If you select "Day" or "Week", you can select one or more integers from 0 to 59 as the minutes of the hour when you want to run the workflow. <br><br>For example, you can specify "30" as the minute mark and using the previous example for hours of the day, you get 10:30 AM, 12:30 PM, and 2:30 PM. <br><br>**Note**: Sometimes, the timestamp for the triggered run might vary up to 1 minute from the scheduled time. If you need to pass the timestamp exactly as scheduled to subsequent actions, you can use template expressions to change the timestamp accordingly. For more information, see [Date and time functions for expressions](../logic-apps/workflow-definition-language-functions-reference.md#date-time-functions). |

+ For example, suppose that today is Friday, September 4, 2020. The following Recurrence trigger doesn't fire *any sooner* than the specified start date and time, which is Friday, September 18, 2020 at 8:00 AM Pacific Time. However, the recurrence schedule is set for 10:30 AM, 12:30 PM, and 2:30 PM on Mondays only. The first time that the trigger fires and creates a workflow instance is on Monday at 10:30 AM. To learn more about how start times work, see these [start time examples](../logic-apps/concepts-schedule-automated-recurring-tasks-workflows.md#start-time).

+ >

+ **Consumption**

+ 

+ **Standard**

+ 

+1. Now continue building your workflow with other actions. For more actions that you can add, see [Connectors for Azure Logic Apps](../connectors/apis-list.md).

+You can view how the [Recurrence trigger definition](../logic-apps/logic-apps-workflow-actions-triggers.md#recurrence-trigger) appears with your chosen options by reviewing the underlying JSON definition for your workflow in Consumption logic apps and Standard logic apps (stateful only).

+Based on whether your logic app is Consumption or Standard, choose one of the following options:

+* **Consumption**: On the designer toolbar, select **Code view**. To return to the designer, on the code view editor toolbar, select **Designer**.

+* **Standard**: On the workflow menu, select **Code view**. To return to the designer, on the workflow menu, select **Designer**.

+The following example shows how a Recurrence trigger definition might appear in the workflow's underlying JSON definition:

+> * Deploy a Container Apps environment to host container apps

+Once your Azure Blob Storage account is created, you'll create a template where these storage parameters will use environment variable values. The values are passed in via the `parameters` argument when you deploy your apps with the `az deployment group create` command.

+- `storage_account_name` uses the value of the `STORAGE_ACCOUNT` variable.

+- `storage_container_name` uses the value of the `STORAGE_ACCOUNT_CONTAINER` variable. Dapr creates a container with this name when it doesn't already exist in your Azure Storage account.

+Create an ARM template to deploy a Container Apps environment including:

+* the associated Log Analytics workspace

+* Application Insights resource for distributed tracing

+* a dapr component for the state store

+* two dapr-enabled container apps

+Create a bicep template to deploy a Container Apps environment including:

+* the associated Log Analytics workspace

+* Application Insights resource for distributed tracing

+* a dapr component for the state store

+* the two dapr-enabled container apps

+ cpu: json('0.5')

+ cpu: json('0.5')

+- the Container Apps environment and associated Log Analytics workspace for hosting the hello world dapr solution

+Once you're done, run the following command to delete your resource group along with all the resources you created in this tutorial.

+Now create an instance of the virtual network to associate with the Container Apps environment. The virtual network must have two subnets available for the container app instance.

+| `name` | Name of the Container Apps environment. |

+| `logs-workspace-id` | (Optional) The ID of an existing the Log Analytics workspace. If omitted, a workspace will be created for you. |

+| `logs-workspace-key` | The Log Analytics client secret. Required if using an existing workspace. |

+| `internal-only` | (Optional) The environment doesn't use a public static IP, only internal IP addresses available in the custom VNET. (Requires an infrastructure subnet resource ID.) |

+With your environment created using your custom virtual network, you can deploy container apps into the environment using the `az containerapp create` command.

+| `platform-reserved-dns-ip` | An IP address from the `platform-reserved-cidr` range that is used for the internal DNS server. The address can't be the first address in the range, or the network address. For example, if `platform-reserved-cidr` is set to `10.2.0.0/16`, then `platform-reserved-dns-ip` can't be `10.2.0.0` (the network address), or `10.2.0.1` (infrastructure reserves use of this IP). In this case, the first usable IP for the DNS would be `10.2.0.2`. |

+If you're not going to continue to use this application, you can delete the Azure Container Apps instance and all the associated services by removing the **my-container-apps** resource group. Deleting this resource group will also delete the resource group automatically created by the Container Apps service containing the custom network components.

+- For more information about configuring your private endpoints, see [What is Azure Private Endpoint](../private-link/private-endpoint-overview.md).

+| `name` | Name of the Container Apps environment. |

+| `platform-reserved-dns-ip` | An IP address from the `platform-reserved-cidr` range that is used for the internal DNS server. The address can't be the first address in the range, or the network address. For example, if `platform-reserved-cidr` is set to `10.2.0.0/16`, then `platform-reserved-dns-ip` can't be `10.2.0.0` (the network address), or `10.2.0.1` (infrastructure reserves use of this IP). In this case, the first usable IP for the DNS would be `10.2.0.2`. |

+If you're not going to continue to use this application, you can delete the Azure Container Apps instance and all the associated services by removing the **my-container-apps** resource group. Deleting this resource group will also delete the resource group automatically created by the Container Apps service containing the custom network components.

+- For more information about configuring your private endpoints, see [What is Azure Private Endpoint](../private-link/private-endpoint-overview.md).

+description: Introduction to the Azure Container Registry service, providing cloud-based, managed registries.

+# Introduction to Container registries in Azure

+Azure Container Registry is a managed registry service based on the open-source Docker Registry 2.0. Create and maintain Azure container registries to store and manage your container images and related artifacts.

+ Title: Use a managed identity to access Azure Key Vault from Azure Cosmos DB

+description: Use managed identity in Azure Cosmos DB to access Azure Key Vault.

+ms.devlang: csharp

+# Access Azure Key Vault from Azure Cosmos DB using a managed identity

+Azure Cosmos DB may need to read secret/key data from Azure Key Vault. For example, your Azure Cosmos DB may require a customer-managed key stored in Azure Key Vault. To do this, Azure Cosmos DB should be configured with a managed identity, and then an Azure Key Vault access policy should grant the managed identity access.

+## Prerequisites

+- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).

+- An existing Azure Cosmos DB SQL API account. [Create an Azure Cosmos DB SQL API account](sql/create-cosmosdb-resources-portal.md)

+- An existing Azure Key Vault resource. [Create a key vault using the Azure CLI](../key-vault/general/quick-create-cli.md)

+- To perform the steps in this article, install the [Azure CLI](/cli/azure/install-azure-cli) and [sign in to Azure](/cli/azure/authenticate-azure-cli).

+## Prerequisite check

+1. In a terminal or command window, store the names of your Azure Key Vault resource, Azure Cosmos DB account and resource group as shell variables named ``keyVaultName``, ``cosmosName``, and ``resourceGroupName``.

+ ```azurecli-interactive

+ # Variable for function app name

+ keyVaultName="msdocs-keyvault"

+

+ # Variable for Cosmos DB account name

+ cosmosName="msdocs-cosmos-app"

+ # Variable for resource group name

+ resourceGroupName="msdocs-cosmos-keyvault-identity"

+ ```

+ > [!NOTE]

+ > These variables will be re-used in later steps. This example assumes your Azure Cosmos DB account name is ``msdocs-cosmos-app``, your key vault name is ``msdocs-keyvault`` and your resource group name is ``msdocs-cosmos-keyvault-identity``.

+## Create a system-assigned managed identity in Azure Cosmos DB

+First, create a system-assigned managed identity for the existing Azure Cosmos DB account.

+> [!IMPORTANT]

+> This how-to guide assumes that you are using a system-assigned managed identity. Many of the steps are similar when using a user-assigned managed identity.

+1. Run [``az cosmosdb identity assign``](/cli/azure/cosmosdb/identity#az-cosmosdb-identity-assign) to create a new system-assigned managed identity.

+ ```azurecli-interactive

+ az cosmosdb identity assign \

+ --resource-group $resourceGroupName \

+ --name $cosmosName

+ ```

+1. Retrieve the metadata of the system-assigned managed identity using [``az cosmosdb identity show``](/cli/azure/cosmosdb/identity#az-cosmosdb-identity-show), filter to just return the ``principalId`` property using the **query** parameter, and store the result in a shell variable named ``principal``.

+ ```azurecli-interactive

+ principal=$(

+ az cosmosdb identity show \

+ --resource-group $resourceGroupName \

+ --name $cosmosName \

+ --query principalId \

+ --output tsv

+ )

+ echo $principal

+ ```

+ > [!NOTE]

+ > This variable will be re-used in a later step.

+## Create an Azure Key Vault access policy

+In this step, create an access policy in Azure Key Vault using the previously managed identity.

+1. Use the [``az keyvault set-policy``](/cli/azure/keyvault#az-keyvault-set-policy) command to create an access policy in Azure Key Vault that gives the Azure Cosmos DB managed identity permission to access Key Vault. Specifically, the policy will use the **key-permissions** parameters to grant permissions to ``get``, ``list``, and ``import`` keys.

+ ```azurecli-itneractive

+ az keyvault set-policy \

+ --name $keyVaultName \

+ --object-id $principal \

+ --key-permissions get list import

+ ```

+## Next steps

+* To use customer-managed keys in Azure Key Vault with your Azure Cosmos account, see [configure customer-managed keys](how-to-setup-cmk.md#using-managed-identity)

+* To use Azure Key Vault to manage secrets, see [secure credentials](access-secrets-from-keyvault.md).

+# Secure Azure Cosmos credentials using Azure Key Vault

+> The recommended solution to access Azure Cosmos DB is to use a [system-assigned managed identity](managed-identity-based-authentication.md). If your service cannot take advantage of managed identities then use the [cert based solution](certificate-based-authentication.md). If both the managed identity solution and cert based solution do not meet your needs, please use the key vault solution below.

+When using Azure Cosmos DB, you can access the database, collections, documents by using the endpoint and the key within the app's configuration file. However, it's not safe to put keys and URL directly in the application code because they're available in clear text format to all the users. You want to make sure that the endpoint and keys are available but through a secured mechanism. This scenario is where Azure Key Vault can help you to securely store and manage application secrets.

+ * **Subscription:** Choose the subscription that you'll use.

+ * Within **Resource Group**, choose **Create new** and enter a resource group name.

+ :::image type="content" source="./media/access-secrets-from-keyvault/create-a-secret.png" alt-text="Screenshot of the Create a secret dialog in the Azure portal.":::

+4. After the secret is created, open it and copy the **Secret Identifier that is in the following format. You'll use this identifier in the next section.

+1. Create an Azure web application or you can download the app from the [GitHub repository](https://github.com/Azure/azure-cosmos-dotnet-v2/tree/master/Demo/keyvaultdemo). It's a simple MVC application.

+4. Next deploy the application to Azure. Open the context menu for the project and choose **publish**. Create a new app service profile (you can name the app WebAppKeyVault1) and select **Publish**.

+5. Once the application is deployed from the Azure portal, navigate to web app that you deployed, and turn on the **Managed service identity** of this application.

+ :::image type="content" source="./media/access-secrets-from-keyvault/turn-on-managed-service-identity.png" alt-text="Screenshot of the Managed service identity page in the Azure portal.":::

+If you run the application now, you'll see the following error, as you have not given any permission to this application in Key Vault.

+* To configure a firewall for Azure Cosmos DB, see [firewall support](how-to-configure-firewall.md) article.

+| Maximum storage per container (SQL API, Mongo API, Table API, Gremlin API)| 1 TB |

+| Maximum storage per container (Cassandra API)| 1 TB |

+| Maximum number of regional failovers | 10/hour by default. ¹ ² |

+Similarly, if you configured [customer-managed keys on analytical store](how-to-setup-cmk.md#is-it-possible-to-use-customer-managed-keys-with-the-azure-cosmos-db-analytical-store), you must directly enable it on the Synapse workspace primary storage account, which is the partitioned store, as well.

+- [Azure CLI](/cli/azure/cosmosdb/service?view=azure-cli-latest&preserve-view=true#az-cosmosdb-service-create)

+Graphlytic is compatible with Azure Cosmos DB and can be deployed to Azure in minutes. GraphlyticΓÇÖs UI can be customized and extended in many ways, for instance the default [visualization configuration](https://graphlytic.biz/doc/latest/Visualization_Settings.html), [data schema](https://graphlytic.biz/doc/latest/Data_Schema.html), [style mappings](https://graphlytic.biz/doc/latest/Style_Mappers.html), [virtual properties](https://graphlytic.biz/doc/latest/Virtual_properties.html) in the visualization, or custom implemented [widgets](https://graphlytic.biz/doc/latest/Widgets.html) that can enhance the visualization features with bespoke reports or integrations.

+This access policy ensures that your encryption keys can be accessed by your Azure Cosmos DB account. The access policy is implemented by granting access to a specific Azure Active Directory (AD) identity. Two types of identities are supported:

+1. If the system-assigned managed identity wasn't configured during account creation, [enable a system-assigned managed identity](./how-to-setup-managed-identity.md#add-a-system-assigned-identity) on your account and copy the `principalId` that got assigned.

+1. Add a new access policy to your Azure Key Vault account as described [above](#add-access-policy), but using the `principalId` you copied at the previous step instead of Azure Cosmos DB's first-party identity.

+1. Update your Azure Cosmos DB account to specify that you want to use the system-assigned managed identity when accessing your encryption keys in Azure Key Vault. You have two options:

+ - Specify the property in your account's Azure Resource Manager template:

+ ```json

+ {

+ "type": " Microsoft.DocumentDB/databaseAccounts",

+ "properties": {

+ "defaultIdentity": "SystemAssignedIdentity",

+ // ...

+ },

+ }

+ ```

+ - Update your account with the Azure CLI:

+ ```azurecli

+ resourceGroupName='myResourceGroup'

+ accountName='mycosmosaccount'

+

+ az cosmosdb update --resource-group $resourceGroupName --name $accountName --default-identity "SystemAssignedIdentity"

+ ```

+1. When creating your Azure Cosmos DB account, you must enable the user-assigned managed identity and specify that you want to use this identity when accessing your encryption keys in Azure Key Vault. Options include:

+ - Using an Azure Resource Manager template:

+

+ ```json

+ {

+ "type": "Microsoft.DocumentDB/databaseAccounts",

+ "identity": {

+ "type": "UserAssigned",

+ "userAssignedIdentities": {

+ "<identity-resource-id>": {}

+ }

+ },

+ "properties": {

+ "defaultIdentity": "UserAssignedIdentity=<identity-resource-id>"

+ "keyVaultKeyUri": "<key-vault-key-uri>"

+ // ...

+ }

+ ```

+ - Using the Azure CLI:

+ ```azurecli

+ resourceGroupName='myResourceGroup'

+ accountName='mycosmosaccount'

+ keyVaultKeyUri = 'https://<my-vault>.vault.azure.net/keys/<my-key>'

+

+ az cosmosdb create \

+ -n $accountName \

+ -g $resourceGroupName \

+ --key-uri $keyVaultKeyUri

+ --assign-identity <identity-resource-id>

+ --default-identity "UserAssignedIdentity=<identity-resource-id>"

+ ```

+The data you store in your Azure Cosmos DB account when using customer-managed keys ends up being encrypted twice:

+- Once through the extra encryption performed with customer-managed keys.

+Double encryption only applies to the main Azure Cosmos DB transactional storage. Some features involve internal replication of your data to a second tier of storage where double encryption isn't provided, even with customer-managed keys. These features include:

+- [Azure Synapse Link](./synapse-link.md)

+ :::image type="content" source="./media/how-to-setup-cmk/portal-akv-rot.png" alt-text="Screenshot of the New Version option in the Versions page of the Azure portal.":::

+- Swap the key currently used with a different one by updating the key URI on your account. From the Azure portal, go to your Azure Cosmos account and select **Data Encryption** from the left menu:

+ :::image type="content" source="./media/how-to-setup-cmk/portal-data-encryption.png" alt-text="Screenshot of the Data Encryption menu option in the Azure portal.":::

+ :::image type="content" source="./media/how-to-setup-cmk/portal-key-swap.png" alt-text="Screenshot of the Save option in the Key page of the Azure portal.":::

+If there are any errors with customer-managed keys in Azure Cosmos DB, Azure Cosmos DB returns the error details along with an HTTP substatus code in the response. You can use the HTTP substatus code to debug the root cause of the issue. See the [HTTP Status Codes for Azure Cosmos DB](/rest/api/cosmos-db/http-status-codes-for-cosmosdb) article to get the list of supported HTTP substatus codes.

+### Are there more charges to enable customer-managed keys?

+### How do customer-managed keys influence capacity planning?

+[Request Units](./request-units.md) consumed by your database operations see an increase to reflect the extra processing required to perform encryption and decryption of your data when using customer-managed keys. The extra RU consumption may lead to slightly higher utilization of your provisioned capacity. Use the table below for guidance:

+### Is it possible to use customer-managed keys with the Azure Cosmos DB [analytical store](analytical-store-introduction.md)?

+Yes, Azure Synapse Link only supports configuring customer-managed keys using your Azure Cosmos DB account's managed identity. You must [use your Azure Cosmos DB account's managed identity](#using-managed-identity) in your Azure Key Vault access policy before [enabling Azure Synapse Link](configure-synapse-link.md#enable-synapse-link) on your account. For a how-to guide on how to enable managed identity and use it in an access policy, see [access Azure Key Vault from Azure Cosmos DB using a managed identity](access-key-vault-managed-identity.md).

+- The encryption key that you used at the time of the backup is required and must be available in Azure Key Vault. This condition requires that no revocation was made and the version of the key that was used at the time of the backup is still enabled.

+- If you [used a system-assigned managed identity in the access policy](#to-use-a-system-assigned-managed-identity), temporarily [grant access to the Azure Cosmos DB first-party identity](#add-access-policy) before restoring your data. This requirement exists because a system-assigned managed identity is specific to an account and can't be reused in the target account. Once the data is fully restored to the target account, you can set your desired identity configuration and remove the first-party identity from the Key Vault access policy.

+Azure Cosmos DB gives you the option to configure [continuous backups](./continuous-backup-restore-introduction.md) on your account. With continuous backups, you can restore your data to any point in time within the past 30 days. To use continuous backups on an account where customer-managed keys are enabled, you must [use a user-assigned managed identity](#to-use-a-user-assigned-managed-identity) in the Key Vault access policy. Azure Cosmos DB first-party identities or system-assigned managed identities aren't currently supported on accounts using continuous backups.

+- The encryption key that you used at the time of the backup is required and must be available in Azure Key Vault. This requirement means that no revocation was made and the version of the key that was used at the time of the backup is still enabled.

+- [In Python](/python/api/overview/azure/identity-readme?view=azure-python&preserve-view=true#credential-classes)

+### 2.14.7 (May 9, 2022)

+ - This release updates the Azure Cosmos DB Emulator background services to match the latest online functionality of the Azure Cosmos DB. In addition to this update there are couple issues that were addressed in this release:

+ * Update Data Explorer to the latest content and fix a broken link for the quick start sample documentation.

+ * Add option to enable the Mongo API version for the Linux Cosmos DB emulator by setting the environment variable: "AZURE_COSMOS_EMULATOR_ENABLE_MONGODB_ENDPOINT" in the Docker container setting. Valid setting are: "3.2", "3.6", "4.0" and "4.2"

+ Title: Use system-assigned managed identities to access Azure Cosmos DB data

+In this article, you'll set up a *robust, key rotation agnostic* solution to access Azure Cosmos DB keys by using [managed identities](../active-directory/managed-identities-azure-resources/services-support-managed-identities.md) and [data plane role-based access control](how-to-setup-rbac.md). The example in this article uses Azure Functions, but you can use any service that supports managed identities.

+You'll learn how to create a function app that can access Azure Cosmos DB data without needing to copy any Azure Cosmos DB keys. The function app will trigger when an HTTP request is made and then list all of the existing databases.

+## Prerequisites

+- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).

+- An existing Azure Cosmos DB SQL API account. [Create an Azure Cosmos DB SQL API account](sql/create-cosmosdb-resources-portal.md)

+- An existing Azure Functions function app. [Create your first function in the Azure portal](../azure-functions/functions-create-function-app-portal.md)

+ - A system-assigned managed identity for the function app. [Add a system-assigned identity](/app-service/overview-managed-identity.md?tabs=cli#add-a-system-assigned-identity)

+- [Azure Functions Core Tools](../azure-functions/functions-run-local.md)

+- To perform the steps in this article, install the [Azure CLI](/cli/azure/install-azure-cli) and [sign in to Azure](/cli/azure/authenticate-azure-cli).

+## Prerequisite check

+1. In a terminal or command window, store the names of your Azure Functions function app, Azure Cosmos DB account and resource group as shell variables named ``functionName``, ``cosmosName``, and ``resourceGroupName``.

+ ```azurecli-interactive

+ # Variable for function app name

+ functionName="msdocs-function-app"

+

+ # Variable for Cosmos DB account name

+ cosmosName="msdocs-cosmos-app"

+ # Variable for resource group name

+ resourceGroupName="msdocs-cosmos-functions-dotnet-identity"

+ ```

+ > [!NOTE]

+ > These variables will be re-used in later steps. This example assumes your Azure Cosmos DB account name is ``msdocs-cosmos-app``, your function app name is ``msdocs-function-app`` and your resource group name is ``msdocs-cosmos-functions-dotnet-identity``.

+1. View the function app's properties using the [``az functionapp show``](/cli/azure/functionapp&preserve-view=true#az-functionapp-show) command.

+ ```azurecli-interactive

+ az functionapp show \

+ --resource-group $resourceGroupName \

+ --name $functionName

+ ```

+1. View the properties of the system-assigned managed identity for your function app using [``az webapp identity show``](/cli/azure/webapp/identity#az-webapp-identity-show).

+ ```azurecli-interactive

+ az webapp identity show \

+ --resource-group $resourceGroupName \

+ --name $functionName

+ ```

+1. View the Cosmos DB account's properties using [``az cosmosdb show``](/cli/azure/cosmosdb#az-cosmosdb-show).

+ ```azurecli-interactive

+ az cosmosdb show \

+ --resource-group $resourceGroupName \

+ --name $cosmosName

+ ```

+## Create Cosmos DB SQL API databases

+In this step, you'll create two databases.

+1. In a terminal or command window, create a new ``products`` database using [``az cosmosdb sql database create``](/cli/azure/cosmosdb/sql/database#az-cosmosdb-sql-database-create).

+ ```azurecli-interactive

+ az cosmosdb sql database create \

+ --resource-group $resourceGroupName \

+ --name products \

+ --account-name $cosmosName

+ ```

+1. Create a new ``customers`` database.

+ ```azurecli-interactive

+ az cosmosdb sql database create \

+ --resource-group $resourceGroupName \

+ --name customers \

+ --account-name $cosmosName

+ ```

+## Get Cosmos DB SQL API endpoint

+In this step, you'll query the document endpoint for the SQL API account.

+1. Use ``az cosmosdb show`` with the **query** parameter set to ``documentEndpoint``. Record the result. You'll use this value in a later step.

+ ```azurecli-interactive

+ az cosmosdb show \

+ --resource-group $resourceGroupName \

+ --name $cosmosName \

+ --query documentEndpoint

+ cosmosEndpoint=$(

+ az cosmosdb show \

+ --resource-group $resourceGroupName \

+ --name $cosmosName \

+ --query documentEndpoint \

+ --output tsv

+ )

+

+ echo $cosmosEndpoint

+ ```

+ > [!NOTE]

+ > This variable will be re-used in a later step.

+## Grant access to your Azure Cosmos account

+In this step, you'll assign a role to the function app's system-assigned managed identity. Azure Cosmos DB has multiple built-in roles that you can assign to the managed identity. For this solution, you'll use the [Cosmos DB Built-in Data Reader](how-to-setup-rbac.md#built-in-role-definitions) role.

+> [!TIP]

+> When you assign roles, assign only the needed access. If your service requires only reading data, then assign the **Cosmos DB Built-in Data Reader** role to the managed identity. For more information about the importance of least privilege access, see the [Lower exposure of privileged accounts](../security/fundamentals/identity-management-best-practices.md#lower-exposure-of-privileged-accounts) article.

+1. Use ``az cosmosdb show`` with the **query** parameter set to ``id``. Store the result in a shell variable named ``scope``.

+ ```azurecli-interactive

+ scope=$(

+ az cosmosdb show \

+ --resource-group $resourceGroupName \

+ --name $cosmosName \

+ --query id \

+ --output tsv

+ )

+

+ echo $scope

+ ```

+ > [!NOTE]

+ > This variable will be re-used in a later step.

+1. Use ``az webapp identity show`` with the **query** parameter set to ``principalId``. Store the result in a shell variable named ``principal``.

+ ```azurecli-interactive

+ principal=$(

+ az webapp identity show \

+ --resource-group $resourceGroupName \

+ --name $functionName \

+ --query principalId \

+ --output tsv

+ )

+

+ echo $principal

+ ```

+1. Create a new JSON object with the configuration of the new custom role.

+ ```json

+ "RoleName": "Read Cosmos Metadata",

+ "Type": "CustomRole",

+ "AssignableScopes": ["/"],

+ "Permissions": [{

+ "DataActions": [

+ "Microsoft.DocumentDB/databaseAccounts/readMetadata"

+ ]

+ }]

+ ```

+1. Use [``az role assignment create``](/cli/azure/cosmosdb/sql/role/assignment#az-cosmosdb-sql-role-assignment-create) to assign the ``Cosmos DB Built-in Data Reader`` role to the system-assigned managed identity.

+ ```azurecli-interactive

+ az cosmosdb sql role assignment create \

+ --resource-group $resourceGroupName \

+ --account-name $cosmosName \

+ --role-definition-name "Read Cosmos Metadata" \

+ --principal-id $principal \

+ --scope $scope

+ ```

+## Programmatically access the Azure Cosmos DB keys

+We now have a function app that has a system-assigned managed identity with the **Cosmos DB Built-in Data Reader** role. The following function app will query the Azure Cosmos DB account for a list of databases.

+1. Create a local function project with the ``--dotnet`` parameter in a folder named ``csmsfunc``. Change your shell's directory

+ ```azurecli-interactive

+ func init csmsfunc --dotnet

+

+ cd csmsfunc

+ ```

+1. Create a new function with the **template** parameter set to ``httptrigger`` and the **name** set to ``readdatabases``.

+ ```azurecli-interactive

+ func new --template httptrigger --name readdatabases

+ ```

+1. Add the [``Azure.Identity``](https://www.nuget.org/packages/Azure.Identity/) and [``Microsoft.Azure.Cosmos``](https://www.nuget.org/packages/Microsoft.Azure.Cosmos/) NuGet package to the .NET project. Build the project using [``dotnet build``](/dotnet/core/tools/dotnet-build).

+ ```azurecli-interactive

+ dotnet add package Azure.Identity

+

+ dotnet add package Microsoft.Azure.Cosmos

+

+ dotnet build

+ ```

+1. Open the function code in an integrated developer environment (IDE).

+ > [!TIP]

+ > If you are using the Azure CLI locally or in the Azure Cloud Shell, you can open Visual Studio Code.

+ >

+ > ```azurecli

+ > code .

+ > ```

+ >

+1. Replace the code in the **readdatabases.cs** file with this sample function implementation. Save the updated file.

+ ```csharp

+ using System;

+ using System.Collections.Generic;

+ using System.Threading.Tasks;

+ using Azure.Identity;

+ using Microsoft.AspNetCore.Mvc;

+ using Microsoft.Azure.Cosmos;

+ using Microsoft.Azure.WebJobs;

+ using Microsoft.Azure.WebJobs.Extensions.Http;

+ using Microsoft.AspNetCore.Http;

+ using Microsoft.Extensions.Logging;

+

+ namespace csmsfunc

+ public static class readdatabases

+ [FunctionName("readdatabases")]

+ public static async Task<IActionResult> Run(

+ [HttpTrigger(AuthorizationLevel.Anonymous, "get")] HttpRequest req,

+ ILogger log)

+ {

+ log.LogTrace("Start function");

+

+ CosmosClient client = new CosmosClient(

+ accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT", EnvironmentVariableTarget.Process),

+ new DefaultAzureCredential()

+ );

+

+ using FeedIterator<DatabaseProperties> iterator = client.GetDatabaseQueryIterator<DatabaseProperties>();

+

+ List<(string name, string uri)> databases = new();

+ while(iterator.HasMoreResults)

+ {

+ foreach(DatabaseProperties database in await iterator.ReadNextAsync())

+ {

+ log.LogTrace($"[Database Found]\t{database.Id}");

+ databases.Add((database.Id, database.SelfLink));

+ }

+ }

+

+ return new OkObjectResult(databases);

+ }

+ }

+ }

+ ```

+## (Optional) Run the function locally

+In a local environment, the [``DefaultAzureCredential``](/dotnet/api/azure.identity.defaultazurecredential) class will use various local credentials to determine the current identity. While running locally isn't required for the how-to, you can develop locally using your own identity or a service principal.

+1. In the **local.settings.json** file, add a new setting named ``COSMOS_ENDPOINT`` in the **Values** object. The value of the setting should be the document endpoint you recorded earlier in this how-to guide.

+ ```json

+ ...

+ "Values": {

+ ...

+ "COSMOS_ENDPOINT": "https://msdocs-cosmos-app.documents.azure.com:443/",

+ ...

+ }

+ ...

+ ```

+ > [!NOTE]

+ > This JSON object has been shortened for brevity. This JSON object also includes a sample value that assumes your account name is ``msdocs-cosmos-app``.

+1. Run the function app

+ ```azurecli

+ func start

+ ```

+## Deploy to Azure

+Once published, the ``DefaultAzureCredential`` class will use credentials from the environment or a managed identity. For this guide, the system-assigned managed identity will be used as a credential for the [``CosmosClient``](/dotnet/api/microsoft.azure.cosmos.cosmosclient) constructor.

+1. Set the ``COSMOS_ENDPOINT`` setting on the function app already deployed in Azure.

+ ```azurecli-interactive

+ az functionapp config appsettings set \

+ --resource-group $resourceGroupName \

+ --name $functionName \

+ --settings "COSMOS_ENDPOINT=$cosmosEndpoint"

+ ```

+1. Deploy your function app to Azure by reusing the ``functionName`` shell variable:

+ ```azurecli-interactive

+ func azure functionapp publish $functionName

+ ```

+1. [Test your function in the Azure portal](../azure-functions/functions-create-function-app-portal.md#test-the-function).

+When using the `findOneAndUpdate` operation with Mongo API version 4.0, sort operations on a single field and multiple fields are supported. Sort operations on multiple fields was a limitation of previous wire protocols.

+az cosmosdb mongodb user definition create --account-name <YOUR_DB_ACCOUNT> --resource-group <YOUR_RG> --body {\"Id\":\"<YOUR_DB_NAME>.<YOUR_USERNAME>\",\"UserName\":\"<YOUR_USERNAME>\",\"Password\":\"<YOUR_PASSWORD>\",\"DatabaseName\":\"<YOUR_DB_NAME>\",\"CustomData\":\"Some_Random_Info\",\"Mechanisms\":\"SCRAM-SHA-256\",\"Roles\":[{\"Role\":\"read\",\"Db\":\"<YOUR_DB_NAME>\"}]}

+> * You are managing the session tokens manually.

+* [Availability and performance tradeoffs for various consistency levels](../consistency-levels.md)

+How eventual is eventual consistency? For the average case, can we offer staleness bounds with respect to version history and time. The [**Probabilistically Bounded Staleness (PBS)**](http://pbs.cs.berkeley.edu/) metric tries to quantify the probability of staleness and shows it as a metric. To view the PBS metric, go to your Azure Cosmos account in the Azure portal. Open the **Metrics** pane, and select the **Consistency** tab. Look at the graph named **Probability of strongly consistent reads based on your workload (see PBS)**.

+The Microsoft.Azure.Documents.UriFactory class has been replaced by the fluent design.

+# [.NET SDK v3](#tab/dotnet-v3)

+```csharp

+private readonly CosmosClient _client;

+private readonly Container _container;

+public Program()

+{

+ // Client should be a singleton

+ _client = new CosmosClient(

+ accountEndpoint: "https://testcosmos.documents.azure.com:443/",

+ authKeyOrResourceToken: "SuperSecretKey",

+ clientOptions: new CosmosClientOptions()

+ {

+ ApplicationPreferredRegions = new List<string>()

+ {

+ Regions.EastUS,

+ Regions.WestUS,

+ }

+ });

+ _container = _client.GetContainer("DatabaseName","ContainerName");

+}

+private async Task CreateItemAsync(SalesOrder salesOrder)

+{

+ ItemResponse<SalesOrder> response = await this._container.CreateItemAsync(

+ salesOrder,

+ new PartitionKey(salesOrder.AccountNumber));

+}

+```

+# [.NET SDK v2](#tab/dotnet-v2)

+```csharp

+private readonly DocumentClient _client;

+private readonly string _databaseName;

+private readonly string _containerName;

+public Program()

+{

+ ConnectionPolicy connectionPolicy = new ConnectionPolicy()

+ {

+ ConnectionMode = ConnectionMode.Direct, // Default for v2 is Gateway. v3 is Direct

+ ConnectionProtocol = Protocol.Tcp,

+ };

+ connectionPolicy.PreferredLocations.Add(LocationNames.EastUS);

+ connectionPolicy.PreferredLocations.Add(LocationNames.WestUS);

+ // Client should always be a singleton

+ _client = new DocumentClient(

+ new Uri("https://testcosmos.documents.azure.com:443/"),

+ "SuperSecretKey",

+ connectionPolicy);

+ _databaseName = "DatabaseName";

+ _containerName = "ContainerName";

+}

+private async Task CreateItemAsync(SalesOrder salesOrder)

+{

+ Uri collectionUri = UriFactory.CreateDocumentCollectionUri(_databaseName, _containerName)

+ await this._client.CreateDocumentAsync(

+ collectionUri,

+ salesOrder,

+ new RequestOptions { PartitionKey = new PartitionKey(salesOrder.AccountNumber) });

+}

+```

+The fluent design builds URLs internally and allows a single `Container` object to be passed around instead of a `DocumentClient`, `DatabaseName`, and `DocumentCollection`.

+|**Samples**|[Python SDK samples](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/cosmos/azure-cosmos/samples)|

+> * Versions 4.3.0b2 and higher support Async IO operations and only support Python 3.6+. Python 2 is not supported.

+| 4.3.0 |May 23, 2022 | |

+ // Log the response.Diagnostics.ToString() and add any additional info necessary to correlate to other logs

+ // Log the full exception including the stack trace with: cosmosException.ToString()

+

+ // The Diagnostics can be logged separately if required with: cosmosException.Diagnostics.ToString()

+ // Log the diagnostics and add any additional info necessary to correlate to other logs with: response.Diagnostics.ToString()

+### <a name="ServiceEndpointStatistics"></a>ServiceEndpointStatistics

+Information about a particular backend server. The SDK can open multiple connections to a single backend server depending upon the number of pending requests and the MaxConcurrentRequestsPerConnection.

+* `inflightRequests` The number of pending requests to a backend server (maybe from different partitions). A high number may to lead to more traffic and higher latencies.

+* `openConnections` is the total Number of connections open to a single backend server. This can be useful to show SNAT port exhausion if this number is very high.

+### <a name="ConnectionStatistics"></a>ConnectionStatistics

+Information about the particular connection (new or old) the request get's assigned to.

+* `waitforConnectionInit`: The current request was waiting for new connection initialization to complete. This will lead to higher latencies.

+* `callsPendingReceive`: Number of calls that was pending receive before this call was sent. A high number can show us that there were a lot of calls before this call and it may lead to higher latencies. If this number is high it points to a head of line blocking issue possibly caused by another request like query or feed operation that is taking a long time to process. Try lowering the CosmosClientOptions.MaxRequestsPerTcpConnection to increase the number of channels.

+* `LastSentTime`: Time of last request that was sent to this server. This along with LastReceivedTime can be used to see connectivity or endpoint issues. For example if there are a lot of receive timeouts, Sent time will be much larger than the Receive time.

+* `lastReceive`: Time of last request that was received from this server

+* `lastSendAttempt`: Time of the last send attempt

+### <a name="Request and response sizes"></a>Request and response sizes

+* `requestSizeInBytes`: The total size of the request sent to Cosmos DB

+* `responseMetadataSizeInBytes`: The size of headers returned from Cosmos DB

+* `responseBodySizeInBytes`: The size of content returned from Cosmos DB

+ "ActivityId": "bab6ade1-b8de-407f-b89d-fa2138a91284",

+ "StatusCode": "Ok",

+ "LSN": 453362,

+ "PartitionKeyRangeId": "1",

+ "GlobalCommittedLSN": 0,

+ "ItemLSN": 453358,

+ "UsingLocalLSN": true,

+ "QuorumAckedLSN": -1,

+ "SessionToken": "-1#453362",

+ "CurrentWriteQuorum": -1,

+ "CurrentReplicaSetSize": -1,

+ "StorePhysicalAddress": "rntbd://127.0.0.1:10253/apps/DocDbApp/services/DocDbServer92/partitions/a4cb49a8-38c8-11e6-8106-8cdcd42c33be/replicas/1s/",

+ "RequestCharge": 1,

+ "RetryAfterInMs": null,

+ "BELatencyInMs": "0.304",

+ "transportRequestTimeline": {

+ "requestTimeline": [

+ {

+ "event": "Created",

+ "startTimeUtc": "2022-05-25T12:03:36.3081190Z",

+ "durationInMs": 0.0024

+ },

+ {

+ "event": "ChannelAcquisitionStarted",

+ "startTimeUtc": "2022-05-25T12:03:36.3081214Z",

+ "durationInMs": 0.0132

+ },

+ {

+ "event": "Pipelined",

+ "startTimeUtc": "2022-05-25T12:03:36.3081346Z",

+ "durationInMs": 0.0865

+ },

+ {

+ "event": "Transit Time",

+ "startTimeUtc": "2022-05-25T12:03:36.3082211Z",

+ "durationInMs": 1.3324

+ },

+ {

+ "event": "Received",

+ "startTimeUtc": "2022-05-25T12:03:36.3095535Z",

+ "durationInMs": 12.6128

+ },

+ {

+ "event": "Completed",

+ "startTimeUtc": "2022-05-25T12:03:36.8621663Z",

+ "durationInMs": 0

+ }

+ ],

+ "serviceEndpointStats": {

+ "inflightRequests": 1,

+ "openConnections": 1

+ "connectionStats": {

+ "waitforConnectionInit": "False",

+ "callsPendingReceive": 0,

+ "lastSendAttempt": "2022-05-25T12:03:34.0222760Z",

+ "lastSend": "2022-05-25T12:03:34.0223280Z",

+ "lastReceive": "2022-05-25T12:03:34.0257728Z"

+ "requestSizeInBytes": 447,

+ "responseMetadataSizeInBytes": 438,

+ "responseBodySizeInBytes": 604

+ },

+* Learn about performance guidelines for [.NET v3](performance-tips-dotnet-sdk-v3-sql.md) and [.NET v2](performance-tips.md).

+To insert or upsert such an object using the Table API, map the properties of the expandable object into a [TableEntity](/java/api/com.azure.data.tables.models.tableentity) object and use the [createEntity](/java/api/com.azure.data.tables.tableclient.createentity) or [upsertEntity](/java/api/com.azure.data.tables.tableclient.upsertentity) methods on the [TableClient](/java/api/com.azure.data.tables.tableclient) object as appropriate.

+> [Import table data to the Tables API](table-import.md)

+ ListEntitiesOptions options = new ListEntitiesOptions().setFilter(PARTITION_KEY + " eq 'Sales' AND " + ROW_KEY + " lt '0004' AND " + ROW_KEY + " gt '0001'");

+ "\t" + specificEntity.getProperty("LastName") +

+ // Delete the entity for partition key 'Sales' and row key '0001' from the table.

+[Azure Tables Team Blog]: https://blogs.msdn.microsoft.com/windowsazurestorage/

+This article helps you understand and use Cost Management alerts to monitor your Azure usage and spending. Cost alerts are automatically generated based when Azure resources are consumed. Alerts show all active cost management and billing alerts together in one place. When your consumption reaches a given threshold, alerts are generated by Cost Management. There are three main types of cost alerts: budget alerts, credit alerts, and department spending quota alerts.

+You can also [create a cost anomaly alert](../understand/analyze-unexpected-charges.md#create-an-anomaly-alert) to automatically get notified when an anomaly is detected.

+EA credit expires when the EA enrollment ends.

+> - This API only works with the [legacy APIs for subscription creation](programmatically-create-subscription-preview.md).

+> - Unless you have a specific need to use the legacy APIs, you should use the information for the [latest GA version](programmatically-create-subscription-enterprise-agreement.md) about the latest API version. **See [Enrollment Account Role Assignments - Put](/rest/api/billing/2019-10-01-preview/enrollment-account-role-assignments/put) to grant permission to create EA subscriptions with the latest API**.

+> - If you're migrating to use the newer APIs, you must grant owner permissions again using [2019-10-01-preview](/rest/api/billing/2019-10-01-preview/enrollment-account-role-assignments/put). Your previous configuration that uses the following APIs doesn't automatically convert for use with newer APIs.

+You can also create an anomaly alert to automatically get notified when an anomaly is detected.

+## Create an anomaly alert

+You can create an anomaly alert to automatically get notified when an anomaly is detected. All email recipients get notified when a subscription cost anomaly is detected.

+An anomaly alert email includes a summary of changes in resource group count and cost. It also includes the top resource group changes for the day compared to the previous 60 days. And, it has a direct link to the Azure portal so that you can review the cost and investigate further.

+1. Start on a subscription scope.

+1. In the left menu, select **Cost alerts**.

+1. On the Cost alerts page, select **+ Add** > **Add anomaly alert**.

+1. On the Subscribe to emails page, enter required information and then select **Save**.

+ :::image type="content" source="./media/analyze-unexpected-charges/subscribe-emails.png" alt-text="Screenshot showing the Subscribe to emails page where you enter notification information for an alert." lightbox="./media/analyze-unexpected-charges/subscribe-emails.png" :::

+Here's an example email generated for an anomaly alert.

+## May 2022

+<br>

+<table>

+<tr><td><b>Service category</b></td><td><b>Service improvements</b></td><td><b>Details</b></td></tr>

+<tr><td><b>Data flow</b></td><td>User Defined Functions for mapping data flows</td><td>Azure Data Factory introduces in public preview user defined functions and data flow libraries. A user defined function is a customized expression you can define to be able to reuse logic across multiple mapping data flows. User defined functions live in a collection called a data flow library to be able to easily group up common sets of customized functions.<br><a href="concepts-data-flow-udf.md">Learn more</a></td></tr>

+</table>

+<iframe src="https://aka.ms/docs/player?id=05fdecf5-f6a1-4162-b95d-1e34478d1d60" width="1080" height="530" allowFullScreen="true" frameBorder="0"></iframe>

+<iframe src="https://aka.ms/docs/player?id=646c2b9a-3f15-4705-af23-7802bd9549c5" width="1080" height="530" allowFullScreen="true" frameBorder="0"></iframe>

+<iframe src="https://aka.ms/docs/player?id=f62e1199-d0a8-4801-9793-5318fde27497" width="1080" height="530" allowFullScreen="true" frameBorder="0"></iframe>

+<iframe src="https://aka.ms/docs/player?id=845108fd-e57d-40e0-808a-1239e78a7390" width="1080" height="530" allowFullScreen="true" frameBorder="0"></iframe>

+<iframe src="https://aka.ms/docs/player?id=f9470496-abe3-4344-8160-d6a6b65c077f" width="1080" height="530" allowFullScreen="true" frameBorder="0"></iframe>

+<iframe src="https://aka.ms/docs/player?id=26cbaec8-0f3f-4bb1-9918-1bf7d912db57" width="1080" height="530" allowFullScreen="true" frameBorder="0"></iframe>

+<iframe src="https://aka.ms/docs/player?id=80ba04f0-1551-48f3-94a2-d2e82e7073c9" width="1080" height="530" allowFullScreen="true" frameBorder="0"></iframe>

+<iframe src="https://aka.ms/docs/player?id=3811455b-cc20-4ee0-b1bf-9d4df5ee4eaf" width="1080" height="530" allowFullScreen="true" frameBorder="0"></iframe>

+<iframe src="https://aka.ms/docs/player?id=078af1f2-1f12-4030-bd3f-3e7616150562" width="1080" height="530" allowFullScreen="true" frameBorder="0"></iframe>

+<iframe src="https://aka.ms/docs/player?id=b8624912-ef9e-4fc6-8c0c-ea65e86d9128" width="1080" height="530" allowFullScreen="true" frameBorder="0"></iframe>

+<iframe src="https://aka.ms/docs/player?id=18fdbe74-4399-44fe-81e7-3e3ce92df451" width="1080" height="530" allowFullScreen="true" frameBorder="0"></iframe>

+<iframe src="https://aka.ms/docs/player?id=9b911e9c-e933-4b7b-908a-5fd614f822c7" width="1080" height="530" allowFullScreen="true" frameBorder="0"></iframe>

+| :::image type="icon" source="media/secure-score-security-controls/preview-icon.png" border="false"::: | Preview recommendation | This recommendation won't affect your secure score until it's GA. |

+| **Cache size** | cycle FIFO | Defines the number of events collected in between the times that data is sent. | `256` |

+| **Devices** | A list of the network devices separated by a comma. <br><br>For example `eth0,eth1` | Defines the list of network devices (interfaces) that the agent will use to monitor the traffic. <br><br>If a network device isn't listed, the Network Raw events will not be recorded for the missing device.| `eth0` |

+description: Learn about the concept of security recommendations and how they're used in the Defender for IoT Hub.

+description: Learn about the concept of Defender-IoT-micro-agent twins and how they're used in Defender for IoT.

+description: Learn how to configure Pluggable Authentication Modules (PAM) to audit sign-in events when syslog isn't configured for your device.

+Make sure to validate your agent configuration against this [schema](https://aka.ms/iot-security-github-module-schema). An agent will not launch if the configuration object doesn't match the schema.

+If, while the agent is running, the configuration object is changed to a non-valid configuration (the configuration doesn't match the schema), the agent will ignore the invalid configuration and will continue using the current configuration.

+| ASC_SECURITY_MODULE_PENDING_TIME | Number | 300 | The Defender-IoT-micro-agent pending time (in seconds). The state will change to suspend, if the time is exceeded. |

+1. Adds a service user (with interactive sign-in disabled).

+- Adds a service user (with interactive sign-in disabled).

+ 1. Ensure that the service is stable by making sure it's `active` and that the uptime of the process is appropriate

+- Identify all IOT, and OT devices from different inputs. For example, allowing you to understand which devices in your environment aren't communicating, and will require troubleshooting.

+Multiple filters can be applied at one time. The filters aren't saved when you leave the Device inventory page.

+If you are under the impression that certain devices are not actively communicating, there's a way to check, and see which devices have not communicated in a specified time period.

+In this section, you'll prepare to move the resource for the move by finding the resource and confirming it is in a region you wish to move from.

+1. Ensure that you've selected the correct hub, and that it is in the region you want to move it from.

+You're now ready to move your resource to your new location. Follow [these instructions](../../iot-hub/iot-hub-how-to-clone.md) to move your IoT Hub.

+In this section, you'll verify that the resource has been moved, that the connection to the IoT Hub has been enabled, and that everything is working correctly.

+1. Select the **Settings** blade under the **Security** section.

+1. Select **Data Collection**, and change your Log Analytics workspace configuration.

+1. Select **further investigation**, then select **To see which devices have this alert click here and view the DeviceId column**.

+The **Secure your IoT solution** button will only appear if the IoT Hub hasn't already been onboarded, or if you set the Defender for IoT toggle to **Off** while onboarding.

+| **Device inventory** | Defender for IoT identifies, and classifies devices as a single unique network device in the inventory for: <br><br> - Standalone IT, OT, and IoT devices with 1 or multiple NICs. <br><br> - Devices composed of multiple backplane components. This includes all racks, slots, and modules. <br><br> - Devices that act as network infrastructure. For example, switches, and routers with multiple NICs. <br><br> - Public internet IP addresses, multicast groups, and broadcast groups aren't considered inventory devices. <br><br>Devices that have been inactive for more than 60 days are classified as inactive Inventory devices.|

+- **Micro agent supported devices list expands**: The micro agent now supports Debian 11 AMD64 and ARM32v7 devices, and Ubuntu Server 18.04 ARM32 Linux devices & Ubuntu Server 20.04 ARM32 & ARM64 Linux devices.

+- [Leaf device proxying](../../iot-edge/how-to-connect-downstream-iot-edge-device.md#integrate-microsoft-defender-for-iot-with-iot-edge-gateway): There's now an enhanced integration with IoT Edge. This integration enhances the connectivity between the agent, and the cloud using leaf device proxying.

+Agent installation on your IoT devices isn't mandatory in order to enable Defender for IoT. You can choose between the following two options There are four different levels of security monitoring, and management capabilities, which will provide different levels of protection:

+In this article, you got a high-level overview about Defender for IoT Defender-IoT-micro-agent architecture, and the available installers. To continue getting started with Defender for IoT deployment, review the security agent authentication methods that are available.

+Microsoft Defender for IoT agent self-starts immediately after installation. The agent start-up process includes reading local configuration, connecting to Azure IoT Hub, and retrieving the remote twin configuration. Failure in any one of these steps may cause the security agent to fail.

+1. To validate that the security agent is running, wait a few minutes after installing the agent and run the following command.

+| Local Configuration | Cant Parse Configuration | A configuration value can't be parsed. The error message should state which key can't be parsed. A configuration value cannot be parsed either because the value isn't in the expected type, or the value is out of range. | Fix the value of the key in /var/LocalConfiguration.json file so that it matches the LocalConfiguration schema, see the [c#-localconfig-reference](azure-iot-security-local-configuration-csharp.md) for details. | Fix the value of the key in General.config file so that it matches the schema, see the [cs-localconfig-reference](azure-iot-security-local-configuration-c.md) for details. |

+| Remote Configuration | Timeout | The agent could not fetch the azureiotsecurity module twin within the timeout period. | Make sure authentication configuration is correct and try again. | The agent couldn't fetch the azureiotsecurity module twin within timeout period. Make sure authentication configuration is correct and try again. |

+| Authentication | File Not Exist | The file in the given path doesn't exist. | Make sure the file exists in the given path or go to the **LocalConfiguration.json** file and change the **FilePath** configuration. | Make sure the file exists in the given path or go to the **Authentication.config** file and change the **filePath** configuration. |

+1. Check that the service is stable by making sure it's `active`, and that the uptime in the process is appropriate.

+ :::image type="content" source="media/troubleshooting/active-running.png" alt-text="Ensure your service is stable by checking to see that it's active and the uptime is appropriate.":::

+For this scenario we'll be installing, and configuring the latest version of [Squid](http://www.squid-cache.org/) on an Ubuntu 18 server.

+When users haven't worked with their console mouse or keyboard for 30 minutes, a session sign-out is forced.

+1. On the sign-in screen of either the on-premises management console or the sensor, select **Password recovery**. The **Password recovery** screen opens.

+ :::image type="content" source="media/how-to-create-and-manage-users/password-recovery.png" alt-text="Screenshot of the Select Password recovery from the sign-in screen of either the on-premises management console, or the sensor.":::

+| **Inventory device** | Defender for IoT will identify and classify devices as a single unique network device in the inventory for:<br><br>- Standalone IT/OT/IoT devices (w/ 1 or multiple NICs)<br>- Devices composed of multiple backplane components (including all racks/slots/modules)<br>- Devices acting as network infrastructure such as Switch/Router (w/ multiple NICs). <br><br>Public internet IP addresses, multicast groups, and broadcast groups are not considered inventory devices. Devices that have been inactive for more than 60 days are classified as inactive Inventory devices.|

+Azure Digital Twins can receive data from upstream services such as [IoT Hub](../iot-hub/about-iot-hub.md) or [Logic Apps](../logic-apps/logic-apps-overview.md), which are used to deliver telemetry and notifications.

+Azure Digital Twins can also use [event routes](concepts-route-events.md) to send data to downstream services, such as [Azure Maps](../azure-maps/about-azure-maps.md) and [Time Series Insights](../time-series-insights/overview-what-is-tsi.md), for storage, workflow integration, analytics, and more.

+## Data egress

+You may want to send Azure Digital Twins data to other downstream services for storage or additional processing.

+Digital twin data can be sent to most Azure services using *endpoints*. If your destination is [Azure Data Explorer](/azure/data-explorer/data-explorer-overview), you can use *data history* instead to automatically historize twin property updates to an Azure Data Explorer cluster, where they can be queried as time series data. The rest of this section describes these capabilities in more detail.

+>[!NOTE]

+>Azure Digital Twins implements *at least once* delivery for data emitted to egress services.

+### Endpoints

+To send Azure Digital Twins data to most Azure services, such as [Azure Maps](../azure-maps/about-azure-maps.md), [Time Series Insights](../time-series-insights/overview-what-is-tsi.md), or [Azure Storage](../storage/common/storage-introduction.md), start by attaching the destination service to an *endpoint*.

+### Data history

+To send twin data to [Azure Data Explorer](/azure/data-explorer/data-explorer-overview), set up a [data history (preview) connection](concepts-data-history.md) that automatically historizes digital twin property updates from your Azure Digital Twins instance to an Azure Data Explorer cluster. The data history connection requires an [event hub](../event-hubs/event-hubs-about.md), but doesn't require an explicit endpoint.

+Once the data has been historized, you can query this data in Azure Data Explorer using the [Azure Digital Twins query plugin for Azure Data Explorer](concepts-data-explorer-plugin.md).

+You can also use data history in combination with [Azure Synapse Analytics](../synapse-analytics/overview-what-is.md) to aggregate data from disparate sources. One useful application of this is to combine information technology (IT) data from ERP or CRM systems (like Dynamics 365, SAP, or Salesforce) with operational technology (OT) data from IoT devices and production management systems. For an example that illustrates how a company might combine this data, see the following blog post: [Integrating IT and OT Data with Azure Digital Twins, Azure Data Explorer, and Azure Synapse](https://techcommunity.microsoft.com/t5/internet-of-things-blog/integrating-it-and-ot-data-with-azure-digital-twins-azure-data/ba-p/3401981).

+* [Ingest telemetry from IoT Hub](how-to-ingest-iot-hub-data.md)

+| **Phoenix** | [CyrusOne Chandler](https://cyrusone.com/locations/arizona/phoenix-arizona-chandler/) | US Gov Arizona | Supported | AT&T NetBond, CenturyLink Cloud Connect, Megaport |

+| **vXchnge** | IX Reach, Megaport |

+ Title: Manage Azure Web Application Firewall policies (preview)

+description: Learn how to use Azure Firewall Manager to manage Azure Web Application Firewall policies

+# Manage Web Application Firewall policies (preview)

+You can centrally create and associate Web Application Firewall (WAF) policies for your application delivery platforms, including Azure Front Door and Azure Application Gateway.

+> [!IMPORTANT]

+> Managing Web Application Firewall policies using Azure Firewall Manager is currently in PREVIEW.

+> See the [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) for legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.

+## Prerequisites

+- A deployed [Azure Front Door](../frontdoor/quickstart-create-front-door.md) or [Azure Application Gateway](../application-gateway/quick-create-portal.md)

+## Associate a WAF policy

+1. Sign in to the Azure portal at [https://portal.azure.com](https://portal.azure.com).

+2. In the Azure portal search bar, type **Firewall Manager** and press **Enter**.

+3. On the Azure Firewall Manager page, select **Application Delivery Platforms**.

+ :::image type="content" source="media/manage-web-application-firewall-policies/application-delivery-platforms.png" alt-text="Screenshot of Firewall Manager application delivery platforms.":::

+1. Select your application delivery platform (Front Door or Application Gateway) to associate a WAF policy. In this example, we'll associate a WAF policy to a Front Door.

+1. Select **Manage Security** and then select **Associate WAF policy**.

+ :::image type="content" source="media/manage-web-application-firewall-policies/associate-waf-policy.png" alt-text="Screenshot of Firewall Manager associate WAF policy.":::

+1. Select either an existing policy or **Create New**.

+1. Select the domain(s) that you want the WAF policy to protect with your Azure Front Door profile.

+1. Select **Associate**.

+## View and manage WAF policies

+1. On the Azure Firewall Manager page, under **Security**, select **Web application firewall policies** to view all your policies.

+1. Select **Add** to create a new WAF policy or import settings from an existing WAF policy.

+ :::image type="content" source="media/manage-web-application-firewall-policies/web-application-firewall-policies.png" alt-text="Screenshot of Firewall Manager Web Application Firewall policies.":::

+## Upgrade Application Gateway WAF configuration to WAF policy

+For Application Gateway with WAF configuration, you can upgrade the WAF configuration to a WAF policy associated with Application Gateway.

+The WAF policy can be shared to multiple application gateways. Also, a WAF policy allows you to take advantage of advanced and new features like bot protection, newer rule sets, and reduced false positives. New features are only released on WAF policies.

+To upgrade a WAF configuration to a WAF policy, select **Upgrade from WAF configuration** from the desired application gateway.

+## Next steps

+- [Configure an Azure DDoS Protection Plan using Azure Firewall Manager (preview)](configure-ddos.md)

+This article lists current metros containing edge locations, sorted by region, for Azure Front Door. Each metro may contain more than one edge locations. Currently, Azure Front Door has 118 edge locations across 100 metro cities. Azure Front Door also has 4 edge locations across 4 Azure US Government cloud regions.

+zone_pivot_groups: front-door-tiers

+Azure Front Door supports adding custom domain to Front Door profile. This is done by adding DNS TXT record for domain ownership validation and creating a CNAME record in your DNS configuration to route DNS queries for the custom domain to Azure Front Door endpoint. For apex domain, DNS TXT will continue to be used for domain validation. However, the DNS protocol prevents the assignment of CNAME records at the zone apex. For example, if your domain is `contoso.com`; you can create CNAME records for `somelabel.contoso.com`; but you can't create CNAME for `contoso.com` itself. Front Door doesn't expose the frontend IP address associated with your Front Door profile. So you can't map your apex domain to an IP address if your intent is to onboard it to Azure Front Door.

+## Onboard the custom domain to your Front Door

+1. Select **Domains** from under *Settings* on the left side pane for your Front Door profile and then select **+ Add** to add a new custom domain.

+ :::image type="content" source="./media/front-door-apex-domain/add-domain.png" alt-text="Screenshot of adding a new domain to Front Door profile.":::

+1. On **Add a domain** page, you'll enter information about the custom domain. You can choose Azure-managed DNS (recommended) or you can choose to use your DNS provider.

+ - **Azure-managed DNS** - select an existing DNS zone and for *Custom domain*, select **Add new**. Select **APEX domain** from the pop-up and then select **OK** to save.

+ :::image type="content" source="./media/front-door-apex-domain/add-custom-domain.png" alt-text="Screenshot of adding a new custom domain to Front Door profile.":::

+ - **Another DNS provider** - make sure the DNS provider supports CNAME flattening and follow the steps for [adding a custom domain](standard-premium/how-to-add-custom-domain.md#add-a-new-custom-domain).

+1. Select the **Pending** validation state. A new page will appear with DNS TXT record information needed to validate the custom domain. The TXT record is in the form of `_dnsauth.<your_subdomain>`.

+ :::image type="content" source="./media/front-door-apex-domain/pending-validation.png" alt-text="Screenshot of custom domain pending validation.":::

+ - **Azure DNS-based zone** - select the **Add** button and a new TXT record with the displayed record value will be created in the Azure DNS zone.

+ :::image type="content" source="./media/front-door-apex-domain/validate-custom-domain.png" alt-text="Screenshot of validate a new custom domain.":::

+ - If you're using another DNS provider, manually create a new TXT record of name `_dnsauth.<your_subdomain>` with the record value as shown on the page.

+1. Close the *Validate the custom domain* page and return to the *Domains* page for the Front Door profile. You should see the *Validation state* change from **Pending** to **Approved**. If not, wait up to 10 minutes for changes to reflect. If your validation doesn't get approved make sure your TXT record is correct and name servers are configured correctly if you're using Azure DNS.

+ :::image type="content" source="./media/front-door-apex-domain/validation-approved.png" alt-text="Screenshot of new custom domain passing validation.":::

+1. Select **Unassociated** from the *Endpoint association* column, to add the new custom domain to an endpoint.

+ :::image type="content" source="./media/front-door-apex-domain/unassociated-endpoint.png" alt-text="Screenshot of unassociated custom domain to an endpoint.":::

+1. On the *Associate endpoint and route* page, select the **Endpoint** and **Route** you would like to associate the domain to. Then select **Associate** to complete this step.

+ :::image type="content" source="./media/front-door-apex-domain/associate-endpoint.png" alt-text="Screenshot of associated endpoint and route page for a domain.":::

+1. Under the *DNS state* column, select the **CNAME record is currently not detected** to add the alias record to DNS provider.

+ - **Azure DNS** - select the **Add** button on the page.

+ :::image type="content" source="./media/front-door-apex-domain/cname-record.png" alt-text="Screenshot of add or update CNAME record page.":::

+ - **A DNS provider that supports CNAME flattening** - you must manually enter the alias record name.

+

+1. Once the alias record gets created and the custom domain is associated to the Azure Front Door endpoint, traffic will start flowing.

+ :::image type="content" source="./media/front-door-apex-domain/cname-record-added.png" alt-text="Screenshot of completed APEX domain configuration.":::

+> [!NOTE]

+> **DNS state** column is meant for CNAME mapping check. Because apex domain doesnΓÇÖt support CNAME record, the DNS state will show 'CNAME record is currently not detected' even after you added the alias record to the DNS provider.

+## Enable HTTPS on your custom domain

+Follow the guidance for [configuring HTTPS for your custom domain](standard-premium/how-to-configure-https-custom-domain.md) to enable HTTPS for your apex domain.

+## Managed certificate renewal for apex domain

+Front Door managed certificates will automatically rotate certificates only if the domain CNAME is pointed to Front Door endpoint. If the APEX domain doesnΓÇÖt have a CNAME record pointing to Front Door endpoint, the auto-rotation for managed certificate will fail until domain ownership is re-validated. The validation column will become `Pending-revalidation` 45 days before the managed certificate expires. Select the **Pending-revalidation** link and then select the **Regenerate** button to regenerate the TXT token. After that, add the TXT token to the DNS provider settings.

+## Where is the service available?

+Azure Front Door is available in Microsoft Azure (Commercial) and Microsoft Azure Government (US).

+ Title: Reference - Azure Policy guest configuration baseline for Docker

+description: Details of the Docker baseline on Azure implemented through Azure Policy guest configuration.

+# Docker security baseline

+This article details the configuration settings for Docker hosts as applicable in the following

+implementations:

+- **\[Preview\]: Linux machines should meet requirements for the Azure security baseline for Docker hosts**

+- **Vulnerabilities in security configuration on your machines should be remediated** in Azure

+ Security Center

+For more information, see [Understand the guest configuration feature of Azure Policy](../concepts/guest-configuration.md) and

+[Overview of the Azure Security Benchmark (V2)](../../../security/benchmarks/overview.md).

+## General security controls

+|Name<br />_(CCEID) |Details |Remediation check |

+||||

+|Docker inventory Information<br />_(0.0) |Description: None |None |

+|Ensure a separate partition for containers has been created<br />_(1.01) |Description: Docker depends on /var/lib/docker as the default directory where all Docker related files, including the images, are stored. This directory might fill up fast and soon Docker and the host could become unusable. So, it's advisable to create a separate partition (logical volume) for storing Docker files. |For new installations, create a separate partition for /var/lib/docker mount point. For systems that were previously installed, use the Logical Volume Manager (LVM) to create partitions. |

+|Ensure docker version is up-to-date<br />_(1.03) |Description: Using up-to-date docker version will keep your host secure |Follow the docker documentation in aim to upgrade your version |

+|Ensure auditing is configured for the docker daemon<br />_(1.05) |Description: Apart from auditing your regular Linux file system and system calls, audit Docker daemon as well. Docker daemon runs with root privileges. It's thus necessary to audit its activities and usage. |Add the line `-w /usr/bin/docker -k docker` into the /etc/audit/audit.rules file. Then, restart the audit daemon by running the command: `service auditd restart` |

+|Ensure auditing is configured for Docker files and directories - /var/lib/docker<br />_(1.06) |Description: Apart from auditing your regular Linux file system and system calls, audit all Docker related files and directories. Docker daemon runs with root privileges. Its behavior depends on some key files and directories. /var/lib/docker is one such directory. It holds all the information about containers. It must be audited. |Add the line `-w /var/lib/docker -k docker` into the /etc/audit/audit.rules file. Then, restart the audit daemon by running the command: `service auditd restart` |

+|Ensure auditing is configured for Docker files and directories - /etc/docker<br />_(1.07) |Description: Apart from auditing your regular Linux file system and system calls, audit all Docker related files and directories. Docker daemon runs with root privileges. Its behavior depends on some key files and directories. /etc/docker is one such directory. It holds various certificates and keys used for TLS communication between Docker daemon and Docker client. It must be audited. |Add the line `-w /etc/docker -k docker` into the /etc/audit/audit.rules file. Then, restart the audit daemon by running the command: `service auditd restart` |

+|Ensure auditing is configured for Docker files and directories - docker.service<br />_(1.08) |Description: Apart from auditing your regular Linux file system and system calls, audit all Docker related files and directories. Docker daemon runs with root privileges. Its behavior depends on some key files and directories. Docker.service is one such file. The docker.service file might be present if the daemon parameters have been changed by an administrator. It holds various parameters for Docker daemon. It must be audited, if applicable. |Find out the 'docker.service' file location by running: `systemctl show -p FragmentPath docker.service` and add the line `-w {docker.service file location} -k docker` into the /etc/audit/audit.rules file where `{docker.service file location}` is the file path you have found earlier. Restart the audit daemon by running the command: `service auditd restart` |

+|Ensure auditing is configured for Docker files and directories - docker.socket<br />_(1.09) |Description: Apart from auditing your regular Linux file system and system calls, audit all Docker related files and directories. Docker daemon runs with root privileges. Its behavior depends on some key files and directories. Docker.socket is one such file. It holds various parameters for Docker daemon socket. It must be audited, if applicable. |Find out the 'docker.socket' file location by running: `systemctl show -p FragmentPath docker.socket` and add the line `-w {docker.socket file location} -k docker` into the /etc/audit/audit.rules file where `{docker.socket file location}` is the file path you have found earlier. Restart the audit daemon by running the command: `service auditd restart` |

+|Ensure auditing is configured for Docker files and directories - /etc/default/docker<br />_(1.10) |Description: Apart from auditing your regular Linux file system and system calls, audit all Docker related files and directories. Docker daemon runs with root privileges. Its behavior depends on some key files and directories. /etc/default/docker is one such file. It holds various parameters for Docker daemon. It must be audited, if applicable. |Add the line `-w /etc/default/docker -k docker` into the /etc/audit/audit.rules file. Then, restart the audit daemon by running the command: `service auditd restart` |

+|Ensure auditing is configured for Docker files and directories - /etc/docker/daemon.json<br />_(1.11) |Description: Apart from auditing your regular Linux file system and system calls, audit all Docker related files and directories. Docker daemon runs with root privileges. Its behavior depends on some key files and directories. /etc/docker/daemon.json is one such file. It holds various parameters for Docker daemon. It must be audited, if applicable. |Add the line `-w /etc/docker/daemon.json -k docker` into the /etc/audit/audit.rules file. Then, restart the audit daemon by running the command: `service auditd restart` |

+|Ensure auditing is configured for Docker files and directories - /usr/bin/docker-containerd<br />_(1.12) |Description: Apart from auditing your regular Linux file system and system calls, audit all Docker related files and directories. Docker daemon runs with root privileges. Its behavior depends on some key files and directories. /usr/bin/docker-containerd is one such file. Docker now relies on containerd and runC to spawn containers. It must be audited, if applicable. |Add the line `-w /usr/bin/docker-containerd -k docker` into the /etc/audit/audit.rules file. Then, restart the audit daemon by running the command: `service auditd restart` |

+|Ensure auditing is configured for Docker files and directories - /usr/bin/docker-runc<br />_(1.13) |Description: Apart from auditing your regular Linux file system and system calls, audit all Docker related files and directories. Docker daemon runs with root privileges. Its behavior depends on some key files and directories. /usr/bin/docker-runc is one such file. Docker now relies on containerd and runC to spawn containers. It must be audited, if applicable. |Add the line `-w /usr/bin/docker-runc -k docker` into the /etc/audit/audit.rules file. Then, restart the audit daemon by running the command: `service auditd restart` |

+|Ensure network traffic is restricted between containers on the default bridge<br />_(2.01) |Description: The inter-container communication would be disabled on the default network bridge. If any communication between containers on the same host is desired, then it needs to be explicitly defined using container linking or alternatively custom networks have to be defined. |Run the docker in daemon mode and pass `--icc=false` as an argument or set the 'icc' setting to false in the daemon.json file. Alternatively, you can follow the Docker documentation and create a custom network and only join containers that need to communicate to that custom network. The `--icc` parameter only applies to the default docker bridge, if custom networks are used then the approach of segmenting networks should be adopted instead. |

+|Ensure the logging level is set to 'info'.<br />_(2.02) |Description: Setting up an appropriate log level, configures the Docker daemon to log events that you would want to review later. A base log level of `info` and above would capture all logs except debug logs. Until and unless required, you shouldn't run Docker daemon at `debug` log level. |Run the Docker daemon as below: ```dockerd --log-level info``` |

+|Ensure Docker is allowed to make changes to iptables<br />_(2.03) |Description: Docker will never make changes to your system `iptables` rules if you choose to do so. Docker server would automatically make the needed changes to iptables based on how you choose your networking options for the containers if it's allowed to do so. It's recommended to let Docker server make changes to `iptables`automatically to avoid networking misconfiguration that might hamper the communication between containers and to the outside world. Additionally, it would save you hassles of updating `iptable`every time you choose to run the containers or modify networking options. |Don't run the Docker daemon with `--iptables=false` parameter. For example, don't start the Docker daemon as below: ```dockerd --iptables=false``` |

+|Ensure insecure registries aren't used<br />_(2.04) |Description: You shouldn't be using any insecure registries in the production environment. Insecure registries can be tampered with leading to possible compromise to your production system. |remove `--insecure-registry` flag from the dockerd start command |

+|The 'aufs' storage driver shouldn't be used by the docker daemon<br />_(2.05) |Description: The 'aufs' storage driver is the oldest storage driver. It's based on a Linux kernel patch-set that is unlikely to be merged into the main Linux kernel. aufs driver is also known to cause some serious kernel crashes. aufs just has legacy support from Docker. Most importantly, aufs isn't a supported driver in many Linux distributions using latest Linux kernels |The 'aufs' storage driver should be replaced by a different storage driver, we recommend to use 'overlay2' |

+|Ensure TLS authentication for Docker daemon is configured<br />_(2.06) |Description: By default, Docker daemon binds to a non-networked Unix socket and runs with `root` privileges. If you change the default docker daemon binding to a TCP port or any other Unix socket, anyone with access to that port or socket can have full access to Docker daemon and in turn to the host system. Hence, you shouldn't bind the Docker daemon to another IP/port or a Unix socket. If you must expose the Docker daemon via a network socket, configure TLS authentication for the daemon and Docker Swarm APIs (if using). This would restrict the connections to your Docker daemon over the network to a limited number of clients who could successfully authenticate over TLS. |Follow the steps mentioned in the Docker documentation or other references. |

+|Ensure the default ulimit's configured appropriately<br />_(2.07) |Description: If the ulimits aren't set properly, the desired resource control might not be achieved and might even make the system unusable. |Run the docker in daemon mode and pass --default-ulimit as argument with respective ulimits as appropriate in your environment. Alternatively, you can also set a specific resource limitation to each container separately by using the `--ulimit` argument with respective ulimits as appropriate in your environment. |

+|Enable user namespace support<br />_(2.08) |Description: The Linux kernel user namespace support in Docker daemon provides additional security for the Docker host system. It allows a container to have a unique range of user and group IDs which are outside the traditional user and group range utilized by the host system. For example, the root user will have expected administrative privilege inside the container but can effectively be mapped to an unprivileged UID on the host system. |Please consult Docker documentation for various ways in which this can be configured depending upon your requirements. Your steps might also vary based on platform - For example, on Red Hat, sub-UIDs and sub-GIDs mapping creation does not work automatically. You might have to create your own mapping. However, the high-level steps are as below: **Step 1:** Ensure that the files `/etc/subuid` and `/etc/subgid` exist.```touch /etc/subuid /etc/subgid```**Step 2:** Start the docker daemon with `--userns-remap` flag ```dockerd --userns-remap=default``` |

+|Ensure base device size isn't changed until needed<br />_(2.10) |Description: Increasing the base device size allows all future images and containers to be of the new base device size, this may cause a denial of service by ending up in file system being over-allocated or full. |remove `--storage-opt dm.basesize` flag from the dockerd start command until you need it |

+|Ensure that authorization for Docker client commands is enabled<br />_(2.11) |Description: DockerΓÇÖs out-of-the-box authorization model is all or nothing. Any user with permission to access the Docker daemon can run any Docker client command. The same is true for callers using DockerΓÇÖs remote API to contact the daemon. If you require greater access control, you can create authorization plugins and add them to your Docker daemon configuration. Using an authorization plugin, a Docker administrator can configure granular access policies for managing access to Docker daemon. Third party integrations of Docker may implement their own authorization models to require authorization with the Docker daemon outside of docker's native authorization plugin (i.e. Kubernetes, Cloud Foundry, OpenShift). |**Step 1**: Install/Create an authorization plugin. **Step 2**: Configure the authorization policy as desired. **Step 3**: Start the docker daemon as below: ```dockerd --authorization-plugin=``` |

+|Ensure centralized and remote logging is configured<br />_(2.12) |Description: Centralized and remote logging ensures that all important log records are safe despite catastrophic events. Docker now supports various such logging drivers. Use the one that suits your environment the best. |**Step 1**: Setup the desired log driver by following its documentation. **Step 2**: Start the docker daemon with that logging driver. For example, ```dockerd --log-driver=syslog --log-opt syslog-address=tcp://192.xxx.xxx.xxx``` |

+|Ensure live restore is Enabled<br />_(2.14) |Description: One of the important security triads is availability. Setting `--live-restore` flag in the docker daemon ensures that container execution isn't interrupted when the docker daemon isn't available. This also means that it's now easier to update and patch the docker daemon without execution downtime. |Run the docker in daemon mode and pass `--live-restore` as an argument. For Example,```dockerd --live-restore``` |

+|Ensure Userland Proxy is Disabled<br />_(2.15) |Description: Docker engine provides two mechanisms for forwarding ports from the host to containers, hairpin NAT, and a userland proxy. In most circumstances, the hairpin NAT mode is preferred as it improves performance and makes use of native Linux iptables functionality instead of an additional component. Where hairpin NAT is available, the userland proxy should be disabled on startup to reduce the attack surface of the installation. |Run the Docker daemon as below: ```dockerd --userland-proxy=false``` |

+|Ensure experimental features are avoided in production<br />_(2.17) |Description: Experimental is now a runtime docker daemon flag instead of a separate build. Passing `--experimental` as a runtime flag to the docker daemon, activates experimental features. Experimental is now considered a stable release, but with a couple of features which might not have tested and guaranteed API stability. |Don't pass `--experimental` as a runtime parameter to the docker daemon. |

+|Ensure containers are restricted from acquiring new privileges.<br />_(2.18) |Description: A process can set the `no_new_priv` bit in the kernel. It persists across fork, clone and execve. The `no_new_priv` bit ensures that the process or its children processes don't gain any additional privileges via suid or sgid bits. This way numerous dangerous operations become a lot less dangerous because there's no possibility of subverting privileged binaries. Setting this at the daemon level ensures that by default all new containers are restricted from acquiring new privileges. |Run the Docker daemon as below: ```dockerd --no-new-privileges``` |

+|Ensure that docker.service file ownership is set to root:root.<br />_(3.01) |Description: `docker.service` file contains sensitive parameters that may alter the behavior of Docker daemon. Hence, it should be owned and group-owned by `root` to maintain the integrity of the file. |**Step 1**: Find out the file location: ```systemctl show -p FragmentPath docker.service``` **Step 2**: If the file does not exist, this recommendation isn't applicable. If the file exists, execute the below command with the correct file path to set the ownership and group ownership for the file to `root`. For example, ```chown root:root /usr/lib/systemd/system/docker.service``` |

+|Ensure that docker .service file permissions are set to 644 or more restrictive<br />_(3.02) |Description: `docker.service` file contains sensitive parameters that may alter the behavior of Docker daemon. Hence, it shouldn't be writable by any other user other than `root` to maintain the integrity of the file. |**Step 1**: Find out the file location: ```systemctl show -p FragmentPath docker.service``` **Step 2**: If the file does not exist, this recommendation isn't applicable. If the file exists, execute the below command with the correct file path to set the file permissions to `644`. For example, ```chmod 644 /usr/lib/systemd/system/docker.service``` |

+|Ensure that docker.socket file ownership is set to root:root.<br />_(3.03) |Description: `docker.socket` file contains sensitive parameters that may alter the behavior of Docker remote API. Hence, it should be owned and group-owned by `root` to maintain the integrity of the file. |**Step 1**: Find out the file location: ```systemctl show -p FragmentPath docker.socket``` **Step 2**: If the file does not exist, this recommendation isn't applicable. If the file exists, execute the below command with the correct file path to set the ownership and group ownership for the file to `root`. For example, ```chown root:root /usr/lib/systemd/system/docker.socket``` |

+|Ensure that docker.socket file permissions are set to `644` or more restrictive<br />_(3.04) |Description: `docker.socket` file contains sensitive parameters that may alter the behavior of Docker daemon. Hence, it shouldn't be writable by any other user other than `root` to maintain the integrity of the file. |**Step 1**: Find out the file location: ```systemctl show -p FragmentPath docker.socket``` **Step 2**: If the file does not exist, this recommendation isn't applicable. If the file exists, execute the below command with the correct file path to set the file permissions to `644`. For example, ```chmod 644 /usr/lib/systemd/system/docker.service``` |

+|Ensure that /etc/docker directory ownership is set to `root:root`.<br />_(3.05) |Description: /etc/docker directory contains certificates and keys in addition to various sensitive files. Hence, it should be owned and group-owned by `root` to maintain the integrity of the directory. | ```chown root:root /etc/docker``` This would set the ownership and group-ownership for the directory to `root`. |

+|Ensure that /etc/docker directory permissions are set to `755` or more restrictive<br />_(3.06) |Description: /etc/docker directory contains certificates and keys in addition to various sensitive files. Hence, it should only be writable by `root` to maintain the integrity of the directory. | ```chmod 755 /etc/docker``` This would set the permissions for the directory to `755`. |

+|Ensure that registry certificate file ownership is set to root:root<br />_(3.07) |Description: /etc/docker/certs.d/ directory contains Docker registry certificates. These certificate files must be owned and group-owned by `root` to maintain the integrity of the certificates. | ```chown root:root /etc/docker/certs.d//*``` This would set the ownership and group-ownership for the registry certificate files to `root`. |

+|Ensure that registry certificate file permissions are set to `444` or more restrictive<br />_(3.08) |Description: /etc/docker/certs.d/ directory contains Docker registry certificates. These certificate files must have permissions of `444` to maintain the integrity of the certificates. | ```chmod 444 /etc/docker/certs.d//*``` This would set the permissions for registry certificate files to `444`. |

+|Ensure that TLS CA certificate file ownership is set to root:root<br />_(3.09) |Description: The TLS CA certificate file should be protected from any tampering. It's used to authenticate Docker server based on given CA certificate. Hence, it must be owned and group-owned by `root` to maintain the integrity of the CA certificate. |```chown root:root``` This would set the ownership and group-ownership for the TLS CA certificate file to `root`. |

+|Ensure that TLS CA certificate file permissions are set to `444` or more restrictive<br />_(3.10) |Description: The TLS CA certificate file should be protected from any tampering. It's used to authenticate Docker server based on given CA certificate. Hence, it must have permissions of `444` to maintain the integrity of the CA certificate. | ```chmod 444``` This would set the file permissions of the TLS CA file to `444`. |

+|Ensure that Docker server certificate file ownership is set to root:root<br />_(3.11) |Description: The Docker server certificate file should be protected from any tampering. It's used to authenticate Docker server based on the given server certificate. Hence, it must be owned and group-owned by `root` to maintain the integrity of the certificate. | ```chown root:root``` This would set the ownership and group-ownership for the Docker server certificate file to `root`. |

+|Ensure that Docker server certificate file permissions are set to `444` or more restrictive<br />_(3.12) |Description: The Docker server certificate file should be protected from any tampering. It's used to authenticate Docker server based on the given server certificate. Hence, it must have permissions of `444` to maintain the integrity of the certificate. | ```chmod 444``` This would set the file permissions of the Docker server file to `444`. |

+|Ensure that Docker server certificate key file ownership is set to root:root<br />_(3.13) |Description: The Docker server certificate key file should be protected from any tampering or unneeded reads. It holds the private key for the Docker server certificate. Hence, it must be owned and group-owned by `root` to maintain the integrity of the Docker server certificate. | ```chown root:root``` This would set the ownership and group-ownership for the Docker server certificate key file to `root`. |

+|Ensure that Docker server certificate key file permissions are set to 400<br />_(3.14) |Description: The Docker server certificate key file should be protected from any tampering or unneeded reads. It holds the private key for the Docker server certificate. Hence, it must have permissions of `400` to maintain the integrity of the Docker server certificate. | ```chmod 400``` This would set the Docker server certificate key file permissions to `400`. |

+|Ensure that Docker socket file ownership is set to root:docker<br />_(3.15) |Description: Docker daemon runs as `root`. The default Unix socket hence must be owned by `root`. If any other user or process owns this socket, then it might be possible for that non-privileged user or process to interact with Docker daemon. Also, such a non-privileged user or process might interact with containers. This is neither secure nor desired behavior. Additionally, the Docker installer creates a Unix group called `docker`. You can add users to this group, and then those users would be able to read and write to default Docker Unix socket. The membership to the `docker` group is tightly controlled by the system administrator. If any other group owns this socket, then it might be possible for members of that group to interact with Docker daemon. Also, such a group might not be as tightly controlled as the `docker` group. This is neither secure nor desired behavior. Hence, the default Docker Unix socket file must be owned by `root` and group-owned by `docker` to maintain the integrity of the socket file. | ```chown root:docker /var/run/docker.sock``` This would set the ownership to `root` and group-ownership to `docker` for default Docker socket file. |

+|Ensure that Docker socket file permissions are set to `660` or more restrictive<br />_(3.16) |Description: Only `root` and members of `docker` group should be allowed to read and write to default Docker Unix socket. Hence, the Docket socket file must have permissions of `660` or more restrictive. | ```chmod 660 /var/run/docker.sock``` This would set the file permissions of the Docker socket file to `660`. |

+|Ensure that daemon.json file ownership is set to root:root<br />_(3.17) |Description: `daemon.json` file contains sensitive parameters that may alter the behavior of docker daemon. Hence, it should be owned and group-owned by `root` to maintain the integrity of the file. | ```chown root:root /etc/docker/daemon.json``` This would set the ownership and group-ownership for the file to `root`. |

+|Ensure that daemon.json file permissions are set to 644 or more restrictive<br />_(3.18) |Description: `daemon.json` file contains sensitive parameters that may alter the behavior of docker daemon. Hence, it should be writable only by `root` to maintain the integrity of the file. | ```chmod 644 /etc/docker/daemon.json``` This would set the file permissions for this file to `644`. |

+|Ensure that /etc/default/docker file ownership is set to root:root<br />_(3.19) |Description: `/etc/default/docker` file contains sensitive parameters that may alter the behavior of docker daemon. Hence, it should be owned and group-owned by `root` to maintain the integrity of the file. | ```chown root:root /etc/default/docker``` This would set the ownership and group-ownership for the file to `root`. |

+|Ensure that /etc/default/docker file permissions are set to 644 or more restrictive<br />_(3.20) |Description: /etc/default/docker file contains sensitive parameters that may alter the behavior of docker daemon. Hence, it should be writable only by `root` to maintain the integrity of the file. | ```chmod 644 /etc/default/docker``` This would set the file permissions for this file to `644`. |

+|Ensure a user for the container has been created<br />_(4.01) |Description: it's a good practice to run the container as a non-root user, if possible. Though user namespace mapping is now available, if a user is already defined in the container image, the container is run as that user by default and specific user namespace remapping isn't required. |Ensure that the Dockerfile for the container image contains: `USER {username or ID}` where username or ID refers to the user that could be found in the container base image. If there's no specific user created in the container base image, then add a useradd command to add the specific user before USER instruction. |

+|Ensure HEALTHCHECK instructions have been added to the container image<br />_(4.06) |Description: One of the important security triads is availability. Adding `HEALTHCHECK` instruction to your container image ensures that the docker engine periodically checks the running container instances against that instruction to ensure that the instances are still working. Based on the reported health status, the docker engine could then exit non-working containers and instantiate new ones. |Follow Docker documentation and rebuild your container image with `HEALTHCHECK` instruction. |

+|Ensure either SELinux or AppArmor is enabled as appropriate<br />_(5.01-2) |Description: AppArmor protects the Linux OS and applications from various threats by enforcing security policy which is also known as AppArmor profile. You can create your own AppArmor profile for containers or use the Docker's default AppArmor profile. This would enforce security policies on the containers as defined in the profile. SELinux provides a Mandatory Access Control (MAC) system that greatly augments the default Discretionary Access Control (DAC) model. You can thus add an extra layer of safety by enabling SELinux on your Linux host, if applicable. |After enabling the relevant Mandatory Access Control Plugin for your distro, run the docker daemon as ```docker run --interactive --tty --security-opt="apparmor:PROFILENAME" centos /bin/bash``` for AppArmor or ```docker run --interactive --tty --security-opt label=level:TopSecret centos /bin/bash``` for SELinux. |

+|Ensure Linux Kernel Capabilities are restricted within containers<br />_(5.03) |Description: Docker supports the addition and removal of capabilities, allowing the use of a non-default profile. This may make Docker more secure through capability removal, or less secure through the addition of capabilities. It's thus recommended to remove all capabilities except those explicitly required for your container process. For example, capabilities such as below are usually not needed for container process: ```NET_ADMIN SYS_ADMIN SYS_MODULE``` |Execute the below command to add needed capabilities: ```$> docker run --cap-add={"Capability 1","Capability 2"}``` For example,```docker run --interactive --tty --cap-add={"NET_ADMIN","SYS_ADMIN"} centos:latest /bin/bash``` Execute the below command to drop unneeded capabilities: ```$> docker run --cap-drop={"Capability 1","Capability 2"}``` For example,```docker run --interactive --tty --cap-drop={"SETUID","SETGID"} centos:latest /bin/bash``` Alternatively, You may choose to drop all capabilities and add only the needed ones: $> docker run --cap-drop=all --cap-add={"Capability 1","Capability 2"} For example, ```docker run --interactive --tty --cap-drop=all --cap-add={"NET_ADMIN","SYS_ADMIN"} centos:latest /bin/bash``` |

+|Ensure privileged containers aren't used<br />_(5.04) |Description: The `--privileged` flag gives all capabilities to the container, and it also lifts all the limitations enforced by the device cgroup controller. In other words, the container can then do almost everything that the host can do. This flag exists to allow special use-cases, like running Docker within Docker. |Don't run container with the `--privileged` flag. For example, don't start a container as below: ```docker run --interactive --tty --privileged centos /bin/bash``` |

+|Ensure sensitive host system directories aren't mounted on containers<br />_(5.05) |Description: If sensitive directories are mounted in read-write mode, it would be possible to make changes to files within those sensitive directories. The changes might bring down security implications or unwarranted changes that could put the Docker host in compromised state. |Don't mount host sensitive directories on containers especially in read-write mode. |

+|Ensure the host's network namespace isn't shared<br />_(5.09) |Description: This is potentially dangerous. It allows the container process to open low-numbered ports like any other `root` process. It also allows the container to access network services like D-bus on the Docker host. Thus, a container process can potentially do unexpected things such as shutting down the Docker host. You shouldn't use this option. |Don't pass `--net=host` option when starting the container. |

+|Ensure memory usage for container is limited<br />_(5.10) |Description: By default, container can use all of the memory on the host. You can use memory limit mechanism to prevent a denial of service arising from one container consuming all of the hostΓÇÖs resources such that other containers on the same host cannot perform their intended functions. Having no limit on memory can lead to issues where one container can easily make the whole system unstable and as a result unusable. |Run the container with only as much memory as required. Always run the container using the `--memory` argument. For example, you could run a container as below: ```docker run --interactive --tty --memory 256m centos /bin/bash``` In the above example, the container is started with a memory limit of 256 MB. Note: Please note that the output of the below command would return values in scientific notation if memory limits are in place. ```docker inspect --format='{{.Config.Memory}}' 7c5a2d4c7fe0``` For example, if the memory limit's set to `256 MB` for the above container instance, the output of the above command would be `2.68435456e+08` and NOT 256m. You should convert this value using a scientific calculator or programmatic methods. |

+|Ensure the container's root filesystem is mounted as read only<br />_(5.12) |Description: Enabling this option forces containers at runtime to explicitly define their data writing strategy to persist or not persist their data. This also reduces security attack vectors since the container instance's filesystem cannot be tampered with or written to unless it has explicit read-write permissions on its filesystem folder and directories. |Add a `--read-only` flag at a container's runtime to enforce the container's root filesystem to be mounted as read only.```docker run --read-only``` Enabling the `--read-only` option at a container's runtime should be used by administrators to force a container's executable processes to only write container data to explicit storage locations during the container's runtime. Examples of explicit storage locations during a container's runtime include, but not limited to: 1. Use the `--tmpfs` option to mount a temporary file system for non-persistent data writes. ```docker run --interactive --tty --read-only --tmpfs "/run" --tmpfs "/tmp" centos /bin/bash``` 2. Enabling Docker `rw` mounts at a container's runtime to persist container data directly on the Docker host filesystem. ```docker run --interactive --tty --read-only -v /opt/app/data:/run/app/data:rw centos /bin/bash``` 3. Utilizing Docker shared-storage volume plugins for Docker data volume to persist container data. ```docker volume create -d convoy --opt o=size=20GB my-named-volume``````docker run --interactive --tty --read-only -v my-named-volume:/run/app/data centos /bin/bash``` 4. Transmitting container data outside of the docker during the container's runtime for container data to persist container data. Examples include hosted databases, network file shares, and APIs. |

+|Ensure incoming container traffic is bound to a specific host interface<br />_(5.13) |Description: If you have multiple network interfaces on your host machine, the container can accept connections on the exposed ports on any network interface. This might not be desired and may not be secured. Many times a particular interface is exposed externally and services such as intrusion detection, intrusion prevention, firewall, load balancing, etc. are run on those interfaces to screen incoming public traffic. Hence, you shouldn't accept incoming connections on any interface. You should only allow incoming connections from a particular external interface. |Bind the container port to a specific host interface on the desired host port. For example, ```docker run --detach --publish 10.2.3.4:49153:80 nginx``` In the example above, the container port `80` is bound to the host port on `49153` and would accept incoming connection only from `10.2.3.4` external interface. |

+|Ensure 'on-failure' container restart policy is set to '5' or lower<br />_(5.14) |Description: If you indefinitely keep trying to start the container, it could possibly lead to a denial of service on the host. It could be an easy way to do a distributed denial of service attack especially if you have many containers on the same host. Additionally, ignoring the exit status of the container and `always` attempting to restart the container leads to non-investigation of the root cause behind containers getting terminated. If a container gets terminated, you should investigate on the reason behind it instead of just attempting to restart it indefinitely. Thus, it's recommended to use `on-failure` restart policy and limit it to maximum of `5` restart attempts. |If a container is desired to be restarted of its own then, for example, you could start the container as below: ```docker run --detach --restart=on-failure:5 nginx``` |

+|Ensure the host's process namespace isn't shared<br />_(5.15) |Description: PID namespace provides separation of processes. The PID Namespace removes the view of the system processes, and allows process ID's to be reused including PID `1`. If the host's PID namespace is shared with the container, it would basically allow processes within the container to see all of the processes on the host system. This breaks the benefit of process level isolation between the host and the containers. Someone having access to the container can eventually know all the processes running on the host system and can even kill the host system processes from within the container. This can be catastrophic. Hence, don't share the host's process namespace with the containers. |Don't start a container with `--pid=host` argument. For example, don't start a container as below: ```docker run --interactive --tty --pid=host centos /bin/bash``` |

+|Ensure the host's IPC namespace isn't shared<br />_(5.16) |Description: IPC namespace provides separation of IPC between the host and containers. If the host's IPC namespace is shared with the container, it would basically allow processes within the container to see all of the IPC on the host system. This breaks the benefit of IPC level isolation between the host and the containers. Someone having access to the container can eventually manipulate the host IPC. This can be catastrophic. Hence, don't share the host's IPC namespace with the containers. |Don't start a container with `--ipc=host` argument. For example, don't start a container as below: ```docker run --interactive --tty --ipc=host centos /bin/bas``` |

+|Ensure host devices aren't directly exposed to containers<br />_(5.17) |Description: The `--device` option exposes the host devices to the containers and consequently, the containers can directly access such host devices. You would not require the container to run in `privileged` mode to access and manipulate the host devices. By default, the container will be able to read, write and mknod these devices. Additionally, it's possible for containers to remove block devices from the host. Hence, don't expose host devices to containers directly. If at all, you would want to expose the host device to a container, use the sharing permissions appropriately: - r - read only - w - writable - m - mknod allowed |Don't directly expose the host devices to containers. If at all, you need to expose the host devices to containers, use the correct set of permissions: For example, don't start a container as below: ```docker run --interactive --tty --device=/dev/tty0:/dev/tty0:rwm --device=/dev/temp_sda:/dev/temp_sda:rwm centos bash``` For example, share the host device with correct permissions: ```docker run --interactive --tty --device=/dev/tty0:/dev/tty0:rw --device=/dev/temp_sda:/dev/temp_sda:r centos bash``` |

+|Ensure mount propagation mode isn't set to shared<br />_(5.19) |Description: A shared mount is replicated at all mounts and the changes made at any mount point are propagated to all mounts. Mounting a volume in shared mode does not restrict any other container to mount and make changes to that volume. This might be catastrophic if the mounted volume is sensitive to changes. Don't set mount propagation mode to shared until needed. |Don't mount volumes in shared mode propagation. For example, don't start container as below: ```docker run --volume=/hostPath:/containerPath:shared``` |

+|Ensure the host's UTS namespace isn't shared<br />_(5.20) |Description: Sharing the UTS namespace with the host provides full permission to the container to change the hostname of the host. This is insecure and shouldn't be allowed. |Don't start a container with `--uts=host` argument. For example, don't start a container as below: ```docker run --rm --interactive --tty --uts=host rhel7.2``` |

+|Ensure cgroup usage is confirmed<br />_(5.24) |Description: System administrators typically define cgroups under which containers are supposed to run. Even if cgroups aren't explicitly defined by the system administrators, containers run under `docker` cgroup by default. At run-time, it's possible to attach to a different cgroup other than the one that was expected to be used. This usage should be monitored and confirmed. By attaching to a different cgroup than the one that is expected, excess permissions and resources might be granted to the container and thus, can prove to be unsafe. |Don't use `--cgroup-parent` option in `docker run` command unless needed. |

+|Ensure the container is restricted from acquiring additional privileges<br />_(5.25) |Description: A process can set the `no_new_priv` bit in the kernel. It persists across fork, clone and execve. The `no_new_priv` bit ensures that the process or its children processes don't gain any additional privileges via suid or sgid bits. This way numerous dangerous operations become a lot less dangerous because there's no possibility of subverting privileged binaries. |For example, you should start your container as below: ```docker run --rm -it --security-opt=no-new-privileges ubuntu bash``` |

+|Ensure container health is checked at runtime<br />_(5.26) |Description: One of the important security triads is availability. If the container image you're using does not have a pre-defined `HEALTHCHECK` instruction, use the `--health-cmd` parameter to check container health at runtime. Based on the reported health status, you could take necessary actions. |Run the container using `--health-cmd` and the other parameters. For example, ```docker run -d --health-cmd='stat /etc/passwd || exit 1' nginx``` |

+|Ensure PIDs cgroup limit's used<br />_(5.28) |Description: Attackers could launch a fork bomb with a single command inside the container. This fork bomb can crash the entire system and requires a restart of the host to make the system functional again. PIDs cgroup `--pids-limit` will prevent this kind of attacks by restricting the number of forks that can happen inside a container at a given time. |Use `--pids-limit` flag while launching the container with an appropriate value. For example, ```docker run -it --pids-limit 100``` In the above example, the number of processes allowed to run at any given time is set to 100. After a limit of 100 concurrently running processes is reached, docker would restrict any new process creation. |

+|Ensure Docker's default bridge docker0 isn't used<br />_(5.29) |Description: Docker connects virtual interfaces created in the bridge mode to a common bridge called `docker0`. This default networking model is vulnerable to ARP spoofing and MAC flooding attacks since there's no filtering applied. |Follow Docker documentation and setup a user-defined network. Run all the containers in the defined network. |

+|Ensure the host's user namespace isn't shared<br />_(5.30) |Description: User namespaces ensure that a root process inside the container will be mapped to a non-root process outside the container. Sharing the user namespaces of the host with the container thus does not isolate users on the host with users on the containers. |Don't share user namespaces between host and containers. For example, don't run a container as below: ```docker run --rm -it --userns=host ubuntu bash``` |

+|Ensure the Docker socket isn't mounted inside any containers<br />_(5.31) |Description: If the docker socket is mounted inside a container it would allow processes running within the container to execute docker commands which effectively allows for full control of the host. |Ensure that no containers mount `docker.sock` as a volume. |

+|Ensure swarm services are bound to a specific host interface<br />_(7.03) |Description: When a swarm is initialized the default value for the `--listen-addr` flag is `0.0.0.0:2377` which means that the swarm services will listen on all interfaces on the host. If a host has multiple network interfaces this may be undesirable as it may expose the docker swarm services to networks which aren't involved in the operation of the swarm. By passing a specific IP address to the `--listen-addr`, a specific network interface can be specified limiting this exposure. |Remediation of this requires re-initialization of the swarm specifying a specific interface for the `--listen-addr` parameter. |

+|Ensure data exchanged between containers are encrypted on different nodes on the overlay network<br />_(7.04) |Description: By default, data exchanged between containers on different nodes on the overlay network isn't encrypted. This could potentially expose traffic between the container nodes. |Create overlay network with `--opt encrypted` flag. |

+|Ensure swarm manager is run in auto-lock mode<br />_(7.06) |Description: When Docker restarts, both the TLS key used to encrypt communication among swarm nodes, and the key used to encrypt and decrypt Raft logs on disk, are loaded into each manager node's memory. You should protect the mutual TLS encryption key and the key used to encrypt and decrypt Raft logs at rest. This protection could be enabled by initializing swarm with `--autolock` flag. With `--autolock` enabled, when Docker restarts, you must unlock the swarm first, using a key encryption key generated by Docker when the swarm was initialized. |If you're initializing swarm, use the below command. ```docker swarm init --autolock``` If you want to set `--autolock` on an existing swarm manager node, use the below command.```docker swarm update --autolock``` |

+> [!NOTE]

+> Availability of specific Azure Policy guest configuration settings may vary in Azure Government

+> and other national clouds.

+## Next steps

+Additional articles about Azure Policy and guest configuration:

+- [Understand the guest configuration feature of Azure Policy]Understand the guest configuration feature of Azure Polic(../concepts/guest-configuration.md).

+- [Regulatory Compliance](../concepts/regulatory-compliance.md) overview.

+- Review other examples at [Azure Policy samples](./index.md).

+- Review [Understanding policy effects](../concepts/effects.md).

+- Learn how to [remediate non-compliant resources](../how-to/remediate-resources.md).

+* Install [Visual Studio](https://visualstudio.microsoft.com/vs/) 2022 with the ['Desktop development with C++'](/cpp/ide/using-the-visual-studio-ide-for-cpp-desktop-development) workload enabled. Visual Studio 2015, Visual Studio 2017, and Visual Studio 19 are also supported. For Linux or macOS, see the appropriate section in [Prepare your development environment](https://github.com/Azure/azure-iot-sdk-c/blob/master/doc/devbox_setup.md) in the SDK documentation.

+* Install the latest [CMake build system](https://cmake.org/download/). Make sure you check the option that adds the CMake executable to your path.

+ >[!IMPORTANT]

+ >Confirm that the Visual Studio prerequisites (Visual Studio and the 'Desktop development with C++' workload) are installed on your machine, **before** starting the `CMake` installation. Once the prerequisites are in place, and the download is verified, install the CMake build system. Also, be aware that older versions of the CMake build system fail to generate the solution file used in this article. Make sure to use the latest version of CMake.

+The following prerequisites are for a Windows development environment. For Linux or macOS, see the appropriate section in [Prepare your development environment](https://github.com/Azure/azure-iot-sdk-csharp/blob/main/doc/devbox_setup.md) in the SDK documentation.

+ ```cmd

+The following prerequisites are for a Windows development environment. For Linux or macOS, see the appropriate section in [Prepare your development environment](https://github.com/Azure/azure-iot-sdk-node/blob/main/doc/node-devbox-setup.md) in the SDK documentation.

+* Install [Node.js v4.0 or above](https://nodejs.org) on your machine.

+The following prerequisites are for a Windows development environment.

+* [Python 3.6 or later](https://www.python.org/downloads/) on your machine.

+The following prerequisites are for a Windows development environment. For Linux or macOS, see the appropriate section in [Prepare your development environment](https://github.com/Azure/azure-iot-sdk-jav) in the SDK documentation.

+* Make sure [OpenSSL](https://www.openssl.org/) is installed on your machine. On Windows, your installation of Git includes an installation of OpenSSL. You can access OpenSSL from the Git Bash prompt. To verify that OpenSSL is installed, open a Git Bash prompt and enter `openssl version`.

+ >[!NOTE]

+ > Unless you're familiar with OpenSSL and already have it installed on your Windows machine, we recommend using OpenSSL from the Git Bash prompt. Alternatively, you can choose to download the source code and build OpenSSL. To learn more, see the [OpenSSL Downloads](https://www.openssl.org/source/) page. Or, you can download OpenSSL pre-built from a third-party. To learn more, see the [OpenSSL wiki](https://wiki.openssl.org/index.php/Binaries). Microsoft makes no guarantees about the validity of packages downloaded from third-parties. If you do choose to build or download OpenSSL make sure that the OpenSSL binary is accessible in your path and that the `OPENSSL_CNF` environment variable is set to the path of your *openssl.cnf* file.

+* Open both a Windows command prompt and a Git Bash prompt.

+ The steps in this quickstart assume that you're using a Windows machine and the OpenSSL installation that is installed as part of Git. You'll use the Git Bash prompt to issue OpenSSL commands and the Windows command prompt for everything else. If you're using Linux, you can issue all commands from a Bash shell.

+1. Open a web browser, and go to the [Release page of the Azure IoT C SDK](https://github.com/Azure/azure-iot-sdk-c/releases/latest).

+2. Select the **Tags** tab at the top of the page.

+3. Copy the tag name for the latest release of the Azure IoT C SDK.

+4. In your Windows command prompt, run the following commands to clone the latest release of the [Azure IoT C SDK](https://github.com/Azure/azure-iot-sdk-c) GitHub repository. (replace `<release-tag>` with the tag you copied in the previous step).

+ ```cmd

+5. When the operation is complete, run the following commands from the `azure-iot-sdk-c` directory:

+ ```cmd

+6. The code sample uses an X.509 certificate to provide attestation via X.509 authentication. Run the following command to build a version of the SDK specific to your development platform that includes the device provisioning client. A Visual Studio solution for the simulated device is generated in the `cmake` directory.

+ When specifying the path used with `-Dhsm_custom_lib` in the command below, make sure to use the absolute path to the library in the `cmake` directory you previously created. The path shown below assumes that you cloned the C SDK in the root directory of the C drive. If you used another directory, adjust the path accordingly.

+ cmake -Duse_prov_client:BOOL=ON -Dhsm_custom_lib=c:/azure-iot-sdk-c/cmake/provisioning_client/samples/custom_hsm_example/Debug/custom_hsm_example.lib ..

+7. When the build succeeds, the last few output lines look similar to the following output:

+ ```cmd

+ cmake -Duse_prov_client:BOOL=ON -Dhsm_custom_lib=c:/azure-iot-sdk-c/cmake/provisioning_client/samples/custom_hsm_example/Debug/custom_hsm_example.lib ..