+Alternatively, you can add a link at the bottom of self-asserted pages, without using of JavaScript. Use the following localization:

+```xml

+<LocalizedResources Id="api.localaccountsignup.en">

+ <LocalizedStrings>

+ <!-- The following elements will display a link at the bottom of the page. -->

+ <LocalizedString ElementType="UxElement" StringId="disclaimer_link_1_text">Terms of use</LocalizedString>

+ <LocalizedString ElementType="UxElement" StringId="disclaimer_link_1_url">termsOfUseUrl</LocalizedString>

+ </LocalizedStrings>

+</LocalizedResources>

+```

+Replace `termsOfUseUrl` with the link to your organization's privacy policy and terms of use.

+### Sign-up and self-asserted pages disclaimer links

+The following `UxElement` string IDs will display disclaimer link(s) at the bottom of the self-asserted page. These links are not displayed by default unless specified in the localized strings.

+| ID | Example value |

+| | - |

+| **disclaimer_msg_intro** | By providing your phone number, you consent to receiving a one-time passcode sent by text message to help you sign into {insert your application name}. Standard messsage and data rates may apply. |

+| **disclaimer_link_1_text** | Privacy Statement |

+| **disclaimer_link_1_url** | {insert your privacy statement URL} |

+| **disclaimer_link_2_text** | Terms and Conditions |

+| **disclaimer_link_2_url** | {insert your terms and conditions URL} |

+ <!-- The following elements will display a message and two links at the bottom of the page.

+ For policies that you intend to show to users in the United States, we suggest displaying the following text. Replace the content of the disclaimer_link_X_url elements with links to your organization's privacy statement and terms and conditions.

+ Uncomment any of these lines to display them. -->

+ <!-- <LocalizedString ElementType="UxElement" StringId="disclaimer_msg_intro">By providing your phone number, you consent to receiving a one-time passcode sent by text message to help you sign into {insert your application name}. Standard messsage and data rates may apply.</LocalizedString> -->

+ <!-- <LocalizedString ElementType="UxElement" StringId="disclaimer_link_1_text">Privacy Statement</LocalizedString>

+ <LocalizedString ElementType="UxElement" StringId="disclaimer_link_1_url">{insert your privacy statement URL}</LocalizedString> -->

+ <!-- <LocalizedString ElementType="UxElement" StringId="disclaimer_link_2_text">Terms and Conditions</LocalizedString>

+ <LocalizedString ElementType="UxElement" StringId="disclaimer_link_2_url">{insert your terms and conditions URL}</LocalizedString> -->

+| setting.autosubmit | No | Specifies whether the technical profile should auto submit the one-time password entry form. Possible values are `true` (default), or `false`. When auto-submit is turned off, the user needs to select a button to progress the journey. |

+1. Once you're redirected to GitHub, click the pencil at the top of the article to start making changes

+## Multiple accounts on iOS (preview)

+You can enable passwordless phone sign-in for multiple accounts in Microsoft Authenticator on any supported iOS device. Consultants, students, and others with multiple accounts in Azure AD can add each account to Microsoft Authenticator and use passwordless phone sign-in for all of them from the same iOS device.

+Previously, admins might not require passwordless sign-in for users with multiple accounts because it requires them to carry more devices for sign-in. By removing the limitation of one user sign-in from a device, admins can more confidently encourage users to register passwordless phone sign-in and use it as their default sign-in method.

+The Azure AD accounts can be in the same tenant or different tenants. Guest accounts aren't supported for multiple account sign-in from one device.

+>[!NOTE]

+>Multiple accounts on iOS is currently in public preview. Some features might not be supported or have limited capabilities. For more information about previews, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).

+- For Android, the device that runs Microsoft Authenticator must be registered to an individual user. We're actively working to enable multiple accounts on Android.

+- For iOS, the device must be registered with each tenant where it's used to sign in. For example, the following device must be registered with Contoso and Wingtiptoys to allow all accounts to sign in:

+ - balas@contoso.com

+ - balas@wingtiptoys.com and bsandhu@wingtiptoys

+- For iOS, we recommend enabling the option in Microsoft Authenticator to allow Microsoft to gather usage data. It's not enabled by default. To enable it in Microsoft Authenticator, go to **Settings** > **Usage Data**.

+

+ :::image type="content" border="true" source="./media/howto-authentication-passwordless-phone/telemetry.png" alt-text="Screenshot of Usage Data in Microsoft Authenticator.":::

+- [Learn about Azure AD Multi-Factor Authentication](../authentication/howto-mfa-getstarted.md)

+> [!NOTE]

+> The Permissions Management Administrator for all authorization systems will be able to create the new group based permissions.

+- Security & compliance portal

+When Conditional Access policy is targeted to the Microsoft Azure Management application, within the Conditional Access policy app picker the policy will be enforced for tokens issued to application IDs of a set of services closely bound to the portal.

+- Azure Resource Manager

+- Azure portal, which also covers the Microsoft Entra admin center

+- Azure Data Lake

+- Application Insights API

+- Log Analytics API

+Because the policy is applied to the Azure management portal and API, services, or clients with an Azure API service dependency, can indirectly be impacted. For example:

+- Classic deployment model APIs

+- Azure PowerShell

+- Azure CLI

+- Azure DevOps

+- Azure Data Factory portal

+- Azure Event Hubs

+- Azure Service Bus

+- [Azure SQL Database](/azure/azure-sql/database/conditional-access-configure)

+- SQL Managed Instance

+- Azure Synapse

+- Visual Studio subscriptions administrator portal

+> [!TIP]

+> For Azure Government, you should target the Azure Government Cloud Management API application.

+Some applications don't appear in the picker at all. The only way to include these applications in a Conditional Access policy is to includeΓÇ»**All cloud apps**.

+### All cloud apps

+Applying a Conditional Access policy to **All cloud apps** will result in the policy being enforced for all tokens issued to web sites and services. This option includes applications that aren't individually targetable in Conditional Access policy, such as Azure Active Directory.

+In some cases, an **All cloud apps** policy could inadvertently block user access. These cases are excluded from policy enforcement and include:

+- Services required to achieve the desired security posture. For example, device enrollment calls are excluded from compliant device policy targeted to All cloud apps.

+- Calls to Azure AD Graph and MS Graph, to access user profile, group membership and relationship information that is commonly used by applications excluded from policy. The excluded scopes are listed below. Consent is still required for apps to use these permissions.

+ - For native clients:

+ - Azure AD Graph: User.read

+ - MS Graph: User.read, People.read, and UserProfile.read

+ - For confidential / authenticated clients:

+ - Azure AD Graph: User.read, User.read.all, and User.readbasic.all

+ - MS Graph: User.read,User.read.all, User.read.All People.read, People.read.all, GroupMember.Read.All, Member.Read.Hidden, and UserProfile.read

+You can use the Microsoft Defender for Endpoint app along with the Approved Client app policy in Intune to set device compliance policy Conditional Access policies. There's no exclusion required for the Microsoft Defender for Endpoint app while setting up Conditional Access. Although Microsoft Defender for Endpoint on Android & iOS (App ID - dd47d17a-3194-4d86-bfd5-c6ae6f5651e3) isn't an approved app, it has permission to report device security posture. This permission enables the flow of compliance information to Conditional Access.

+Microsoft recommends you require MFA on the following roles at a minimum, based on [identity score recommendations](../fundamentals/identity-secure-score.md):

+| AADSTS50194 | Application '{appId}'({appName}) isn't configured as a multi-tenant application. Usage of the /common endpoint isn't supported for such applications created after '{time}'. Use a tenant-specific endpoint or configure the application to be multi-tenant. |

+- [Pop-up window](#sign-in-with-a-pop-up-window), by using the `loginPopup` method

+- [Redirect](#sign-in-with-redirect), by using the `loginRedirect` method

+If your application already has access to an authenticated user context or ID token, you can skip the login step, and directly acquire tokens. For details, see [SSO with user hint](msal-js-sso.md#with-user-hint).

+- If you don't want users to move away from your main application page during authentication, we recommend the pop-up method. Because the authentication redirect happens in a pop-up window, the state of the main application is preserved.

+- If users have browser constraints or policies where pop-up windows are disabled, you can use the redirect method. Use the redirect method with the Internet Explorer browser, because there are [known issues with pop-up windows on Internet Explorer](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/internet-explorer.md#popups).

+ auth: {

+ clientId: "your_app_id",

+ redirectUri: "your_app_redirect_uri", //defaults to application start page

+ postLogoutRedirectUri: "your_app_logout_redirect_uri",

+ },

+};

+ scopes: ["User.ReadWrite"],

+};

+myMsal

+ .loginPopup(loginRequest)

+ .then(function (loginResponse) {

+ accountId = loginResponse.account.homeAccountId;

+ // Display signed-in user content, call API, etc.

+ })

+ .catch(function (error) {

+ //login failure

+ console.log(error);

+ });

+ auth: {

+ clientId: "your_app_id",

+ redirectUri: "your_app_redirect_uri", //defaults to application start page

+ postLogoutRedirectUri: "your_app_logout_redirect_uri",

+ },

+};

+ scopes: ["User.ReadWrite"],

+};

+myMsal

+ .loginPopup(loginRequest)

+ .then(function (loginResponse) {

+ //login success

+ })

+ .catch(function (error) {

+ //login failure

+ console.log(error);

+ });

+import { NgModule } from "@angular/core";

+import { Routes, RouterModule } from "@angular/router";

+import { ProfileComponent } from "./profile/profile.component";

+import { MsalGuard } from "@azure/msal-angular";

+import { HomeComponent } from "./home/home.component";

+ {

+ path: "profile",

+ component: ProfileComponent,

+ canActivate: [MsalGuard],

+ },

+ {

+ path: "",

+ component: HomeComponent,

+ },

+ imports: [RouterModule.forRoot(routes, { useHash: false })],

+ exports: [RouterModule],

+export class AppRoutingModule {}

+import { PublicClientApplication, InteractionType } from "@azure/msal-browser";

+import { MsalModule } from "@azure/msal-angular";

+ imports: [

+ MsalModule.forRoot(

+ new PublicClientApplication({

+ auth: {

+ clientId: "Enter_the_Application_Id_Here",

+ },

+ cache: {

+ cacheLocation: "localStorage",

+ storeAuthStateInCookie: isIE,

+ },

+ }),

+ {

+ interactionType: InteractionType.Popup, // Msal Guard Configuration

+ authRequest: {

+ scopes: ["user.read"],

+ },

+ },

+ null

+ ),

+ ],

+export class AppModule {}

+import { NgModule } from "@angular/core";

+import { Routes, RouterModule } from "@angular/router";

+import { ProfileComponent } from "./profile/profile.component";

+import { MsalGuard } from "@azure/msal-angular";

+import { HomeComponent } from "./home/home.component";

+ path: "profile",

+ canActivate: [MsalGuard],

+ path: "",

+ component: HomeComponent,

+ },

+ exports: [RouterModule],

+export class AppRoutingModule {}

+The MSAL React wrapper allows you to protect specific components by wrapping them in the `MsalAuthenticationTemplate` component. This component will invoke login if a user isn't already signed in or render child components otherwise.

+ const { accounts } = useMsal();

+ const username = accounts[0].username;

+ return <p>Welcome, {username}</p>;

+ return (

+ <MsalAuthenticationTemplate interactionType={InteractionType.Popup}>

+ <p>This will only render if a user is signed-in.</p>

+ <WelcomeUser />

+ </MsalAuthenticationTemplate>

+ );

+}

+import {

+ useMsal,

+ AuthenticatedTemplate,

+ UnauthenticatedTemplate,

+} from "@azure/msal-react";

+ instance.loginPopup();

+ // useMsal hook will return the PublicClientApplication instance you provided to MsalProvider

+ const { instance } = useMsal();

+ return <button onClick={() => signInClickHandler(instance)}>Sign In</button>;

+}

+ const { accounts } = useMsal();

+ const username = accounts[0].username;

+ return <p>Welcome, {username}</p>;

+ return (

+ <>

+ <AuthenticatedTemplate>

+ <p>This will only render if a user is signed-in.</p>

+ <WelcomeUser />

+ </AuthenticatedTemplate>

+ <UnauthenticatedTemplate>

+ <p>This will only render if a user is not signed-in.</p>

+ <SignInButton />

+ </UnauthenticatedTemplate>

+ </>

+ );

+ auth: {

+ clientId: "your_app_id",

+ redirectUri: "your_app_redirect_uri", //defaults to application start page

+ postLogoutRedirectUri: "your_app_logout_redirect_uri",

+ },

+};

+ scopes: ["User.ReadWrite"],

+};

+ if (response !== null) {

+ accountId = response.account.homeAccountId;

+ // Display signed-in user content, call API, etc.

+ } else {

+ // In case multiple accounts exist, you can select

+ const currentAccounts = myMsal.getAllAccounts();

+ if (currentAccounts.length === 0) {

+ // no accounts signed-in, attempt to sign a user in

+ myMsal.loginRedirect(loginRequest);

+ } else if (currentAccounts.length > 1) {

+ // Add choose account code here

+ } else if (currentAccounts.length === 1) {

+ accountId = currentAccounts[0].homeAccountId;

+ }

+ auth: {

+ clientId: "your_app_id",

+ redirectUri: "your_app_redirect_uri", //defaults to application start page

+ postLogoutRedirectUri: "your_app_logout_redirect_uri",

+ },

+};

+ scopes: ["User.ReadWrite"],

+};

+ //handle redirect response

+The code here's the same as described earlier in the section about sign-in with a pop-up window, except that the `interactionType` is set to `InteractionType.Redirect` for the MsalGuard Configuration, and the `MsalRedirectComponent` is bootstrapped to handle redirects.

+import { PublicClientApplication, InteractionType } from "@azure/msal-browser";

+import { MsalModule, MsalRedirectComponent } from "@azure/msal-angular";

+ imports: [

+ MsalModule.forRoot(

+ new PublicClientApplication({

+ auth: {

+ clientId: "Enter_the_Application_Id_Here",

+ },

+ cache: {

+ cacheLocation: "localStorage",

+ storeAuthStateInCookie: isIE,

+ },

+ }),

+ {

+ interactionType: InteractionType.Redirect, // Msal Guard Configuration

+ authRequest: {

+ scopes: ["user.read"],

+ },

+ },

+ null

+ ),

+ ],

+ bootstrap: [AppComponent, MsalRedirectComponent],

+export class AppModule {}

+The code here's the same as described earlier in the section about sign-in with a pop-up window. The default flow is redirect.

+The MSAL React wrapper allows you to protect specific components by wrapping them in the `MsalAuthenticationTemplate` component. This component will invoke login if a user isn't already signed in or render child components otherwise.

+ const { accounts } = useMsal();

+ const username = accounts[0].username;

+ return <p>Welcome, {username}</p>;

+ return (

+ <MsalAuthenticationTemplate interactionType={InteractionType.Redirect}>

+ <p>This will only render if a user is signed-in.</p>

+ <WelcomeUser />

+ </MsalAuthenticationTemplate>

+ );

+}

+import {

+ useMsal,

+ AuthenticatedTemplate,

+ UnauthenticatedTemplate,

+} from "@azure/msal-react";

+ instance.loginRedirect();

+ // useMsal hook will return the PublicClientApplication instance you provided to MsalProvider

+ const { instance } = useMsal();

+ return <button onClick={() => signInClickHandler(instance)}>Sign In</button>;

+}

+ const { accounts } = useMsal();

+ const username = accounts[0].username;

+ return <p>Welcome, {username}</p>;

+ return (

+ <>

+ <AuthenticatedTemplate>

+ <p>This will only render if a user is signed-in.</p>

+ <WelcomeUser />

+ </AuthenticatedTemplate>

+ <UnauthenticatedTemplate>

+ <p>This will only render if a user is not signed-in.</p>

+ <SignInButton />

+ </UnauthenticatedTemplate>

+ </>

+ );

+ auth: {

+ clientId: "your_app_id",

+ redirectUri: "your_app_redirect_uri", // defaults to application start page

+ postLogoutRedirectUri: "your_app_logout_redirect_uri",

+ },

+};

+ account: myMsal.getAccountByHomeId(homeAccountId),

+ mainWindowRedirectUri: "your_app_main_window_redirect_uri",

+};

+Signing out with a pop-up window isn't supported in MSAL.js v1

+Signing out with a pop-up window isn't supported in MSAL Angular v1

+import {

+ useMsal,

+ AuthenticatedTemplate,

+ UnauthenticatedTemplate,

+} from "@azure/msal-react";

+ const logoutRequest = {

+ account: instance.getAccountByHomeId(homeAccountId),

+ mainWindowRedirectUri: "your_app_main_window_redirect_uri",

+ postLogoutRedirectUri: "your_app_logout_redirect_uri",

+ };

+ instance.logoutPopup(logoutRequest);

+ // useMsal hook will return the PublicClientApplication instance you provided to MsalProvider

+ const { instance } = useMsal();

+ return (

+ <button onClick={() => signOutClickHandler(instance)}>Sign Out</button>

+ );

+}

+ return (

+ <>

+ <AuthenticatedTemplate>

+ <p>This will only render if a user is signed-in.</p>

+ <SignOutButton />

+ </AuthenticatedTemplate>

+ <UnauthenticatedTemplate>

+ <p>This will only render if a user is not signed-in.</p>

+ </UnauthenticatedTemplate>

+ </>

+ );

+MSAL.js provides a `logout` method in v1, and `logoutRedirect` method in v2 that clears the cache in browser storage and redirects the window to the Azure AD sign-out page. After sign-out, Azure AD redirects back to the page that invoked logout by default.

+ auth: {

+ clientId: "your_app_id",

+ redirectUri: "your_app_redirect_uri", //defaults to application start page

+ postLogoutRedirectUri: "your_app_logout_redirect_uri",

+ },

+};

+ account: myMsal.getAccountByHomeId(homeAccountId),

+};

+ auth: {

+ clientId: "your_app_id",

+ redirectUri: "your_app_redirect_uri", //defaults to application start page

+ postLogoutRedirectUri: "your_app_logout_redirect_uri",

+ },

+};

+import {

+ useMsal,

+ AuthenticatedTemplate,

+ UnauthenticatedTemplate,

+} from "@azure/msal-react";

+ const logoutRequest = {

+ account: instance.getAccountByHomeId(homeAccountId),

+ postLogoutRedirectUri: "your_app_logout_redirect_uri",

+ };

+ instance.logoutRedirect(logoutRequest);

+ // useMsal hook will return the PublicClientApplication instance you provided to MsalProvider

+ const { instance } = useMsal();

+ return (

+ <button onClick={() => signOutClickHandler(instance)}>Sign Out</button>

+ );

+}

+ return (

+ <>

+ <AuthenticatedTemplate>

+ <p>This will only render if a user is signed-in.</p>

+ <SignOutButton />

+ </AuthenticatedTemplate>

+ <UnauthenticatedTemplate>

+ <p>This will only render if a user is not signed-in.</p>

+ </UnauthenticatedTemplate>

+ </>

+ );

+Some organizations set goals to remove AD, and their on-premises IT footprint. Others take advantage of some cloud-based capabilities to reduce the AD footprint, but not to completely remove their on-premises environments. This content provides guidance to move:

+Transformation must be aligned with and achieve business objectives including increased productivity, reduced costs and complexity, and improved security posture. To better understand the costs vs. value of moving to the cloud, see [Forrester TEI for Microsoft Azure Active Directory](https://www.microsoft.com/security/business/forrester-tei-study) and other TEI reports and [Cloud economics](https://azure.microsoft.com/overview/cloud-economics/).

+1. In the **Enable review decision helpers** section choose whether you want your reviewer to receive recommendations during the review process:

+ 1. If you select **No sign-in within 30 days**, users who have signed in during the previous 30-day period are recommended for approval. Users who haven't signed in during the past 30 days are recommended for denial. This 30-day interval is irrespective of whether the sign-ins were interactive or not. The last sign-in date for the specified user will also display along with the recommendation.

+ 1. If you select **Peer outlier**, approvers will be recommended to keep or deny access to users based on the access the users' peers have. If a user doesn't have the same access as their peers, the system will recommend that the reviewer deny them access.

+ 

+To make access reviews easier and faster for you, we also provide recommendations that you can accept with a single click. There are two ways recommendations are generated for the reviewer. One method the system uses to create recommendations is by the user's sign-in activity. If a user has been inactive for 30 days or more, the reviewer will be recommended to deny access. The other method is based on the access the user's peers have. If the user doesn't have the same access as their peers, the reviewer will be recommended to deny that user access.

+If you have **No sign-in within 30 days** or **Peer outlier** enabled, follow the steps below to accept recommendations:

+ Title: Review recommendations for Access reviews - Azure AD

+description: Learn how to review access of group members with review recommendations in Azure Active Directory access reviews.

+editor: markwahl-msft

+ na

+# Review recommendations for Access reviews

+Decision makers who review users' access and perform access reviews can use system based recommendations to help them decide whether to continue their access or deny their access to resources. For more information about how to use review recommendations, see [Enable decision helpers](create-access-review.md#next-settings).

+## Prerequisites

+

+- Azure AD Premium P2

+

+For more information, see [License requirements](access-reviews-overview.md#license-requirements).

+## Peer outlier recommendations

+If review decision helpers are enabled by the creator of the access review, reviewers can receive peer outlier recommendations for reviews of group access reviews.

+Peer analysis recommendation detects users with outlier access to a group, based on reporting-structure similarity with other group members. The outlier recommendation relies on a scoring mechanism which is calculated by computing the userΓÇÖs average distance to the remaining users in the group.

+A *peer* in an organizationΓÇÖs chart is defined as two or more users who share similar characteristics in the organization's reporting structure. Users who are very distant from all the other group members based on their organization's chart, are considered a ΓÇ£peer outlierΓÇ¥ in a group.

+> [!NOTE]

+> Currently, this feature is only available for uses in your directory. Use of the peer outlier recommendations is not supported for guest users.

+The following image has an example of an organization's reporting structure in a cosmetics company:

+

+Based on the reporting structure in the example image, members outside of a division that is under a group review, would be denied access by the system if the peer outlier recommendation was taken by the reviewer.

+For example, Phil who works within the Personal care division is in a group with Debby, Irwin, and Emily who all work within the Cosmetics division. The group is called *Fresh Skin*. If an Access Review for the group Fresh Skin is performed, based on the reporting structure and distance away from the other group members, Phil would be considered an outlier. The system will create a **Deny** recommendation in the group access review.

+## Next Steps

+- [Create an access review](create-access-review.md)

+- [Review access to groups or applications](perform-access-review.md)

+The access review starts in a few minutes and it appears in your list with an indicator of its status.

+### View the status of an access review

+You can track the progress of access reviews as they are completed.

+

+1. Go to **Azure Active Directory**, and then select **Identity Governance**.

+1. In the left menu, select **Access reviews**.

+1. In the list, select the access review you created.

+1. On the **Overview** page, check the progress of the access review.

+The **Results** page provides information on each user under review in the instance, including the ability to Stop, Reset, and Download results. To learn more, check out the [Complete an access review of groups and applications in Azure AD access reviews](../governance/complete-access-review.md) article.

+> [Manage consent to applications and evaluate consent requests](manage-consent-requests.md)

+> | microsoft.directory/users/authenticationMethods/standard/restrictedRead | Read standard properties of authentication methods that do not include personally identifiable information for users |

+> | microsoft.directory/deletedItems.users/delete | Permanently delete users, which can no longer be restored |

+> | microsoft.directory/deletedItems.users/delete | Permanently delete users, which can no longer be restored |

+| - | - | - | - | - | - | - |

+ Title: 'Tutorial: Azure AD SSO integration with AMMS'

+# Tutorial: Azure AD SSO integration with AMMS

+In this tutorial, you'll learn how to integrate AMMS with Azure Active Directory (Azure AD). When you integrate AMMS with Azure AD, you can:

+* Control in Azure AD who has access to AMMS.

+* Enable your users to be automatically signed-in to AMMS with their Azure AD accounts.

+* Manage your accounts in one central location - the Azure portal.

+* An Azure AD subscription. If you don't have an Azure AD environment, you can get a [free account](https://azure.microsoft.com/free/).

+* AMMS single sign-on enabled subscription.

+* Along with Cloud Application Administrator, Application Administrator can also add or manage applications in Azure AD.

+For more information, see [Azure built-in roles](../roles/permissions-reference.md).

+* AMMS supports **SP** initiated SSO.

+## Add AMMS from the gallery

+1. Sign in to the Azure portal using either a work or school account, or a personal Microsoft account.

+1. On the left navigation pane, select the **Azure Active Directory** service.

+1. Navigate to **Enterprise Applications** and then select **All Applications**.

+1. To add new application, select **New application**.

+1. In the **Add from the gallery** section, type **AMMS** in the search box.

+1. Select **AMMS** from results panel and then add the app. Wait a few seconds while the app is added to your tenant.

+## Configure and test Azure AD SSO for AMMS

+Configure and test Azure AD SSO with AMMS using a test user called **B.Simon**. For SSO to work, you need to establish a link relationship between an Azure AD user and the related user in AMMS.

+To configure and test Azure AD SSO with AMMS, perform the following steps:

+1. **[Configure Azure AD SSO](#configure-azure-ad-sso)** - to enable your users to use this feature.

+ 1. **[Create an Azure AD test user](#create-an-azure-ad-test-user)** - to test Azure AD single sign-on with B.Simon.

+ 1. **[Assign the Azure AD test user](#assign-the-azure-ad-test-user)** - to enable B.Simon to use Azure AD single sign-on.

+1. **[Configure AMMS SSO](#configure-amms-sso)** - to configure the single sign-on settings on application side.

+ 1. **[Create AMMS test user](#create-amms-test-user)** - to have a counterpart of B.Simon in AMMS that is linked to the Azure AD representation of user.

+1. **[Test SSO](#test-sso)** - to verify whether the configuration works.

+## Configure Azure AD SSO

+Follow these steps to enable Azure AD SSO in the Azure portal.

+1. In the Azure portal, on the **AMMS** application integration page, find the **Manage** section and select **single sign-on**.

+1. On the **Select a single sign-on method** page, select **SAML**.

+1. On the **Set up single sign-on with SAML** page, click the pencil icon for **Basic SAML Configuration** to edit the settings.

+ 

+1. On the **Basic SAML Configuration** section, perform the following steps:

+ a. In the **Identifier (Entity ID)** text box, type a value using the following pattern:

+ `<SUBDOMAIN>.microwestcloud.com/amms`

+ b. In the **Sign on URL** text box, type a URL using the following pattern:

+ > These values are not real. Update these values with the actual Identifier and Sign on URL. Contact [AMMS Client support team](mailto:techsupport@microwestsoftware.com) to get these values. You can also refer to the patterns shown in the **Basic SAML Configuration** section in the Azure portal.

+ 

+In this section, you'll create a test user in the Azure portal called B.Simon.

+1. From the left pane in the Azure portal, select **Azure Active Directory**, select **Users**, and then select **All users**.

+1. Select **New user** at the top of the screen.

+1. In the **User** properties, follow these steps:

+ 1. In the **Name** field, enter `B.Simon`.

+ 1. In the **User name** field, enter the username@companydomain.extension. For example, `B.Simon@contoso.com`.

+ 1. Select the **Show password** check box, and then write down the value that's displayed in the **Password** box.

+ 1. Click **Create**.

+In this section, you'll enable B.Simon to use Azure single sign-on by granting access to AMMS.

+1. In the Azure portal, select **Enterprise Applications**, and then select **All applications**.

+1. In the applications list, select **AMMS**.

+1. In the app's overview page, find the **Manage** section and select **Users and groups**.

+1. Select **Add user**, then select **Users and groups** in the **Add Assignment** dialog.

+1. In the **Users and groups** dialog, select **B.Simon** from the Users list, then click the **Select** button at the bottom of the screen.

+1. If you're expecting any role value in the SAML assertion, in the **Select Role** dialog, select the appropriate role for the user from the list and then click the **Select** button at the bottom of the screen.

+1. In the **Add Assignment** dialog, click the **Assign** button.

+## Configure AMMS SSO

+To configure single sign-on on **AMMS** side, you need to send the **App Federation Metadata Url** to [AMMS support team](mailto:techsupport@microwestsoftware.com). They set this setting to have the SAML SSO connection set properly on both sides.

+## Test SSO

+In this section, you test your Azure AD single sign-on configuration with following options.

+* Click on **Test this application** in Azure portal. This will redirect to AMMS Sign-on URL where you can initiate the login flow.

+* Go to AMMS Sign-on URL directly and initiate the login flow from there.

+* You can use Microsoft My Apps. When you click the AMMS tile in the My Apps, this will redirect to AMMS Sign-on URL. For more information about the My Apps, see [Introduction to the My Apps](../user-help/my-apps-portal-end-user-access.md).

+## Next steps

+Once you configure AMMS you can enforce session control, which protects exfiltration and infiltration of your organizationΓÇÖs sensitive data in real time. Session control extends from Conditional Access. [Learn how to enforce session control with Microsoft Cloud App Security](/cloud-app-security/proxy-deployment-aad).

+# Tutorial: Azure AD SSO integration with Change Process Management

+* Along with Cloud Application Administrator, Application Administrator can also add or manage applications in Azure AD.

+For more information, see [Azure built-in roles](../roles/permissions-reference.md).

+## Scenario description

+1. Sign in to the Azure portal with a work or school account or with a personal Microsoft account.

+1. In the Azure portal, on the **Change Process Management** application integration page, in the **Manage** section, select **single sign-on**.

+ 

+1. On the **Basic SAML Configuration** section, perform the following steps:

+ a. In the **Identifier** box, type a URL using the following pattern:

+ b. In the **Reply URL** box, type a URL using the following pattern:

+ 

+ 

+Work with the [Change Process Management support team](mailto:support@realtech-us.com) to add a user named B.Simon in Change Process Management. Users must be created and activated before you use single sign-on.

+## Test SSO

+In this section, you test your Azure AD single sign-on configuration with following options.

+* Click on Test this application in Azure portal and you should be automatically signed in to the Change Process Management for which you set up the SSO.

+* You can use Microsoft My Apps. When you click the Change Process Management tile in the My Apps, you should be automatically signed in to the Change Process Management for which you set up the SSO. For more information about the My Apps, see [Introduction to the My Apps](../user-help/my-apps-portal-end-user-access.md).

+## Next steps

+Once you configure Change Process Management you can enforce session control, which protects exfiltration and infiltration of your organizationΓÇÖs sensitive data in real time. Session control extends from Conditional Access. [Learn how to enforce session control with Microsoft Cloud App Security](/cloud-app-security/proxy-deployment-aad).

+ Title: 'Tutorial: Azure AD SSO integration with Halosys'

+# Tutorial: Azure AD SSO integration with Halosys

+In this tutorial, you'll learn how to integrate Halosys with Azure Active Directory (Azure AD). When you integrate Halosys with Azure AD, you can:

+* Control in Azure AD who has access to Halosys.

+* Enable your users to be automatically signed-in to Halosys with their Azure AD accounts.

+* Manage your accounts in one central location - the Azure portal.

+To get started, you need the following items:

+* An Azure AD subscription. If you don't have a subscription, you can get a [free account](https://azure.microsoft.com/free/).

+* Halosys single sign-on (SSO) enabled subscription.

+* Along with Cloud Application Administrator, Application Administrator can also add or manage applications in Azure AD.

+For more information, see [Azure built-in roles](../roles/permissions-reference.md).

+* Halosys supports **IDP** initiated SSO.

+## Add Halosys from the gallery

+1. Sign in to the Azure portal using either a work or school account, or a personal Microsoft account.

+1. On the left navigation pane, select the **Azure Active Directory** service.

+1. Navigate to **Enterprise Applications** and then select **All Applications**.

+1. To add new application, select **New application**.

+1. In the **Add from the gallery** section, type **Halosys** in the search box.

+1. Select **Halosys** from results panel and then add the app. Wait a few seconds while the app is added to your tenant.

+## Configure and test Azure AD SSO for Halosys

+Configure and test Azure AD SSO with Halosys using a test user called **B.Simon**. For SSO to work, you need to establish a link relationship between an Azure AD user and the related user in Halosys.

+To configure and test Azure AD SSO with Halosys, perform the following steps:

+1. **[Configure Azure AD SSO](#configure-azure-ad-sso)** - to enable your users to use this feature.

+ 1. **[Create an Azure AD test user](#create-an-azure-ad-test-user)** - to test Azure AD single sign-on with B.Simon.

+ 1. **[Assign the Azure AD test user](#assign-the-azure-ad-test-user)** - to enable B.Simon to use Azure AD single sign-on.

+1. **[Configure Halosys SSO](#configure-halosys-sso)** - to configure the single sign-on settings on application side.

+ 1. **[Create Halosys test user](#create-halosys-test-user)** - to have a counterpart of B.Simon in Halosys that is linked to the Azure AD representation of user.

+1. **[Test SSO](#test-sso)** - to verify whether the configuration works.

+## Configure Azure AD SSO

+Follow these steps to enable Azure AD SSO in the Azure portal.

+1. In the Azure portal, on the **Halosys** application integration page, find the **Manage** section and select **single sign-on**.

+1. On the **Select a single sign-on method** page, select **SAML**.

+1. On the **Set up single sign-on with SAML** page, click the pencil icon for **Basic SAML Configuration** to edit the settings.

+ 

+1. On the **Basic SAML Configuration** section, perform the following steps:

+1. On the **Set up Single Sign-On with SAML** page, in the **SAML Signing Certificate** section, click **Download** to download the **Federation Metadata XML** from the given options as per your requirement and save it on your computer.

+ 

+1. On the **Set up Halosys** section, copy the appropriate URL(s) as per your requirement.

+ 

+In this section, you'll create a test user in the Azure portal called B.Simon.

+1. From the left pane in the Azure portal, select **Azure Active Directory**, select **Users**, and then select **All users**.

+1. Select **New user** at the top of the screen.

+1. In the **User** properties, follow these steps:

+ 1. In the **Name** field, enter `B.Simon`.

+ 1. In the **User name** field, enter the username@companydomain.extension. For example, `B.Simon@contoso.com`.

+ 1. Select the **Show password** check box, and then write down the value that's displayed in the **Password** box.

+ 1. Click **Create**.

+In this section, you'll enable B.Simon to use Azure single sign-on by granting access to Halosys.

+1. In the Azure portal, select **Enterprise Applications**, and then select **All applications**.

+1. In the applications list, select **Halosys**.

+1. In the app's overview page, find the **Manage** section and select **Users and groups**.

+1. Select **Add user**, then select **Users and groups** in the **Add Assignment** dialog.

+1. In the **Users and groups** dialog, select **B.Simon** from the Users list, then click the **Select** button at the bottom of the screen.

+1. If you're expecting any role value in the SAML assertion, in the **Select Role** dialog, select the appropriate role for the user from the list and then click the **Select** button at the bottom of the screen.

+1. In the **Add Assignment** dialog, click the **Assign** button.

+## Configure Halosys SSO

+To configure single sign-on on **Halosys** side, you need to send the downloaded **Federation Metadata XML** and appropriate copied URLs from Azure portal to [Halosys support team](https://www.sonata-software.com/form/contact). They set this setting to have the SAML SSO connection set properly on both sides.

+## Test SSO

+In this section, you test your Azure AD single sign-on configuration with following options.

+* Click on Test this application in Azure portal and you should be automatically signed in to the Halosys for which you set up the SSO.

+* You can use Microsoft My Apps. When you click the Halosys tile in the My Apps, you should be automatically signed in to the Halosys for which you set up the SSO. For more information about the My Apps, see [Introduction to the My Apps](../user-help/my-apps-portal-end-user-access.md).

+## Next steps

+Once you configure Halosys you can enforce session control, which protects exfiltration and infiltration of your organizationΓÇÖs sensitive data in real time. Session control extends from Conditional Access. [Learn how to enforce session control with Microsoft Cloud App Security](/cloud-app-security/proxy-deployment-aad).

+ > These values are not real. Update these values with the actual Identifier and Reply URL. Contact the [SAP Cloud Identity Services Client support team](https://cloudplatform.sap.com/capabilities/security/trustcenter.html) to get these values. If you don't understand Identifier value, read the SAP Cloud Identity Services documentation about [Tenant SAML 2.0 configuration](https://help.sap.com/docs/IDENTITY_AUTHENTICATION/6d6d63354d1242d185ab4830fc04feb1/e81a19b0067f4646982d7200a8dab3ca.html).

+* Authentication details (credentials used for provisioning, NOT the credentials used for SSO)

+ Title: 'Tutorial: Azure AD SSO integration with Yuhu Property Management Platform'

+# Tutorial: Azure AD SSO integration with Yuhu Property Management Platform

+* Along with Cloud Application Administrator, Application Administrator can also add or manage applications in Azure AD.

+For more information, see [Azure built-in roles](../roles/permissions-reference.md).

+* Yuhu Property Management Platform supports **SP** initiated SSO.

+## Add Yuhu Property Management Platform from the gallery

+1. Sign in to the Azure portal using either a work or school account, or a personal Microsoft account.

+## Configure and test Azure AD SSO for Yuhu Property Management Platform

+To configure and test Azure AD SSO with Yuhu Property Management Platform, perform the following steps:

+ 1. **[Create an Azure AD test user](#create-an-azure-ad-test-user)** - to test Azure AD single sign-on with B.Simon.

+ 1. **[Assign the Azure AD test user](#assign-the-azure-ad-test-user)** - to enable B.Simon to use Azure AD single sign-on.

+ 1. **[Create Yuhu Property Management Platform test user](#create-yuhu-property-management-platform-test-user)** - to have a counterpart of B.Simon in Yuhu Property Management Platform that is linked to the Azure AD representation of user.

+1. In the Azure portal, on the **Yuhu Property Management Platform** application integration page, find the **Manage** section and select **single sign-on**.

+1. On the **Set up single sign-on with SAML** page, click the pencil icon for **Basic SAML Configuration** to edit the settings.

+ 

+1. On the **Basic SAML Configuration** section, perform the following steps:

+ a. In the **Identifier (Entity ID)** text box, type a value using the following pattern:

+ b. In the **Sign on URL** text box, type a URL using the following pattern:

+ `https://<SUBDOMAIN>.yuhu.io/companies`

+ > These values are not real. Update these values with the actual Identifier and Sign on URL. Contact [Yuhu Property Management Platform Client support team](mailto:hello@yuhu.io) to get these values. You can also refer to the patterns shown in the **Basic SAML Configuration** section in the Azure portal.

+ 

+ 

+ 

+In this section, you test your Azure AD single sign-on configuration with following options.

+* Click on **Test this application** in Azure portal. This will redirect to Yuhu Property Management Platform Sign-on URL where you can initiate the login flow.

+* Go to Yuhu Property Management Platform Sign-on URL directly and initiate the login flow from there.

+* You can use Microsoft My Apps. When you click the Yuhu Property Management Platform tile in the My Apps, this will redirect to Yuhu Property Management Platform Sign-on URL. For more information about the My Apps, see [Introduction to the My Apps](../user-help/my-apps-portal-end-user-access.md).

+## Next steps

+Once you configure Yuhu Property Management Platform you can enforce session control, which protects exfiltration and infiltration of your organizationΓÇÖs sensitive data in real time. Session control extends from Conditional Access. [Learn how to enforce session control with Microsoft Cloud App Security](/cloud-app-security/proxy-deployment-aad).

+A container runtime is software that executes containers and manages container images on a node. The runtime helps abstract away sys-calls or operating system (OS) specific functionality to run containers on Linux or Windows. For Linux node pools, `containerd` is used for node pools using Kubernetes version 1.19 and greater. For Windows Server 2019 node pools, `containerd` is generally available and is used by default in Kubernetes 1.23 and greater. Docker is no longer supported as of September 2022. For more information about this deprecation, see the [AKS release notes][aks-release-notes].

+> Clusters with Linux node pools created on Kubernetes v1.19 or greater default to `containerd` for its container runtime. Clusters with node pools on a earlier supported Kubernetes versions receive Docker for their container runtime. Linux node pools will be updated to `containerd` once the node pool Kubernetes version is updated to a version that supports `containerd`. You can still use Docker node pools and clusters on versions below 1.23, but Docker is no longer supported as of September 2022.

+> Using `containerd` with Windows Server 2019 node pools is generally available, and is used by default in Kubernetes 1.23 and greater. For more details, see [Add a Windows Server node pool with `containerd`][/learn/aks-add-np-containerd].

+<!-- LINKS - external -->

+[aks-release-notes]: https://github.com/Azure/AKS/releases

+For managed disks, the default disk size and performance will be assigned according to the selected VM SKU and vCPU count. For more information, see [Default OS disk sizing](cluster-configuration.md#default-os-disk-sizing).

+> If you do not specify the *WindowsContainerRuntime=containerd* custom header, the node pool will still use `containerd` as the container runtime by default.

+> When running the upgrade command, the `--kubernetes-version` specified must be a higher version than the node pool's current version.

+#### Create an AKS cluster with system-assigned identities

+> [!NOTE]

+> AKS will create a system-assigned kubelet identity in the Node resource group if you do not [specify your own kubelet managed identity][Use a pre-created kubelet managed identity].

+You can create an AKS cluster using a system-assigned managed identity by running the following CLI command.

+> If you are not using the CLI but using your own VNet or route table which are outside of the worker node resource group, it's recommended to use [user-assigned control plane identity][Create an AKS cluster with user-assigned identities]. For system-assigned control plane identity, we cannot get the identity ID before creating cluster, which causes delay for role assignment to take effect.

+#### Create an AKS cluster with user-assigned identities

+##### Create user-assigned managed identities

+If you don't have a control plane managed identity, you can create by running the following [az identity create][az-identity-create] command:

+```azurecli-interactive

+az identity create --name myIdentity --resource-group myResourceGroup

+```

+The output should resemble the following:

+```output

+{

+ "clientId": "<client-id>",

+ "clientSecretUrl": "<clientSecretUrl>",

+ "id": "/subscriptions/<subscriptionid>/resourcegroups/myResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myIdentity",

+ "location": "westus2",

+ "name": "myIdentity",

+ "principalId": "<principal-id>",

+ "resourceGroup": "myResourceGroup",

+ "tags": {},

+ "tenantId": "<tenant-id>",

+ "type": "Microsoft.ManagedIdentity/userAssignedIdentities"

+}

+```

+If you don't have a kubelet managed identity, you can create one by running the following [az identity create][az-identity-create] command:

+```azurecli-interactive

+az identity create --name myKubeletIdentity --resource-group myResourceGroup

+```

+The output should resemble the following:

+```output

+{

+ "clientId": "<client-id>",

+ "clientSecretUrl": "<clientSecretUrl>",

+ "id": "/subscriptions/<subscriptionid>/resourcegroups/myResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myKubeletIdentity",

+ "location": "westus2",

+ "name": "myKubeletIdentity",

+ "principalId": "<principal-id>",

+ "resourceGroup": "myResourceGroup",

+ "tags": {},

+ "tenantId": "<tenant-id>",

+ "type": "Microsoft.ManagedIdentity/userAssignedIdentities"

+}

+```

+##### Create an AKS cluster with user-assigned identities

+Now you can use the following command to create your AKS cluster with your existing identities in the subnet. Provide the control plane identity resource ID via `assign-identity` and the kubelet managed identity via `assign-kubelet-identity`:

+```azurecli

+az aks create -g $RG -n $AKSNAME -l $LOC \

+ --node-count 3 \

+ --network-plugin $PLUGIN \

+ --outbound-type userDefinedRouting \

+ --vnet-subnet-id $SUBNETID \

+ --api-server-authorized-ip-ranges $FWPUBLIC_IP

+ --enable-managed-identity \

+ --assign-identity <identity-resource-id> \

+ --assign-kubelet-identity <kubelet-identity-resource-id>

+```

+> [!NOTE]

+> For creating and using your own VNet and route table where the resources are outside of the worker node resource group, the CLI will add the role assignment automatically. If you are using an ARM template or other client, you need to use the Principal ID of the cluster managed identity to perform a [role assignment.][add role to identity]

+[Create an AKS cluster with user-assigned identities]: limit-egress-traffic.md#create-an-aks-cluster-with-user-assigned-identities

+[Use a pre-created kubelet managed identity]: use-managed-identity.md#use-a-pre-created-kubelet-managed-identity

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

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

+> [!NOTE]

+> By default, disk size and performance for managed disks is assigned according to the selected VM SKU and vCPU count. Default OS disk sizing is only used on new clusters or node pools when Ephemeral OS disks are not supported and a default OS disk size is not specified. For more information, see [Default OS disk sizing](cluster-configuration.md#default-os-disk-sizing).

+The add-on deploys two components: an [nginx ingress controller][nginx], and [External-DNS][external-dns] controller.

+Since Web Application Routing uses OSM internally to secure intranet communication, we need to set up the `osm` CLI. This command-line tool contains everything needed to configure and manage Open Service Mesh. The latest binaries are available on the [OSM GitHub releases page][osm-release].

+### Import certificate to Azure Keyvault

+```bash

+openssl pkcs12 -export -in aks-ingress-tls.crt -inkey aks-ingress-tls.key -out aks-ingress-tls.pfx

+# skip Password prompt

+```

+az keyvault certificate import --vault-name <MY_KEYVAULT> -n <KEYVAULT-CERTIFICATE-NAME> -f aks-ingress-tls.pfx

+## Deploy Web Application Routing with the Azure CLI

+The Web Application Routing routing add-on can be enabled with the Azure CLI when deploying an AKS cluster. To do so, use the [az aks create][az-aks-create] command with the `--enable-addons` argument. However, since Web Application routing depends on the OSM addon to secure intranet communication and the Azure Keyvault Secret Provider to retrieve certificates, we must enable them at the same time.

+```azurecli

+az aks create --resource-group myResourceGroup --name myAKSCluster --enable-addons azure-keyvault-secrets-provider,open-service-mesh,web_application_routing --generate-ssh-keys

+```

+az aks enable-addons --resource-group myResourceGroup --name myAKSCluster --addons azure-keyvault-secrets-provider,open-service-mesh,web_application_routing

+az keyvault set-policy --name myapp-contoso --object-id <WEB_APP_ROUTING_MSI_OBJECT_ID> --secret-permissions get --certificate-permissions get

+ kubernetes.azure.com/tls-cert-keyvault-uri: https://<MY-KEYVAULT>.vault.azure.net/certificates/<KEYVAULT-CERTIFICATE-NAME>/<KEYVAULT-CERTIFICATE-REVISION>

+These annotations in the service manifest would direct Web Application Routing to create an ingress servicing `myapp.contoso.com` connected to the keyvault `<MY-KEYVAULT>` and will retrieve the `<KEYVAULT-CERTIFICATE-NAME>` with `<KEYVAULT-CERTIFICATE-REVISION>`. To obtain the certificate URI within your keyvault run:

+```azurecli

+az keyvault certificate show --vault-name <MY_KEYVAULT> --name <KEYVAULT-CERTIFICATE-NAME> -o jsonc | jq .id

+```

+Create a file named **samples-web-app-routing.yaml** and copy in the following YAML. On line 29-31, update `<MY_HOSTNAME>` with your DNS host name and `<MY_KEYVAULT_CERTIFICATE_URI>` with the ID returned from keyvault.

+ kubernetes.azure.com/tls-cert-keyvault-uri: <MY_KEYVAULT_CERTIFICATE_URI>

+kubectl get ingress -n hello-web-app-routing

+NAME CLASS HOSTS ADDRESS PORTS AGE

+aks-helloworld webapprouting.kubernetes.azure.com myapp.contoso.com 20.51.92.19 80, 443 4m

+## Configure external DNS to point to cluster

+Now that Web Application Routing is configured within our cluster and we have the external IP address, we can configure our DNS servers to reflect this. As soon as the DNS updates have propagated, open a web browser to *<MY_HOSTNAME>*, for example *myapp.contoso.com* and verify you see the demo application. The application may take a few minutes to appear.

+az aks disable-addons --addons azure-keyvault-secrets-provider,open-service-mesh,web_application_routing --name myAKSCluster --resource-group myResourceGroup

+| renewal-period | The length in seconds of the fixed window after which the quota resets. The start of each period is calculated relative to the start time of the subscription. When `renewal-period` is set to `0`, the period is set to infinite.| Yes | N/A |

+| renewal-period | The length in seconds of the fixed window after which the quota resets. The start of each period is calculated relative to `first-perdiod-start`. When `renewal-period` is set to `0`, the period is set to infinite. | Yes | N/A |

+description: Details of known issues and restrictions on OpenAPI, WSDL, and WADL formats support in Azure API Management.

+For GET, HEAD, and OPTIONS operations, API Management discards a request body parameter if defined in the OpenAPI specification.

+> [!IMPORTANT]

+> * This article has been updated with steps to configure an Azure AD B2C app using the Microsoft Authentication Library ([MSAL](../active-directory/develop/msal-overview.md)) v2.0.

+> * If you previously configured an Azure AD B2C app for user sign-in using the Azure AD Authentication Library (ADAL), we recommend that you [migrate to MSAL](#migrate-to-msal).

+1. In the **Add identity provider** page, select **Azure Active Directory B2C**. Once selected, you'll be able to enter other necessary information.

+ * In the **Client library** dropdown, select **MSAL**.

+ * To add other settings, see steps later in the article.

+ * In **Redirect URI**, select **Single-page application (SPA)** and paste the redirect URL you saved from a previous step.

+1. Republish the developer portal for the Azure AD B2C configuration to take effect. In the left menu, under **Developer portal**, select **Portal overview** > **Publish**.

+## Migrate to MSAL

+If you previously configured an Azure AD B2C app for user sign-in using the ADAL, you can use the portal to migrate the app to MSAL and update the identity provider in API Management.

+### Update Azure AD B2C app for MSAL compatibility

+For steps, see [Switch redirect URIs to the single-page application type](../active-directory/develop/migrate-spa-implicit-to-auth-code.md#switch-redirect-uris-to-spa-platform).

+### Update identity provider configuration

+1. In the left menu of your API Management instance, under **Developer portal**, select **Identities**.

+1. Select **Azure Active Directory B2C** from the list.

+1. In the **Client library** dropdown, select **MSAL**.

+1. Select **Update**.

+1. [Republish your developer portal](api-management-howto-developer-portal-customize.md#publish-from-the-azure-portal).

+* Learn more about [MSAL](../active-directory/develop/msal-overview.md) and [migrating to MSAL v2](../active-directory/develop/msal-migration.md)

+> [!IMPORTANT]

+> * This article has been updated with steps to configure an Azure AD app using the Microsoft Authentication Library ([MSAL](../active-directory/develop/msal-overview.md)).

+> * If you previously configured an Azure AD app for user sign-in using the Azure AD Authentication Library (ADAL), we recommend that you [migrate to MSAL](#migrate-to-msal).

+1. Under **Type**, select **Azure Active Directory** from the drop-down menu. Once selected, you'll be able to enter other necessary information.

+ * In the **Client library** dropdown, select **MSAL**.

+ * To add **Client ID** and **Client secret**, see steps later in the article.

+ * Set **Supported account types** to **Accounts in any organizational directory**.

+ * In **Redirect URI**, select **Single-page application (SPA)** and paste the redirect URL you saved from a previous step.

+1. Switch to the browser tab with the App registration.

+## Migrate to MSAL

+If you previously configured an Azure AD app for user sign-in using the ADAL, you can use the portal to migrate the app to MSAL and update the identity provider in API Management.

+### Update Azure AD app for MSAL compatibility

+For steps, see [Switch redirect URIs to the single-page application type](../active-directory/develop/migrate-spa-implicit-to-auth-code.md#switch-redirect-uris-to-spa-platform).

+### Update identity provider configuration

+1. In the left menu of your API Management instance, under **Developer portal**, select **Identities**.

+1. Select **Azure Active Directory** from the list.

+1. In the **Client library** dropdown, select **MSAL**.

+1. Select **Update**.

+1. [Republish your developer portal](api-management-howto-developer-portal-customize.md#publish-from-the-azure-portal).

+ $subId = "Your Azure subscription ID" # Example: "1fb8fadf-03a3-4253-8993-65391f432d3a"

+ $tenantId = "Your Azure AD Tenant or Organization ID" # Example: 0e054eb4-e5d0-43b8-ba1e-d7b5156f6da8"

+ $appObjectID = "Application Object ID that has been registered in AAD" # Example: "2215b54a-df84-453f-b4db-ae079c0d2619"

+- Learn more about [MSAL](../active-directory/develop/msal-overview.md) and [migrating to MSAL](../active-directory/develop/msal-migration.md).

+ > This should take you to the new fork. Your fork URL will look something like this: `https://github.com/YOUR_GITHUB_ACCOUNT_NAME/ruby-docs-hello-world`

+* Choose to rewrite the URL of all requests on a listener or only those requests which match one or more of the conditions you set. These conditions are based on the request properties (request header and server variables).

+ Title: What is Form Recognizer Studio?

+description: Learn how to set up and use Form Recognizer Studio to test features of Azure Form Recognizer on the web.

+recommendations: false

+<!-- markdownlint-disable MD033 -->

+# What is Form Recognizer Studio?

+>[!NOTE]

+> Form Recognizer Studio is currently in public preview. Some features may not be supported or have limited capabilities.

+Form Recognizer Studio is an online tool to visually explore, understand, train, and integrate features from the Form Recognizer service into your applications. The studio provides a platform for you to experiment with the different Form Recognizer models and sample their returned data in an interactive manner without the need to write code.

+The studio supports all Form Recognizer v3.0 models and v2.1 models with labeled data. Refer to the [REST API migration guide](v3-migration-guide.md) for detailed information about migrating from v2.1 to v3.0.

+## Get started using Form Recognizer Studio

+1. To use Form Recognizer Studio, you'll need the following assets:

+ * **Azure subscription** - [Create one for free](https://azure.microsoft.com/free/cognitive-services/).

+ * **Cognitive Services or Form Recognizer resource**. Once you have your Azure subscription, create a [single-service](https://portal.azure.com/#create/Microsoft.CognitiveServicesFormRecognizer) or [multi-service](https://portal.azure.com/#create/Microsoft.CognitiveServicesAllInOne) resource, in the Azure portal to get your key and endpoint. Use the free pricing tier (`F0`) to try the service, and upgrade later to a paid tier for production.

+ > [!TIP]

+ >

+ > * Create a Cognitive Services (multi-service) resource if you plan to access multiple cognitive services under a single endpoint and key.

+ > * Create a single-service resource for Form Recognizer access only. Please note that you'll need a single-service resource if you intend to use [Azure Active Directory authentication](../../active-directory/authentication/overview-authentication.md).

+1. Navigate to the [Form Recognizer Studio](https://formrecognizer.appliedai.azure.com/). If it's your first time logging in, a popup window will appear prompting you to configure your service resource. You have two options:

+ **a. Access by Resource**.

+ * Choose your existing subscription.

+ * Select an existing resource group within your subscription or create a new one.

+ * Select your existing Form Recognizer or Cognitive services resource.

+ :::image type="content" source="media/studio/welcome-to-studio.png" alt-text="Screenshot of the configure service resource window.":::

+ **b. Access by API endpoint and key**.

+ * Retrieve your endpoint and key from the Azure portal.

+ * Go to the overview page for your resource and select **Keys and Endpoint** from the left navigation bar.

+ * Enter the values in the appropriate fields.

+ :::image type="content" source="media/containers/keys-and-endpoint.png" alt-text="Screenshot: keys and endpoint location in the Azure portal.":::

+1. Once you've completed configuring your resource, you'll be able to try the different models offered by Form Recognizer Studio. From the front page, select any Form Recognizer model to try using with a no-code approach.

+ :::image type="content" source="media/studio/form-recognizer-studio-front.png" alt-text="Screenshot of Form Recognizer Studio front page.":::

+1. After you've tried Form Recognizer Studio, use the [**C#**](quickstarts/try-v3-csharp-sdk.md), [**Java**](quickstarts/try-v3-java-sdk.md), [**JavaScript**](quickstarts/try-v3-javascript-sdk.md) or [**Python**](quickstarts/try-v3-python-sdk.md) client libraries or the [**REST API**](quickstarts/try-v3-rest-api.md) to get started incorporating Form Recognizer models into your own applications.

+ To learn more about each model, *see* the concepts pages.

+ | Model type| Models |

+ |--|--|

+ |Document analysis models| <ul><li>[**Read model**](concept-read.md)</li><li>[**Layout model**](concept-layout.md)</li><li>[**General document model**](concept-general-document.md)</li></ul>.</br></br>

+ |**Prebuilt models**|<ul><li>[**W-2 form model**](concept-w2.md)</li><li>[**Invoice model**](concept-invoice.md)</li><li>[**Receipt model**](concept-receipt.md)</li><li>[**ID document model**](concept-id-document.md)</li><li>[**Business card model**](concept-business-card.md)</li></ul>

+ |Custom models|<ul><li>[**Custom model**](concept-custom.md)</li><ul><li>[**Template model**](concept-custom-template.md)</li><li>[**Neural model**](concept-custom-template.md)</li></ul><li>[**Composed model**](concept-model-overview.md)</li></ul>

+### Manage your resource

+ To view resource details such as name and pricing tier, select the **Settings** icon in the top-right corner of the Form Recognizer Studio home page and select the **Resource** tab. If you have access to other resources, you can switch resources as well.

+With Form Recognizer, you can quickly automate your data processing in applications and workflows, easily enhance data-driven strategies, and skillfully enrich document search capabilities.

+## Next steps

+* Visit [Form Recognizer Studio](https://formrecognizer.appliedai.azure.com/studio) to begin using the models presented by the service.

+* For more information on Form Recognizer capabilities, see [Azure Form Recognizer overview](overview.md).

+That's it! You've learned how to use the Form Recognizer sample tool for Form Recognizer prebuilt, layout and custom models. You've also learned to analyze a custom form with manually labeled data.

+>[!div class="nextstepaction"]

+> [**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio)

+In this quickstart, you used the Form Recognizer C# SDK to analyze various forms and documents in different ways. Next, explore the Form Recognizer Studio and reference documentation to learn about Form Recognizer API in more depth.

+>[!div class="nextstepaction"]

+> [**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio)

+> [Form Recognizer REST API v3.0 (preview)](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-06-30-preview/operations/AnalyzeDocument)

+>[!div class="nextstepaction"]

+> [**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio)

+> [Form Recognizer REST API v3.0 (preview)](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-06-30-preview/operations/AnalyzeDocument)

+In this quickstart, you used the Form Recognizer JavaScript SDK to analyze various forms in different ways. Next, explore the Form Recognizer Studio and reference documentation to learn moe about Form Recognizer v3.0 API.

+>[!div class="nextstepaction"]

+> [**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio)

+> [Form Recognizer REST API v3.0 (preview)](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-06-30-preview/operations/AnalyzeDocument)

+In this quickstart, you used the Form Recognizer Python SDK to analyze various forms in different ways. Next, explore the Form Recognizer Studio and reference documentation to learn more about Form Recognizer v3.0 API.

+>[!div class="nextstepaction"]

+> [**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio)

+> [Form Recognizer REST API v3.0 (preview)](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-06-30-preview/operations/AnalyzeDocument)

+In this quickstart, you used the Form Recognizer REST API preview (v3.0) to analyze forms in different ways. Next, further explore the Form Recognizer Studio and latest reference documentation to learn more about the Form Recognizer API.

+>[!div class="nextstepaction"]

+> [**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio)

+- Resource sync rule does not project Azure Arc Data controller. The Azure Arc Data controller must be deployed via ARM API.

+- Resource sync rule does not project Azure Arc enabled PostgreSQL

+- Resource sync rule does not project Azure Arc Active Directory connector

+- Resource sync rule does not project Azure Arc Instance Failover Groups

+[Create Azure Arc data controller in direct connectivity mode using CLI](create-data-controller-direct-cli.md)

+The Azure Fluid Relay doesn't support [experimental distributed data structures (DDSes)](https://fluidframework.com/docs/data-structures/overview). These include but are not limited to DDS packages with the `@fluid-experimental` package namespace.

+The following scripts are designed for and tested in [Azure Cloud Shell](../cloud-shell/overview.md). Choose **Try It** to open a Cloud Shell instance right in your browser.

+# [Azure PowerShell](#tab/azure-powershell)

+# [Azure CLI](#tab/azure-cli)

+# [Azure PowerShell](#tab/azure-powershell)

+# Enable network isolation for the Azure Monitor Agent

+By default, Azure Monitor agent will connect to a public endpoint to connect to your Azure Monitor environment. You can enable network isolation for your agents by creating [data collection endpoints](../essentials/data-collection-endpoint-overview.md) and adding them to your [Azure Monitor Private Link Scopes (AMPLS)](../logs/private-link-configure.md#connect-azure-monitor-resources).

+To use network isolation, you must create a data collection endpoint for each of your regions for agents to connect instead of the public endpoint. See [Create a data collection endpoint](../essentials/data-collection-endpoint-overview.md#create-data-collection-endpoint) for details on create a DCE. An agent can only connect to a DCE in the same region. If you have agents in multiple regions, then you must create a DCE in each one.

+## Create private link

+With [Azure Private Link](../../private-link/private-link-overview.md), you can securely link Azure platform as a service (PaaS) resources to your virtual network by using private endpoints. An Azure Monitor Private Link connects a private endpoint to a set of Azure Monitor resources, defining the boundaries of your monitoring network. That set is called an Azure Monitor Private Link Scope (AMPLS). See [Configure your Private Link](../logs/private-link-configure.md) for details on creating and configuring your AMPLS.

+## Add DCE to AMPLS

+Add the data collection endpoints to a new or existing [Azure Monitor Private Link Scopes (AMPLS)](../logs/private-link-configure.md#connect-azure-monitor-resources) resource. This adds the DCE endpoints to your private DNS zone (see [how to validate](../logs/private-link-configure.md#review-and-validate-your-private-link-setup)) and allows communication via private links. You can do this from either the AMPLS resource or from within an existing DCE resource's 'Network Isolation' tab.

+> Other Azure Monitor resources like the Log Analytics workspace(s) configured in your data collection rules that you wish to send data to, must be part of this same AMPLS resource.

+For your data collection endpoint(s), ensure **Accept access from public networks not connected through a Private Link Scope** option is set to **No** under the 'Network Isolation' tab of your endpoint resource in Azure portal, as shown below. This ensures that public internet access is disabled, and network communication only happen via private links.

+ Associate the data collection endpoints to the target resources by editing the data collection rule in Azure portal. From the **Resources** tab, select **Enable Data Collection Endpoints** and select a DCE for each virtual machine. See [Configure data collection for the Azure Monitor agent](../agents/data-collection-rule-azure-monitor-agent.md).

+You can associate virtual machines to multiple data collection rules. This allows you to define each data collection rule to address a particular requirement, and associate the data collection rules to virtual machines based on the specific data you want to collect from each machine.

+In the **Monitor** menu in the Azure portal, select **Data Collection Rules** from the **Settings** section. Click **Create** to create a new Data Collection Rule and assignment.

+[](media/data-collection-rule-azure-monitor-agent/data-collection-rules-updated.png#lightbox)

+Click **Create** to create a new rule and set of associations. Provide a **Rule name** and specify a **Subscription**, **Resource Group** and **Region**. This specifies where the DCR will be created. The virtual machines and their associations can be in any subscription or resource group in the tenant.

+Additionally, choose the appropriate **Platform Type** which specifies the type of resources this rule can apply to. Custom will allow for both Windows and Linux types. This allows for pre-curated creation experiences with options scoped to the selected platform type.

+[](media/data-collection-rule-azure-monitor-agent/data-collection-rule-basics-updated.png#lightbox)

+In the **Resources** tab, add the resources (virtual machines, virtual machine scale sets, Arc for servers) that should have the Data Collection Rule applied. The Azure Monitor Agent will be installed on resources that don't already have it installed, and will enable Azure Managed Identity as well.

+> [!IMPORTANT]

+> If you need network isolation using private links for collecting data using agents from your resources, then select **Enable Data Collection Endpoints** and select a DCE for each virtual machine. See [Enable network isolation for the Azure Monitor Agent](azure-monitor-agent-data-collection-endpoint.md) for details.

+On the **Collect and deliver** tab, click **Add data source** to add a data source and destination set. Select a **Data source type**, and the corresponding details to select will be displayed. For performance counters, you can select from a predefined set of objects and their sampling rate. For events, you can select from a set of logs or facilities and the severity level.

+[](media/data-collection-rule-azure-monitor-agent/data-collection-rule-data-source-basic-updated.png#lightbox)

+To specify other logs and performance counters from the [currently supported data sources](azure-monitor-agent-overview.md#data-sources-and-destinations) or to filter events using XPath queries, select **Custom**. You can then specify an [XPath ](https://www.w3schools.com/xml/xpath_syntax.asp) for any specific values to collect. See [Sample DCR](data-collection-rule-sample-agent.md) for an example.

+[](media/data-collection-rule-azure-monitor-agent/data-collection-rule-data-source-custom-updated.png#lightbox)

+On the **Destination** tab, add one or more destinations for the data source. You can select multiple destinations of same of different types, for instance multiple Log Analytics workspaces (i.e. "multi-homing"). Windows event and Syslog data sources can only send to Azure Monitor Logs. Performance counters can send to both Azure Monitor Metrics and Azure Monitor Logs.

+[](media/data-collection-rule-azure-monitor-agent/data-collection-rule-destination.png#lightbox)

+Click **Add Data Source** and then **Review + create** to review the details of the data collection rule and association with the set of VMs. Click **Create** to create it.

+> After the data collection rule and associations have been created, it might take up to 5 minutes for data to be sent to the destinations.

+## Create rule and association in Azure portal

+You can use the Azure portal to create a data collection rule and associate virtual machines in your subscription to that rule. The Azure Monitor agent will be automatically installed and a managed identity created for any virtual machines that don't already have it installed.

+> [!IMPORTANT]

+> Creating a data collection rule using the portal also enables System-Assigned managed identity on the target resources, in addition to existing User-Assigned Identities (if any). For existing applications unless they specify the User-Assigned identity in the request, the machine will default to using System-Assigned Identity instead. [Learn More](../../active-directory/managed-identities-azure-resources/managed-identities-faq.md#what-identity-will-imds-default-to-if-dont-specify-the-identity-in-the-request)

+> [!NOTE]

+> If you wish to send data to Log Analytics, you must create the data collection rule in the **same region** where your Log Analytics workspace resides. The rule can be associated to machines in other supported region(s).

+## Limit data collection with custom XPath queries

+Since you're charged for any data collected in a Log Analytics workspace, you should collect only the data that you require. Using basic configuration in the Azure portal, you only have limited ability to filter events to collect. For Application and System logs, this is all logs with a particular severity. For Security logs, this is all audit success or all audit failure logs.

+To specify additional filters, you must use Custom configuration and specify an XPath that filters out the events you don't. XPath entries are written in the form `LogName!XPathQuery`. For example, you may want to return only events from the Application event log with an event ID of 1035. The XPathQuery for these events would be `*[System[EventID=1035]]`. Since you want to retrieve the events from the Application event log, the XPath would be `Application!*[System[EventID=1035]]`

+### Extracting XPath queries from Windows Event Viewer

+One of the ways to create XPath queries is to use Windows Event Viewer to extract XPath queries as shown below.

+* In step 5 when pasting over the 'Select Path' parameter value, you must append the log type category followed by '!' and then paste the copied value.

+[](media/data-collection-rule-azure-monitor-agent/data-collection-rule-extract-xpath.png#lightbox)

+See [XPath 1.0 limitations](/windows/win32/wes/consuming-events#xpath-10-limitations) for a list of limitations in the XPath supported by Windows event log.

+> [!TIP]

+> You can use the PowerShell cmdlet `Get-WinEvent` with the `FilterXPath` parameter to test the validity of an XPathQuery locally on your machine first. The following script shows an example.

+>

+> ```powershell

+> $XPath = '*[System[EventID=1035]]'

+> Get-WinEvent -LogName 'Application' -FilterXPath $XPath

+> ```

+>

+> - **In the cmdlet above, the value for '-LogName' parameter is the initial part of the XPath query until the '!', while only the rest of the XPath query goes into the $XPath parameter.**

+> - If events are returned, the query is valid.

+> - If you receive the message *No events were found that match the specified selection criteria.*, the query may be valid, but there are no matching events on the local machine.

+> - If you receive the message *The specified query is invalid* , the query syntax is invalid.

+The following table shows examples for filtering events using a custom XPath.

+| Description | XPath |

+|:|:|

+| Collect only System events with Event ID = 4648 | `System!*[System[EventID=4648]]`

+| Collect Security Log events with Event ID = 4648 and a process name of consent.exe | `Security!*[System[(EventID=4648)]] and *[EventData[Data[@Name='ProcessName']='C:\Windows\System32\consent.exe']]` |

+| Collect all Critical, Error, Warning, and Information events from the System event log except for Event ID = 6 (Driver loaded) | `System!*[System[(Level=1 or Level=2 or Level=3) and (EventID != 6)]]` |

+| Collect all success and failure Security events except for Event ID 4624 (Successful logon) | `Security!*[System[(band(Keywords,13510798882111488)) and (EventID != 4624)]]` |

+## Create rule and association using REST API

+Follow the steps below to create a data collection rule and associations using the REST API.

+> [!NOTE]

+> If you wish to send data to Log Analytics, you must create the data collection rule in the **same region** where your Log Analytics workspace resides. The rule can be associated to machines in other supported region(s).

+ :::image type="content" source="../logs/media/tutorial-workspace-transformations-api/open-cloud-shell.png" lightbox="../logs/media/tutorial-workspace-transformations-api/open-cloud-shell.png" alt-text="Screenshot of opening Cloud Shell in the Azure portal.":::

+ :::image type="content" source="../logs/media/tutorial-workspace-transformations-api/deploy-custom-template.png" lightbox="../logs/media/tutorial-workspace-transformations-api/deploy-custom-template.png" alt-text="Screenshot that shows portal blade to deploy custom template.":::

+ :::image type="content" source="../logs/media/tutorial-workspace-transformations-api/build-custom-template.png" lightbox="../logs/media/tutorial-workspace-transformations-api/build-custom-template.png" alt-text="Screenshot that shows portal blade to build template in the editor.":::

+ :::image type="content" source="../logs/media/tutorial-workspace-transformations-api/edit-template.png" lightbox="../logs/media/tutorial-workspace-transformations-api/edit-template.png" alt-text="Screenshot that shows portal blade to edit Resource Manager template.":::

+ :::image type="content" source="../logs/media/tutorial-workspace-transformations-api/custom-deployment-values.png" lightbox="../logs/media/tutorial-workspace-transformations-api/custom-deployment-values.png" alt-text="Screenshot that shows portal blade to edit custom deployment values for data collection endpoint.":::

+ :::image type="content" source="../logs/media/tutorial-logs-ingestion-api/data-collection-endpoint-overview.png" lightbox="../logs/media/tutorial-logs-ingestion-api/data-collection-endpoint-overview.png" alt-text="Screenshot that shows portal blade with details of data collection endpoint uri.":::

+ :::image type="content" source="../logs/media/tutorial-logs-ingestion-api/data-collection-endpoint-json.png" lightbox="../logs/media/tutorial-logs-ingestion-api/data-collection-endpoint-json.png" alt-text="Screenshot that shows JSON view for data collection endpoint with the resource ID.":::

+ :::image type="content" source="../logs/media/tutorial-logs-ingestion-api/workspace-resource-id.png" lightbox="../logs/media/tutorial-logs-ingestion-api/workspace-resource-id.png" alt-text="Screenshot showing workspace resource ID.":::

+ :::image type="content" source="../logs/media/tutorial-workspace-transformations-api/deploy-custom-template.png" lightbox="../logs/media/tutorial-workspace-transformations-api/deploy-custom-template.png" alt-text="Screenshot that shows portal blade to deploy custom template.":::

+ :::image type="content" source="../logs/media/tutorial-workspace-transformations-api/build-custom-template.png" lightbox="../logs/media/tutorial-workspace-transformations-api/build-custom-template.png" alt-text="Screenshot that shows portal blade to build template in the editor.":::

+ - `transformKql`: Specifies a [transformation](../logs/../essentials//data-collection-transformations.md) to apply to the incoming data before it's sent to the workspace. Data collection rules for Azure Monitor agent don't yet support transformations, so this value should currently be `source`.

+ :::image type="content" source="../logs/media/tutorial-workspace-transformations-api/edit-template.png" lightbox="../logs/media/tutorial-workspace-transformations-api/edit-template.png" alt-text="Screenshot that shows portal blade to edit Resource Manager template.":::

+1. Open an elevated PowerShell window.

+## Frequently asked questions

+### Does Application Insights support ASP.NET Core 3.X?

+Yes. Update to [Application Insights SDK for ASP.NET Core](https://nuget.org/packages/Microsoft.ApplicationInsights.AspNetCore) version 2.8.0 or later. Earlier versions of the SDK don't support ASP.NET Core 3.X.

+Also, if you're [enabling server-side telemetry based on Visual Studio](#enable-application-insights-server-side-telemetry-visual-studio), update to the latest version of Visual Studio 2019 (16.3.0) to onboard. Earlier versions of Visual Studio don't support automatic onboarding for ASP.NET Core 3.X apps.

+### How can I track telemetry that's not automatically collected?

+Get an instance of `TelemetryClient` by using constructor injection, and call the required `TrackXXX()` method on it. We don't recommend creating new `TelemetryClient` or `TelemetryConfiguration` instances in an ASP.NET Core application. A singleton instance of `TelemetryClient` is already registered in the `DependencyInjection` container, which shares `TelemetryConfiguration` with rest of the telemetry. Creating a new `TelemetryClient` instance is recommended only if it needs a configuration that's separate from the rest of the telemetry.

+The following example shows how to track more telemetry from a controller.

+```csharp

+using Microsoft.ApplicationInsights;

+public class HomeController : Controller

+{

+ private TelemetryClient telemetry;

+ // Use constructor injection to get a TelemetryClient instance.

+ public HomeController(TelemetryClient telemetry)

+ {

+ this.telemetry = telemetry;

+ }

+ public IActionResult Index()

+ {

+ // Call the required TrackXXX method.

+ this.telemetry.TrackEvent("HomePageRequested");

+ return View();

+ }

+```

+For more information about custom data reporting in Application Insights, see [Application Insights custom metrics API reference](./api-custom-events-metrics.md). A similar approach can be used for sending custom metrics to Application Insights using the [GetMetric API](./get-metric.md).

+### How do I customize ILogger logs collection?

+By default, only `Warning` logs and more severe logs are automatically captured. To change this behavior, explicitly override the logging configuration for the provider `ApplicationInsights` as shown below.

+The following configuration allows ApplicationInsights to capture all `Information` logs and more severe logs.

+```json

+{

+ "Logging": {

+ "LogLevel": {

+ "Default": "Warning"

+ },

+ "ApplicationInsights": {

+ "LogLevel": {

+ "Default": "Information"

+ }

+ }

+ }

+}

+```

+It's important to note that the following example doesn't cause the ApplicationInsights provider to capture `Information` logs. It doesn't capture it because the SDK adds a default logging filter that instructs `ApplicationInsights` to capture only `Warning` logs and more severe logs. ApplicationInsights requires an explicit override.

+```json

+{

+ "Logging": {

+ "LogLevel": {

+ "Default": "Information"

+ }

+ }

+}

+```

+For more information, see [ILogger configuration](ilogger.md#logging-level).

+### Some Visual Studio templates used the UseApplicationInsights() extension method on IWebHostBuilder to enable Application Insights. Is this usage still valid?

+The extension method `UseApplicationInsights()` is still supported, but it's marked as obsolete in Application Insights SDK version 2.8.0 and later. It will be removed in the next major version of the SDK. To enable Application Insights telemetry, we recommend using `AddApplicationInsightsTelemetry()` because it provides overloads to control some configuration. Also, in ASP.NET Core 3.X apps, `services.AddApplicationInsightsTelemetry()` is the only way to enable Application Insights.

+### I'm deploying my ASP.NET Core application to Web Apps. Should I still enable the Application Insights extension from Web Apps?

+If the SDK is installed at build time as shown in this article, you don't need to enable the [Application Insights extension](./azure-web-apps.md) from the App Service portal. If the extension is installed, it will back off when it detects the SDK is already added. If you enable Application Insights from the extension, you don't have to install and update the SDK. But if you enable Application Insights by following instructions in this article, you have more flexibility because:

+ * Application Insights telemetry will continue to work in:

+ * All operating systems, including Windows, Linux, and Mac.

+ * All publish modes, including self-contained or framework dependent.

+ * All target frameworks, including the full .NET Framework.

+ * All hosting options, including Web Apps, VMs, Linux, containers, Azure Kubernetes Service, and non-Azure hosting.

+ * All .NET Core versions including preview versions.

+ * You can see telemetry locally when you're debugging from Visual Studio.

+ * You can track more custom telemetry by using the `TrackXXX()` API.

+ * You have full control over the configuration.

+### Can I enable Application Insights monitoring by using tools like Azure Monitor Application Insights Agent (formerly Status Monitor v2)?

+ Yes. In [Application Insights Agent 2.0.0-beta1](https://www.powershellgallery.com/packages/Az.ApplicationMonitor/2.0.0-beta1) and later, ASP.NET Core applications hosted in IIS are supported.

+### Are all features supported if I run my application in Linux?

+Yes. Feature support for the SDK is the same in all platforms, with the following exceptions:

+* The SDK collects [Event Counters](./eventcounters.md) on Linux because [Performance Counters](./performance-counters.md) are only supported in Windows. Most metrics are the same.

+* Although `ServerTelemetryChannel` is enabled by default, if the application is running in Linux or macOS, the channel doesn't automatically create a local storage folder to keep telemetry temporarily if there are network issues. Because of this limitation, telemetry is lost when there are temporary network or server issues. To work around this issue, configure a local folder for the channel:

+```csharp

+using Microsoft.ApplicationInsights.Channel;

+using Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel;

+ public void ConfigureServices(IServiceCollection services)

+ {

+ // The following will configure the channel to use the given folder to temporarily

+ // store telemetry items during network or Application Insights server issues.

+ // User should ensure that the given folder already exists

+ // and that the application has read/write permissions.

+ services.AddSingleton(typeof(ITelemetryChannel),

+ new ServerTelemetryChannel () {StorageFolder = "/tmp/myfolder"});

+ services.AddApplicationInsightsTelemetry();

+ }

+```

+This limitation isn't applicable from version [2.15.0](https://www.nuget.org/packages/Microsoft.ApplicationInsights.AspNetCore/2.15.0) and later.

+### Is this SDK supported for the new .NET Core 3.X Worker Service template applications?

+This SDK requires `HttpContext`; therefore, it doesn't work in any non-HTTP applications, including the .NET Core 3.X Worker Service applications. To enable Application Insights in such applications using the newly released Microsoft.ApplicationInsights.WorkerService SDK, see [Application Insights for Worker Service applications (non-HTTP applications)](worker-service.md).

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

+- Check out the [GitHub Repository](https://github.com/microsoft/ApplicationInsights-JS/tree/master/extensions/applicationinsights-clickanalytics-js) and [npm Package](https://www.npmjs.com/package/@microsoft/applicationinsights-clickanalytics-js) for the Click Analytics Auto Collection Plugin.

+- The table currently supports Basic Logs.

+- The cost savings for data ingestion over a month exceed the expected cost for any expected queries

+The bulk of data collection from virtual machines will be from Windows or Syslog events. While you can provide more filtering with the Azure Monitor agent, you still may be collecting records that provide little value. Use [transformations](essentials//data-collection-transformations.md) to implement more granular filtering and also to filter data from columns that provide little value. For example, you might have a Windows event that's valuable for alerting, but it includes columns with redundant or excessive data. You can create a transformation that allows the event to be collected but removes this excessive data.

+You can also collect duplicate data with a single virtual machine running both the Azure Monitor agent and Log Analytics agent, even if they're both sending data to the same workspace. While the agents can coexist, each works independently without any knowledge of the other. You should continue to use the Log Analytics agent until you [migrate to the Azure Monitor agent](./agents/azure-monitor-agent-migration.md) rather than using both together unless you can ensure that each is collecting unique data.

+Diagnostic settings do not allow granular filtering of resource logs. You may require certain logs in a particular category but not others. In this case, use [transformations](essentials/data-collection-transformations.md) on the workspace to filter logs that you don't require. You can also filter out the value of certain columns that you don't require to save additional cost.

+[Data collection rule transformations in Azure Monitor](essentials//data-collection-transformations.md) allow you to filter incoming data to reduce costs for data ingestion and retention. In addition to filtering records from the incoming data, you can filter out columns in the data, reducing its billable size as described in [Data size calculation](logs/cost-logs.md#data-size-calculation).

+| Log Analytics agent | Custom tables | Configure [custom logs](agents/data-sources-custom-logs.md) on the workspace to collect file based text logs. | Configure ingestion-time transformation in the workspace DCR to filter or transform incoming data. You must first migrate the custom table to the new logs ingestion API. |

+| Data Collector API | Custom tables | Use [Data Collector API](logs/data-collector-api.md) to send data to custom tables in the workspace using REST API. | Configure ingestion-time transformation in the workspace DCR to filter or transform incoming data. You must first migrate the custom table to the new logs ingestion API. |

+| Logs ingestion API | Custom tables<br>Azure tables | Use [Logs ingestion API](logs/logs-ingestion-api-overview.md) to send data to the workspace using REST API. | Configure ingestion-time transformation in the DCR for the custom log. |

+When data collection stops, you effectively have no monitoring of features and resources relying on that workspace. Rather than just relying on the daily cap alone, you can configure an alert rule to notify you when data collection reaches some level before the daily cap. This allows you to address any increases before data collection shuts down, or even to temporarily disable collection for less critical resources.

+In order to avoid unexpected bills, you should be proactively notified anytime you experience excessive usage. This allows you to address any potential anomalies before the end of your billing period.

+Container insights supports clusters running the Linux and Windows Server 2019 operating system. The container runtimes it supports are Moby and any CRI compatible runtime such as CRI-O and ContainerD. Docker is no longer supported as a container runtime as of September 2022. For more information about this deprecation, see the [AKS release notes][aks-release-notes].

+<!-- LINKS - external -->

+[aks-release-notes]: https://github.com/Azure/AKS/releases

+- You automatically get [platform metrics, activity logs and diagnostics logs](data-sources.md) from most of your Azure resources with no configuration.

+ Title: Azure Monitor data platform

+description: Overview of the Azure Monitor data platform and collection of observability data.

+

+Metrics, logs, and distributed traces are commonly referred to as the three pillars of observability. A monitoring tool must collect and analyze these three different kinds of data to provide sufficient observability of a monitored system. Observability can be achieved by correlating data from multiple pillars and aggregating data across the entire set of resources being monitored. Because Azure Monitor stores data from multiple sources together, the data can be correlated and analyzed by using a common set of tools. It also correlates data across multiple Azure subscriptions and tenants, in addition to hosting data for other services.

+Azure resources generate a significant amount of monitoring data. Azure Monitor consolidates this data along with monitoring data from other sources into either a Metrics or Logs platform. Each is optimized for particular monitoring scenarios, and each supports different features in Azure Monitor. Features such as data analysis, visualizations, or alerting require you to understand the differences so that you can implement your required scenario in the most efficient and cost effective manner. Insights in Azure Monitor such as [Application Insights](app/app-insights-overview.md) or [Container insights](containers/container-insights-overview.md) have analysis tools that allow you to focus on the particular monitoring scenario without having to understand the differences between the two types of data.

+| Benefits | Lightweight and capable of near-real time scenarios such as alerting. Ideal for fast detection of issues. | Analyzed with rich query language. Ideal for deep analysis and identifying root cause. |

+| Data | Numerical values only | Text or numeric data |

+| Structure | Standard set of properties including sample time, resource being monitored, a numeric value. Some metrics include multiple dimensions for further definition. | Unique set of properties depending on the log type. |

+| Collection | Collected at regular intervals. | May be collected sporadically as events trigger a record to be created. |

+| Analyze in Azure portal | Metrics Explorer | Log Analytics |

+| Data sources include | Platform metrics collected from Azure resources<br>Applications monitored by Application Insights<br>Azure Monitor agent<br>Custom defined by application or API | Application and resource logs<br>Azure Monitor agent<br>Application requests and exceptions<br>Logs ingestion API<br>Azure Sentinel<br>Microsoft Defender for Cloud |

+Different [sources of data for Azure Monitor](data-sources.md) will write to either a Log Analytics workspace (Logs) or the Azure Monitor metrics database (Metrics) or both. Some sources will write directly to these data stores, while others may write to another location such as Azure storage and require some configuration to populate logs or metrics.

+## Next steps

+- Read more about [Metrics in Azure Monitor](essentials/data-platform-metrics.md).

+- Read more about [Logs in Azure Monitor](logs/data-platform-logs.md).

+- Learn about the [monitoring data available](data-sources.md) for different resources in Azure.

+ Title: Sources of data in Azure Monitor

+description: Describes the data available to monitor the health and performance of your Azure resources and the applications running on them.

+# Sources of monitoring data for Azure Monitor

+Azure Monitor is based on a [common monitoring data platform](data-platform.md) that includes [Logs](logs/data-platform-logs.md) and [Metrics](essentials/data-platform-metrics.md). This platform allows data from multiple resources to be analyzed together using a common set of tools in Azure Monitor. Monitoring data may also be sent to other locations to support certain scenarios, and some resources may write to other locations before they can be collected into Logs or Metrics.

+This article describes common sources of monitoring data collected by Azure Monitor in addition to the monitoring data created by Azure resources. Links are provided to detailed information on configuration required to collect this data to different locations.

+Some of these data sources use the [new data ingestion pipeline](essentials/data-collection.md) in Azure Monitor. This article will be updated as other data sources transition to this new data collection method.

+## Application tiers

+Sources of monitoring data from Azure applications can be organized into tiers, the highest tiers being your application itself and the lower tiers being components of Azure platform. The method of accessing data from each tier varies. The application tiers are summarized in the table below, and the sources of monitoring data in each tier are presented in the following sections. See [Monitoring data locations in Azure](monitor-reference.md) for a description of each data location and how you can access its data.

+### Azure

+The following table briefly describes the application tiers that are specific to Azure. Following the link for further details on each in the sections below.

+| Tier | Description | Collection method |

+|:|:|:|

+| [Azure Tenant](#azure-tenant) | Data about the operation of tenant-level Azure services, such as Azure Active Directory. | View Azure Active Directory data in portal or configure collection to Azure Monitor using a tenant diagnostic setting. |

+| [Azure subscription](#azure-subscription) | Data related to the health and management of cross-resource services in your Azure subscription such as Resource Manager and Service Health. | View in portal or configure collection to Azure Monitor using a log profile. |

+| [Azure resources](#azure-resources) | Data about the operation and performance of each Azure resource. | Metrics collected automatically, view in Metrics Explorer.<br>Configure diagnostic settings to collect logs in Azure Monitor.<br>Monitoring solutions and Insights available for more detailed monitoring for specific resource types. |

+### Azure, other cloud, or on-premises

+The following table briefly describes the application tiers that may be in Azure, another cloud, or on-premises. Following the link for further details on each in the sections below.

+| Tier | Description | Collection method |

+|:|:|:|

+| [Operating system (guest)](#operating-system-guest) | Data about the operating system on compute resources. | Install Azure Monitor agent on virtual machines, scale sets and Arc-enabled servers to collect logs and metrics into Azure Monitor. |

+| [Application Code](#application-code) | Data about the performance and functionality of the actual application and code, including performance traces, application logs, and user telemetry. | Instrument your code to collect data into Application Insights. |

+| [Custom sources](#custom-sources) | Data from external services or other components or devices. | Collect log or metrics data into Azure Monitor from any REST client. |

+## Azure tenant

+Telemetry related to your Azure tenant is collected from tenant-wide services such as Azure Active Directory.

+### Azure Active Directory Audit Logs

+[Azure Active Directory reporting](../active-directory/reports-monitoring/overview-reports.md) contains the history of sign-in activity and audit trail of changes made within a particular tenant.

+| Destination | Description | Reference |

+|:|:|:|

+| Azure Monitor Logs | Configure Azure AD logs to be collected in Azure Monitor to analyze them with other monitoring data. | [Integrate Azure AD logs with Azure Monitor logs](../active-directory/reports-monitoring/howto-integrate-activity-logs-with-log-analytics.md) |

+| Azure Storage | Export Azure AD logs to Azure Storage for archiving. | [Tutorial: Archive Azure AD logs to an Azure storage account](../active-directory/reports-monitoring/quickstart-azure-monitor-route-logs-to-storage-account.md) |

+| Event Hubs | Stream Azure AD logs to other locations using Event Hubs. | [Tutorial: Stream Azure Active Directory logs to an Azure event hub](../active-directory/reports-monitoring/tutorial-azure-monitor-stream-logs-to-event-hub.md). |

+## Azure subscription

+Telemetry related to the health and operation of your Azure subscription.

+### Azure Activity log

+The [Azure Activity log](essentials/platform-logs-overview.md) includes service health records along with records on any configuration changes made to the resources in your Azure subscription. The Activity log is available to all Azure resources and represents their _external_ view.

+| Destination | Description | Reference |

+|:|:|:|

+| Activity log | The Activity log is collected into its own data store that you can view from the Azure Monitor menu or use to create Activity log alerts. | [Query the Activity log in the Azure portal](essentials/activity-log.md#view-the-activity-log) |

+| Azure Monitor Logs | Configure Azure Monitor Logs to collect the Activity log to analyze it with other monitoring data. | [Collect and analyze Azure activity logs in Log Analytics workspace in Azure Monitor](essentials/activity-log.md) |

+| Azure Storage | Export the Activity log to Azure Storage for archiving. | [Archive Activity log](essentials/resource-logs.md#send-to-azure-storage) |

+| Event Hubs | Stream the Activity log to other locations using Event Hubs | [Stream Activity log to Event Hubs](essentials/resource-logs.md#send-to-azure-event-hubs). |

+### Azure Service Health

+[Azure Service Health](../service-health/service-health-overview.md) provides information about the health of the Azure services in your subscription that your application and resources rely on.

+| Destination | Description | Reference |

+|:|:|:|

+| Activity log<br>Azure Monitor Logs | Service Health records are stored in the Azure Activity log, so you can view them in the Azure portal or perform any other activities you can perform with the Activity log. | [View service health notifications by using the Azure portal](../service-health/service-notifications.md) |

+## Azure resources

+Metrics and resource logs provide information about the _internal_ operation of Azure resources. These are available for most Azure services, and monitoring solutions and insights collect additional data for particular services.

+### Platform metrics

+Most Azure services will send [platform metrics](essentials/data-platform-metrics.md) that reflect their performance and operation directly to the metrics database. The specific [metrics will vary for each type of resource](essentials/metrics-supported.md).

+| Destination | Description | Reference |

+|:|:|:|

+| Azure Monitor Metrics | Platform metrics will write to the Azure Monitor metrics database with no configuration. Access platform metrics from Metrics Explorer. | [Getting started with Azure Metrics Explorer](essentials/metrics-getting-started.md)<br>[Supported metrics with Azure Monitor](essentials/metrics-supported.md) |

+| Azure Monitor Logs | Copy platform metrics to Logs for trending and other analysis using Log Analytics. | [Azure diagnostics direct to Log Analytics](essentials/resource-logs.md#send-to-log-analytics-workspace) |

+| Event Hubs | Stream metrics to other locations using Event Hubs. |[Stream Azure monitoring data to an event hub for consumption by an external tool](essentials/stream-monitoring-data-event-hubs.md) |

+### Resource logs

+[Resource logs](essentials/platform-logs-overview.md) provide insights into the _internal_ operation of an Azure resource. Resource logs are created automatically, but you must create a diagnostic setting to specify a destination for them to be collected for each resource.

+The configuration requirements and content of resource logs vary by resource type, and not all services yet create them. See [Supported services, schemas, and categories for Azure resource logs](essentials/resource-logs-schema.md) for details on each service and links to detailed configuration procedures. If the service isn't listed in this article, then that service doesn't currently create resource logs.

+| Destination | Description | Reference |

+|:|:|:|

+| Azure Monitor Logs | Send resource logs to Azure Monitor Logs for analysis with other collected log data. | [Collect Azure resource logs in Log Analytics workspace in Azure Monitor](essentials/resource-logs.md#send-to-azure-storage) |

+| Storage | Send resource logs to Azure Storage for archiving. | [Archive Azure resource logs](essentials/resource-logs.md#send-to-log-analytics-workspace) |

+| Event Hubs | Stream resource logs to other locations using Event Hubs. |[Stream Azure resource logs to an event hub](essentials/resource-logs.md#send-to-azure-event-hubs) |

+## Operating system (guest)

+Compute resources in Azure, in other clouds, and on-premises have a guest operating system to monitor. With the installation of an agent, you can gather telemetry from the guest into Azure Monitor to analyze it with the same monitoring tools as the Azure services themselves.

+### Azure Monitor agent

+[Install the Azure Monitor agent](agents/azure-monitor-agent-manage.md) for comprehensive monitoring and management of your Windows or Linux virtual machines, scale sets and Arc-enabled servers. The Azure Monitor agent replaces the Log Analytics agent and Azure diagnostic extension.

+| Destination | Description | Reference |

+|:|:|:|

+| Azure Monitor Logs | The Azure Monitor agent allows you to collect logs from data sources that you configure using [data collection rules](agents/data-collection-rule-azure-monitor-agent.md) or from monitoring solutions that provide additional insights into applications running on the machine. These can be sent to one or more Log Analytics workspaces. | [Data sources and destinations](agents/azure-monitor-agent-overview.md#data-sources-and-destinations) |

+| Azure Monitor Metrics (preview) | The Azure Monitor agent allows you to collect performance counters and send them to Azure Monitor metrics database | [Data sources and destinations](agents/azure-monitor-agent-overview.md#data-sources-and-destinations) |

+### Log Analytics agent

+[Install the Log Analytics agent](agents/log-analytics-agent.md) for comprehensive monitoring and management of your Windows or Linux virtual machines. The virtual machine can be running in Azure, another cloud, or on-premises. The Log Analytics agent is still supported but has been replaced by the Azure Monitor agent.

+| Destination | Description | Reference |

+|:|:|:|

+| Azure Monitor Logs | The Log Analytics agent connects to Azure Monitor either directly or through System Center Operations Manager and allows you to collect data from data sources that you configure or from monitoring solutions that provide additional insights into applications running on the virtual machine. | [Agent data sources in Azure Monitor](agents/agent-data-sources.md)<br>[Connect Operations Manager to Azure Monitor](agents/om-agents.md) |

+### Azure diagnostic extension

+Enabling the Azure diagnostics extension for Azure Virtual machines allows you to collect logs and metrics from the guest operating system of Azure compute resources including Azure Cloud Service (classic) Web and Worker Roles, Virtual Machines, virtual machine scale sets, and Service Fabric.

+| Destination | Description | Reference |

+|:|:|:|

+| Storage | Azure diagnostics extension always writes to an Azure Storage account. | [Install and configure Azure diagnostics extension (WAD)](agents/diagnostics-extension-windows-install.md)<br>[Use Linux Diagnostic Extension to monitor metrics and logs](../virtual-machines/extensions/diagnostics-linux.md) |

+| Azure Monitor Metrics (preview) | When you configure the Diagnostics Extension to collect performance counters, they are written to the Azure Monitor metrics database. | [Send Guest OS metrics to the Azure Monitor metric store using a Resource Manager template for a Windows virtual machine](essentials/collect-custom-metrics-guestos-resource-manager-vm.md) |

+| Event Hubs | Configure the Diagnostics Extension to stream the data to other locations using Event Hubs. | [Streaming Azure Diagnostics data by using Event Hubs](agents/diagnostics-extension-stream-event-hubs.md)<br>[Use Linux Diagnostic Extension to monitor metrics and logs](../virtual-machines/extensions/diagnostics-linux.md) |

+| Application Insights Logs | Collect logs and performance counters from the compute resource supporting your application to be analyzed with other application data. | [Send Cloud Service, Virtual Machine, or Service Fabric diagnostic data to Application Insights](agents/diagnostics-extension-to-application-insights.md) |

+### VM insights

+[VM insights](vm/vminsights-overview.md) provides a customized monitoring experience for virtual machines providing features beyond core Azure Monitor functionality. It requires a Dependency Agent on Windows and Linux virtual machines that integrates with the Log Analytics agent to collect discovered data about processes running on the virtual machine and external process dependencies.

+| Destination | Description | Reference |

+|:|:|:|

+| Azure Monitor Logs | Stores data about processes and dependencies on the agent. | [Using VM insights Map to understand application components](vm/vminsights-maps.md) |

+## Application Code

+Detailed application monitoring in Azure Monitor is done with [Application Insights](/azure/application-insights/) which collects data from applications running on a variety of platforms. The application can be running in Azure, another cloud, or on-premises.

+### Application data

+When you enable Application Insights for an application by installing an instrumentation package, it collects metrics and logs related to the performance and operation of the application. Application Insights stores the data it collects in the same Azure Monitor data platform used by other data sources. It includes extensive tools for analyzing this data, but you can also analyze it with data from other sources using tools such as Metrics Explorer and Log Analytics.

+| Destination | Description | Reference |

+|:|:|:|

+| Azure Monitor Logs | Operational data about your application including page views, application requests, exceptions, and traces. | [Analyze log data in Azure Monitor](logs/log-query-overview.md) |

+| | Dependency information between application components to support Application Map and telemetry correlation. | [Telemetry correlation in Application Insights](app/correlation.md) <br> [Application Map](app/app-map.md) |

+| | Results of availability tests that test the availability and responsiveness of your application from different locations on the public Internet. | [Monitor availability and responsiveness of any web site](app/monitor-web-app-availability.md) |

+| Azure Monitor Metrics | Application Insights collects metrics describing the performance and operation of the application in addition to custom metrics that you define in your application into the Azure Monitor metrics database. | [Log-based and pre-aggregated metrics in Application Insights](app/pre-aggregated-metrics-log-metrics.md)<br>[Application Insights API for custom events and metrics](app/api-custom-events-metrics.md) |

+| Azure Storage | Send application data to Azure Storage for archiving. | [Export telemetry from Application Insights](app/export-telemetry.md) |

+| | Details of availability tests are stored in Azure Storage. Use Application Insights in the Azure portal to download for local analysis. Results of availability tests are stored in Azure Monitor Logs. | [Monitor availability and responsiveness of any web site](app/monitor-web-app-availability.md) |

+| | Profiler trace data is stored in Azure Storage. Use Application Insights in the Azure portal to download for local analysis. | [Profile production applications in Azure with Application Insights](app/profiler-overview.md)

+| | Debug snapshot data that is captured for a subset of exceptions is stored in Azure Storage. Use Application Insights in the Azure portal to download for local analysis. | [How snapshots work](app/snapshot-debugger.md#how-snapshots-work) |

+## Insights

+[Insights](monitor-reference.md) collect data to provide additional insights into the operation of a particular service or application. They may address resources in different application tiers and even multiple tiers.

+### Container insights

+[Container insights](containers/container-insights-overview.md) provides a customized monitoring experience for [Azure Kubernetes Service (AKS)](../aks/index.yml). It collects additional data about these resources described in the following table.

+| Destination | Description | Reference |

+|:|:|:|

+| Azure Monitor Logs | Stores monitoring data for AKS including inventory, logs, and events. Metric data is also stored in Logs in order to leverage its analysis functionality in the portal. | [Understand AKS cluster performance with Container insights](containers/container-insights-analyze.md) |

+| Azure Monitor Metrics | Metric data is stored in the metric database to drive visualization and alerts. | [View container metrics in metrics explorer](containers/container-insights-analyze.md#view-container-metrics-in-metrics-explorer) |

+| Azure Kubernetes Service | Provides direct access to your Azure Kubernetes Service (AKS) container logs (stdout/stderror), events, and pod metrics in the portal. | [How to view Kubernetes logs, events, and pod metrics in real-time](containers/container-insights-livedata-overview.md) |

+### VM insights

+[VM insights](vm/vminsights-overview.md) provides a customized experience for monitoring virtual machines. A description of the data collected by VM insights is included in the [Operating System (guest)](#operating-system-guest) section above.

+## Custom sources

+In addition to the standard tiers of an application, you may need to monitor other resources that have telemetry that can't be collected with the other data sources. For these resources, write this data to either Metrics or Logs using an Azure Monitor API.

+| Destination | Method | Description | Reference |

+|:|:|:|:|

+| Azure Monitor Logs | Logs ingestion API | Collect log data from any REST client and store in Log Analytics workspace using a data collection rule. | [Logs ingestion API in Azure Monitor (preview)](logs/logs-ingestion-api-overview.md) |

+| | Data Collector API | Collect log data from any REST client and store in Log Analytics workspace. | [Send log data to Azure Monitor with the HTTP Data Collector API (preview)](logs/data-collector-api.md) |

+| Azure Monitor Metrics | Custom Metrics API | Collect metric data from any REST client and store in Azure Monitor metrics database. | [Send custom metrics for an Azure resource to the Azure Monitor metric store by using a REST API](essentials/metrics-store-custom-rest-api.md) |

+## Other services

+Other services in Azure write data to the Azure Monitor data platform. This allows you to analyze data collected by these services with data collected by Azure Monitor and leverage the same analysis and visualization tools.

+| Service | Destination | Description | Reference |

+|:|:|:|:|

+| [Microsoft Defender for Cloud](../security-center/index.yml) | Azure Monitor Logs | Microsoft Defender for Cloud stores the security data it collects in a Log Analytics workspace which allows it to be analyzed with other log data collected by Azure Monitor. | [Data collection in Microsoft Defender for Cloud](../security-center/security-center-enable-data-collection.md) |

+| [Microsoft Sentinel](../sentinel/index.yml) | Azure Monitor Logs | Microsoft Sentinel stores the data it collects from different data sources in a Log Analytics workspace which allows it to be analyzed with other log data collected by Azure Monitor. | [Connect data sources](../sentinel/quickstart-onboard.md) |

+## Next steps

+- Learn more about the [types of monitoring data collected by Azure Monitor](data-platform.md) and how to view and analyze this data.

+- List the [different locations where Azure resources store data](monitor-reference.md) and how you can access it.

+Data Collection Endpoints (DCEs) provide a connection for certain data sources of Azure Monitor. This article provides an overview of data collection endpoints including their contents and structure and how you can create and work with them.

+## Data sources that use DCEs

+The following data sources currently use DCEs:

+- [Azure Monitor agent when network isolation is required](../agents/azure-monitor-agent-data-collection-endpoint.md)

+- [Custom logs](../logs/logs-ingestion-api-overview.md)

+| Configuration access endpoint | The endpoint used to access the configuration service to fetch associated data collection rules (DCR) for Azure Monitor agent.<br>Example: `<unique-dce-identifier>.<regionname>.handler.control` |

+| Logs ingestion endpoint | The endpoint used to ingest logs to Log Analytics workspace(s).<br>Example: `<unique-dce-identifier>.<regionname>.ingest` |

+Data collection endpoints only support Log Analytics workspaces as a destination for collected data. [Custom Metrics (preview)](../essentials/metrics-custom-overview.md) collected and uploaded via the Azure Monitor Agent are not currently controlled by DCEs nor can they be configured over private links.

+## Create data collection endpoint

+> [!IMPORTANT]

+> If agents will connect to your DCE, it must be created in the same region. If you have agents in different regions, then you'll need multiple DCEs.

+# [Azure portal](#tab/portal)

+# [REST API](#tab/restapi)

+Create data collection endpoint(s) using the [DCE REST APIs](/cli/azure/monitor/data-collection/endpoint).

+Create associations between endpoints to your target machines or resources, using the [DCRA REST APIs](/rest/api/monitor/datacollectionruleassociations/create#examples).

+See [Sample data collection endpoint](data-collection-endpoint-sample.md) for a sample data collection endpoint.

+ Title: Sample data collection endpoint

+description: Sample data collection endpoint below is for virtual machines with Azure Monitor agent

+# Sample data collection endpoint

+The sample data collection endpoint (DCE) below is for virtual machines with Azure Monitor agent, with public network access disabled so that agent only uses private links to communicate and send data to Azure Monitor/Log Analytics.

+## Sample DCE

+```json

+{

+ "id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx/resourceGroups/myResourceGroup/providers/Microsoft.Insights/dataCollectionEndpoints/myCollectionEndpoint",

+ "name": "myCollectionEndpoint",

+ "type": "Microsoft.Insights/dataCollectionEndpoints",

+ "location": "eastus",

+ "tags": {

+ "tag1": "A",

+ "tag2": "B"

+ },

+ "properties": {

+ "configurationAccess": {

+ "endpoint": "https://mycollectionendpoint-abcd.eastus-1.control.monitor.azure.com"

+ },

+ "logsIngestion": {

+ "endpoint": "https://mycollectionendpoint-abcd.eastus-1.ingest.monitor.azure.com"

+ },

+ "networkAcls": {

+ "publicNetworkAccess": "Disabled"

+ }

+ },

+ "systemData": {

+ "createdBy": "user1",

+ "createdByType": "User",

+ "createdAt": "yyyy-mm-ddThh:mm:ss.sssssssZ",

+ "lastModifiedBy": "user2",

+ "lastModifiedByType": "User",

+ "lastModifiedAt": "yyyy-mm-ddThh:mm:ss.sssssssZ"

+ },

+ "etag": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

+}

+```

+## Next steps

+- [Read more about data collection endpoints](data-collection-endpoint-overview.md)

+Start by setting up a new custom log. Follow [Tutorial: Send custom logs to Azure Monitor Logs using the Azure portal (preview)]( ../logs/tutorial-logs-ingestion-portal.md). Note the resource ID of the DCR created.

+ :::image type="content" source="../logs/media/tutorial-workspace-transformations-api/open-cloud-shell.png" lightbox="../logs/media/tutorial-workspace-transformations-api/open-cloud-shell.png" alt-text="Screenshot of opening cloud shell":::

+Data Collection Rules (DCRs) define the [data collection process in Azure Monitor](../essentials/data-collection.md). DCRs specify what data should be collected, how to transform that data, and where to send that data. Some DCRs will be created and managed by Azure Monitor to collect a specific set of data to enable insights and visualizations. You may also create your own DCRs to define the set of data required for other scenarios.

+## View data collection rules

+To view your data collection rules in the Azure portal, select **Data Collection Rules** from the **Monitor** menu.

+> [!NOTE]

+> While this view shows all data collection rules in the specified subscriptions, clicking the **Create** button will create a data collection for Azure Monitor agent. Similarly, this page will only allow you to modify data collection rules for the Azure Monitor agent. See [Creating a data collection rule](#create-a-data-collection-rule) below for guidance on creating and updating data collection rules for other workflows.

+## Create a data collection rule

+The following resources describe different scenarios for creating data collection rules. In some cases, the data collection rule may be created for you, while in others you may need to create and edit it yourself.

+| Scenario | Resources | Description |

+|:|:|:|

+| Azure Monitor agent | [Configure data collection for the Azure Monitor agent](../agents/data-collection-rule-azure-monitor-agent.md) | Use the Azure portal to create a data collection rule that specifies events and performance counters to collect from a machine with the Azure Monitor agent and then apply that rule to one or more virtual machines. The Azure Monitor agent will be installed on any machines that don't currently have it. |

+| | [Use Azure Policy to install Azure Monitor agent and associate with DCR](../agents/azure-monitor-agent-manage.md#using-azure-policy) | Use Azure Policy to install the Azure Monitor agent and associate one or more data collection rules with any virtual machines or virtual machine scale sets as they're created in your subscription.

+| Custom logs | [Configure custom logs using the Azure portal](../logs/tutorial-logs-ingestion-portal.md)<br>[Configure custom logs using Resource Manager templates and REST API](../logs/tutorial-logs-ingestion-api.md) | Send custom data using a REST API. The API call connects to a DCE and specifies a DCR to use. The DCR specifies the target table and potentially includes a transformation that filters and modifies the data before it's stored in a Log Analytics workspace. |

+| Workspace transformation | [Configure ingestion-time transformations using the Azure portal](../logs/tutorial-workspace-transformations-portal.md)<br>[Configure ingestion-time transformations using Resource Manager templates and REST API](../logs/tutorial-workspace-transformations-api.md) | Create a transformation for any supported table in a Log Analytics workspace. The transformation is defined in a DCR that's then associated with the workspace and applied to any data sent to that table from a legacy workload that doesn't use a DCR. |

+## Work with data collection rules

+See the following resources for working with data collection rules outside of the Azure portal.

+| Method | Resources |

+|:|:|

+| API | Directly edit the data collection rule in any JSON editor and then [install using the REST API](/rest/api/monitor/datacollectionrules). |

+| CLI | Create DCR and associations with [Azure CLI](https://github.com/Azure/azure-cli-extensions/blob/master/src/monitor-control-service/README.md). |

+| PowerShell | Work with DCR and associations with the following Azure PowerShell cmdlets.<br>[Get-AzDataCollectionRule](/powershell/module/az.monitor/get-azdatacollectionrule)<br>[New-AzDataCollectionRule](/powershell/module/az.monitor/new-azdatacollectionrule)<br>[Set-AzDataCollectionRule](/powershell/module/az.monitor/set-azdatacollectionrule)<br>[Update-AzDataCollectionRule](/powershell/module/az.monitor/update-azdatacollectionrule)<br>[Remove-AzDataCollectionRule](/powershell/module/az.monitor/remove-azdatacollectionrule)<br>[Get-AzDataCollectionRuleAssociation](/powershell/module/az.monitor/get-azdatacollectionruleassociation)<br>[New-AzDataCollectionRuleAssociation](/powershell/module/az.monitor/new-azdatacollectionruleassociation)<br>[Remove-AzDataCollectionRuleAssociation](/powershell/module/az.monitor/remove-azdatacollectionruleassociation)

+Data collection rules are formatted in JSON. While you may not need to interact with them directly, there are scenarios where you may need to directly edit a data collection rule. See [Data collection rule structure](data-collection-rule-structure.md) for a description of this structure and the different elements used for different workflows.

+## Supported regions

+Data collection rules are available in all public regions where Log Analytics workspace are supported, as well as the Azure Government and China clouds. Air-gapped clouds are not yet supported.

+**Single region data residency** is a preview feature to enable storing customer data in a single region and is currently only available in the Southeast Asia Region (Singapore) of the Asia Pacific Geo and Brazil South (Sao Paulo State) Region of Brazil Geo. Single region residency is enabled by default in these regions.

+A rule gets created and stored in a particular region and is backed up to the [paired-region](../../availability-zones/cross-region-replication-azure.md#azure-cross-region-replication-pairings-for-all-geographies) within the same geography. The service is deployed to all three [availability zones](../../availability-zones/az-overview.md#availability-zones) within the region, making it a **zone-redundant service** which further increases availability.

+- [Get details on transformations in a data collection rule.](data-collection-transformations.md)

+[Data Collection Rules (DCRs)](data-collection-rule-overview.md) determine how to collect and process telemetry sent to Azure. Some data collection rules will be created and managed by Azure Monitor, while you may create others to customize data collection for your particular requirements. This article describes the structure of DCRs for creating and editing data collection rules in those cases where you need to work with them directly.

+A DCR for [custom logs](../logs/logs-ingestion-api-overview.md) contains the sections below. For a sample, see [Sample data collection rule - custom logs](../logs/data-collection-rule-sample-custom-logs.md).

+- `transformKql` which is the [transformation](/data-collection-transformations.md) applied to the data that was sent in the input shape described in the `streamDeclarations` section to the shape of the target table.

+ A DCR for [Azure Monitor agent](../agents/data-collection-rule-azure-monitor-agent.md) contains the sections below. For a sample, see [Sample data collection rule - agent](../agents/data-collection-rule-sample-agent.md).

+### dataSources

+### destinations

+### dataFlows

+ Title: KQL limitations in data collection transformations

+description: Structure of transformation in Azure Monitor including limitations of KQL allowed in a transformation.

+ms.reviwer: nikeist

+# Structure of transformation in Azure Monitor (preview)

+[Transformations in Azure Monitor](/data-collection-transformations.md) allow you to filter or modify incoming data before it's stored in a Log Analytics workspace. They are implemented as a Kusto Query Language (KQL) statement in a [data collection rule (DCR)](data-collection-rule-overview.md). This article provides details on how this query is structured and limitations on the KQL language allowed.

+## Transformation structure

+The KQL statement is applied individually to each entry in the data source. It must understand the format of the incoming data and create output in the structure of the target table. The input stream is represented by a virtual table named `source` with columns matching the input data stream definition. Following is a typical example of a transformation. This example includes the following functionality:

+- Filters the incoming data with a [where](/azure/data-explorer/kusto/query/whereoperator) statement

+- Adds a new column using the [extend](/azure/data-explorer/kusto/query/extendoperator) operator

+- Formats the output to match the columns of the target table using the [project](/azure/data-explorer/kusto/query/projectoperator) operator

+```kusto

+source

+| where severity == "Critical"

+| extend Properties = parse_json(properties)

+| project

+ TimeGenerated = todatetime(["time"]),

+ Category = category,

+ StatusDescription = StatusDescription,

+ EventName = name,

+ EventId = tostring(Properties.EventId)

+```

+## KQL limitations

+Since the transformation is applied to each record individually, it can't use any KQL operators that act on multiple records. Only operators that take a single row as input and return no more than one row are supported. For example, [summarize](/azure/data-explorer/kusto/query/summarizeoperator) isn't supported since it summarizes multiple records. See [Supported KQL features](#supported-kql-features) for a complete list of supported features.

+Transformations in a [data collection rule (DCR)](data-collection-rule-overview.md) allow you to filter or modify incoming data before it's stored in a Log Analytics workspace. This article describes how to build transformations in a DCR, including details and limitations of the Kusto Query Language (KQL) used for the transform statement.

+## Inline reference table

+The [datatable](/azure/data-explorer/kusto/query/datatableoperator?pivots=azuremonitor) operator isn't supported in the subset of KQL available to use in transformations. This operator would normally be used in KQL to define an inline query-time table. Use dynamic literals instead to work around this limitation.

+For example, the following statement isn't supported in a transformation:

+```kusto

+let galaxy = datatable (country:string,entity:string)['ES','Spain','US','United States'];

+source

+| join kind=inner (galaxy) on $left.Location == $right.country

+| extend Galaxy_CF = ['entity']

+```

+You can instead use the following statement, which is supported and performs the same functionality:

+```kusto

+let galaxyDictionary = parsejson('{"ES": "Spain","US": "United States"}');

+source

+| extend Galaxy_CF = galaxyDictionary[Location]

+```

+### has operator

+Transformations don't currently support [has](/azure/data-explorer/kusto/query/has-operator). Use [contains](/azure/data-explorer/kusto/query/contains-operator) which is supported and performs similar functionality.

+### Handling dynamic data

+Consider the following input with [dynamic data](/azure/data-explorer/kusto/query/scalar-data-types/dynamic):

+```json

+{

+ "TimeGenerated" : "2021-11-07T09:13:06.570354Z",

+ "Message": "Houston, we have a problem",

+ "AdditionalContext": {

+ "Level": 2,

+ "DeviceID": "apollo13"

+ }

+}

+```

+In order to access the properties in *AdditionalContext*, define it as dynamic-typed column in the input stream:

+```json

+"columns": [

+ {

+ "name": "TimeGenerated",

+ "type": "datetime"

+ },

+ {

+ "name": "Message",

+ "type": "string"

+ },

+ {

+ "name": "AdditionalContext",

+ "type": "dynamic"

+ }

+]

+```

+The content of *AdditionalContext* column can now be parsed and used in the KQL transformation:

+```kusto

+source

+| extend parsedAdditionalContext = parse_json(AdditionalContext)

+| extend Level = toint (parsedAdditionalContext.Level)

+| extend DeviceId = tostring(parsedAdditionalContext.DeviceID)

+```

+### Dynamic literals

+Use the [parse_json function](/azure/data-explorer/kusto/query/parsejsonfunction) to handle [dynamic literals](/azure/data-explorer/kusto/query/scalar-data-types/dynamic#dynamic-literals).

+For example, the following queries provide the same functionality:

+```kql

+print d=dynamic({"a":123, "b":"hello", "c":[1,2,3], "d":{}})

+```

+```kql

+print d=parse_json('{"a":123, "b":"hello", "c":[1,2,3], "d":{}}')

+```

+## Supported KQL features

+### Supported statements

+#### let statement

+The right-hand side of [let](/azure/data-explorer/kusto/query/letstatement) can be a scalar expression, a tabular expression or a user-defined function. Only user-defined functions with scalar arguments are supported.

+#### tabular expression statements

+The only supported data sources for the KQL statement are as follows:

+- **source**, which represents the source data. For example:

+```kql

+source

+| where ActivityId == "383112e4-a7a8-4b94-a701-4266dfc18e41"

+| project PreciseTimeStamp, Message

+```

+- [print](/azure/data-explorer/kusto/query/printoperator) operator, which always produces a single row. For example:

+

+```kusto

+print x = 2 + 2, y = 5 | extend z = exp2(x) + exp2(y)

+```

+### Tabular operators

+- [extend](/azure/data-explorer/kusto/query/extendoperator)

+- [project](/azure/data-explorer/kusto/query/projectoperator)

+- [print](/azure/data-explorer/kusto/query/printoperator)

+- [where](/azure/data-explorer/kusto/query/whereoperator)

+- [parse](/azure/data-explorer/kusto/query/parseoperator)

+- [project-away](/azure/data-explorer/kusto/query/projectawayoperator)

+- [project-rename](/azure/data-explorer/kusto/query/projectrenameoperator)

+- [columnifexists]() (use columnifexists instead of column_ifexists)

+### Scalar operators

+#### Numerical operators

+All [Numerical operators](/azure/data-explorer/kusto/query/numoperators) are supported.

+#### Datetime and Timespan arithmetic operators

+All [Datetime and Timespan arithmetic operators](/azure/data-explorer/kusto/query/datetime-timespan-arithmetic) are supported.

+#### String operators

+The following [String operators](/azure/data-explorer/kusto/query/datatypes-string-operators) are supported.

+- ==

+- !=

+- =~

+- !~

+- contains

+- !contains

+- contains_cs

+- !contains_cs

+- startswith

+- !startswith

+- startswith_cs

+- !startswith_cs

+- endswith

+- !endswith

+- endswith_cs

+- !endswith_cs

+- matches regex

+- in

+- !in

+#### Bitwise operators

+The following [Bitwise operators](/azure/data-explorer/kusto/query/binoperators) are supported.

+- binary_and()

+- binary_or()

+- binary_xor()

+- binary_not()

+- binary_shift_left()

+- binary_shift_right()

+### Scalar functions

+#### Bitwise functions

+- [binary_and](/azure/data-explorer/kusto/query/binary-andfunction)

+- [binary_or](/azure/data-explorer/kusto/query/binary-orfunction)

+- [binary_not](/azure/data-explorer/kusto/query/binary-notfunction)

+- [binary_shift_left](/azure/data-explorer/kusto/query/binary-shift-leftfunction)

+- [binary_shift_right](/azure/data-explorer/kusto/query/binary-shift-rightfunction)

+- [binary_xor](/azure/data-explorer/kusto/query/binary-xorfunction)

+#### Conversion functions

+- [tobool](/azure/data-explorer/kusto/query/toboolfunction)

+- [todatetime](/azure/data-explorer/kusto/query/todatetimefunction)

+- [todouble/toreal](/azure/data-explorer/kusto/query/todoublefunction)

+- [toguid](/azure/data-explorer/kusto/query/toguidfunction)

+- [toint](/azure/data-explorer/kusto/query/tointfunction)

+- [tolong](/azure/data-explorer/kusto/query/tolongfunction)

+- [tostring](/azure/data-explorer/kusto/query/tostringfunction)

+- [totimespan](/azure/data-explorer/kusto/query/totimespanfunction)

+#### DateTime and TimeSpan functions

+- [ago](/azure/data-explorer/kusto/query/agofunction)

+- [datetime_add](/azure/data-explorer/kusto/query/datetime-addfunction)

+- [datetime_diff](/azure/data-explorer/kusto/query/datetime-difffunction)

+- [datetime_part](/azure/data-explorer/kusto/query/datetime-partfunction)

+- [dayofmonth](/azure/data-explorer/kusto/query/dayofmonthfunction)

+- [dayofweek](/azure/data-explorer/kusto/query/dayofweekfunction)

+- [dayofyear](/azure/data-explorer/kusto/query/dayofyearfunction)

+- [endofday](/azure/data-explorer/kusto/query/endofdayfunction)

+- [endofmonth](/azure/data-explorer/kusto/query/endofmonthfunction)

+- [endofweek](/azure/data-explorer/kusto/query/endofweekfunction)

+- [endofyear](/azure/data-explorer/kusto/query/endofyearfunction)

+- [getmonth](/azure/data-explorer/kusto/query/getmonthfunction)

+- [getyear](/azure/data-explorer/kusto/query/getyearfunction)

+- [hourofday](/azure/data-explorer/kusto/query/hourofdayfunction)

+- [make_datetime](/azure/data-explorer/kusto/query/make-datetimefunction)

+- [make_timespan](/azure/data-explorer/kusto/query/make-timespanfunction)

+- [now](/azure/data-explorer/kusto/query/nowfunction)

+- [startofday](/azure/data-explorer/kusto/query/startofdayfunction)

+- [startofmonth](/azure/data-explorer/kusto/query/startofmonthfunction)

+- [startofweek](/azure/data-explorer/kusto/query/startofweekfunction)

+- [startofyear](/azure/data-explorer/kusto/query/startofyearfunction)

+- [todatetime](/azure/data-explorer/kusto/query/todatetimefunction)

+- [totimespan](/azure/data-explorer/kusto/query/totimespanfunction)

+- [weekofyear](/azure/data-explorer/kusto/query/weekofyearfunction)

+#### Dynamic and array functions

+- [array_concat](/azure/data-explorer/kusto/query/arrayconcatfunction)

+- [array_length](/azure/data-explorer/kusto/query/arraylengthfunction)

+- [pack_array](/azure/data-explorer/kusto/query/packarrayfunction)

+- [pack](/azure/data-explorer/kusto/query/packfunction)

+- [parse_json](/azure/data-explorer/kusto/query/parsejsonfunction)

+- [parse_xml](/azure/data-explorer/kusto/query/parse-xmlfunction)

+- [zip](/azure/data-explorer/kusto/query/zipfunction)

+#### Mathematical functions

+- [abs](/azure/data-explorer/kusto/query/abs-function)

+- [bin/floor](/azure/data-explorer/kusto/query/binfunction)

+- [ceiling](/azure/data-explorer/kusto/query/ceilingfunction)

+- [exp](/azure/data-explorer/kusto/query/exp-function)

+- [exp10](/azure/data-explorer/kusto/query/exp10-function)

+- [exp2](/azure/data-explorer/kusto/query/exp2-function)

+- [isfinite](/azure/data-explorer/kusto/query/isfinitefunction)

+- [isinf](/azure/data-explorer/kusto/query/isinffunction)

+- [isnan](/azure/data-explorer/kusto/query/isnanfunction)

+- [log](/azure/data-explorer/kusto/query/log-function)

+- [log10](/azure/data-explorer/kusto/query/log10-function)

+- [log2](/azure/data-explorer/kusto/query/log2-function)

+- [pow](/azure/data-explorer/kusto/query/powfunction)

+- [round](/azure/data-explorer/kusto/query/roundfunction)

+- [sign](/azure/data-explorer/kusto/query/signfunction)

+#### Conditional functions

+- [case](/azure/data-explorer/kusto/query/casefunction)

+- [iif](/azure/data-explorer/kusto/query/iiffunction)

+- [max_of](/azure/data-explorer/kusto/query/max-offunction)

+- [min_of](/azure/data-explorer/kusto/query/min-offunction)

+#### String functions

+- [base64_encodestring](/azure/data-explorer/kusto/query/base64_encode_tostringfunction) (use base64_encodestring instead of base64_encode_tostring)

+- [base64_decodestring](/azure/data-explorer/kusto/query/base64_decode_tostringfunction) (use base64_decodestring instead of base64_decode_tostring)

+- [countof](/azure/data-explorer/kusto/query/countoffunction)

+- [extract](/azure/data-explorer/kusto/query/extractfunction)

+- [extract_all](/azure/data-explorer/kusto/query/extractallfunction)

+- [indexof](/azure/data-explorer/kusto/query/indexoffunction)

+- [isempty](/azure/data-explorer/kusto/query/isemptyfunction)

+- [isnotempty](/azure/data-explorer/kusto/query/isnotemptyfunction)

+- [parse_json](/azure/data-explorer/kusto/query/parsejsonfunction)

+- [split](/azure/data-explorer/kusto/query/splitfunction)

+- [strcat](/azure/data-explorer/kusto/query/strcatfunction)

+- [strcat_delim](/azure/data-explorer/kusto/query/strcat-delimfunction)

+- [strlen](/azure/data-explorer/kusto/query/strlenfunction)

+- [substring](/azure/data-explorer/kusto/query/substringfunction)

+- [tolower](/azure/data-explorer/kusto/query/tolowerfunction)

+- [toupper](/azure/data-explorer/kusto/query/toupperfunction)

+- [hash_sha256](/azure/data-explorer/kusto/query/sha256hashfunction)

+#### Type functions

+- [gettype](/azure/data-explorer/kusto/query/gettypefunction)

+- [isnotnull](/azure/data-explorer/kusto/query/isnotnullfunction)

+- [isnull](/azure/data-explorer/kusto/query/isnullfunction)

+### Identifier quoting

+Use [Identifier quoting](/azure/data-explorer/kusto/query/schema-entities/entity-names?q=identifier#identifier-quoting) as required.

+## Next steps

+- [Create a data collection rule](../agents/data-collection-rule-azure-monitor-agent.md) and an association to it from a virtual machine using the Azure Monitor agent.

+ Title: Data collection transformations

+description: Use transformations in a data collection rule in Azure Monitor to filter and modify incoming data.

+ms.reviwer: nikeist

+# Data collection transformations in Azure Monitor (preview)

+Transformations in Azure Monitor allow you to filter or modify incoming data before it's sent to a Log Analytics workspace. This article provides a basic description of transformations and how they are implemented. It provides links to other content for actually creating a transformation.

+## When to use transformations

+Transformations are useful for a variety of scenarios, including those described below.

+### Reduce data costs

+Since you're charged ingestion cost for any data sent to a Log Analytics workspace, you want to filter out any data that you don't require to reduce your costs.

+- **Remove entire rows.** For example, you might have a diagnostic setting to collect resource logs from a particular resource but not require all of the log entries that it generates. Create a transformation that filters out records that match a certain criteria.

+- **Remove a column from each row.** For example, your data may include columns with data that's redundant or has minimal value. Create a transformation that filters out columns that aren't required.

+- **Parse important data from a column.** You may have a table with valuable data buried in a particular column. Use a transformation to parse the valuable data into a new column and remove the original.

+### Remove sensitive data

+You may have a data source that sends information you don't want stored for privacy or compliancy reasons.

+- **Filter sensitive information.** Filter out entire rows or just particular columns that contain sensitive information.

+

+- **Obfuscate sensitive information**. For example, you might replace digits with a common character in an IP address or telephone number.

+### Enrich data with additional or calculated information

+Use a transformation to add information to data that provides business context or simplifies querying the data later.

+- **Add a column with additional information.** For example, you might add a column identifying whether an IP address in another column is internal or external.

+- **Add business specific information.** For example, you might add a column indicating a company division based on location information in other columns.

+## Supported tables

+Transformations may be applied to the following tables in a Log Analytics workspace.

+- Any Azure table listed in [Tables that support time transformations in Azure Monitor Logs (preview)](../logs/tables-feature-support.md)

+- Any custom table

+## How transformations work

+Transformations are performed in Azure Monitor in the [data ingestion pipeline](../essentials/data-collection.md) after the data source delivers the data and before it's sent to the destination. The data source may perform its own filtering before sending data but then rely on the transformation for further manipulation for it's sent to the destination.

+Transformations are defined in a [data collection rule (DCR)](data-collection-rule-overview.md) and use a [Kusto Query Language (KQL) statement](data-collection-transformations-structure.md) that is applied individually to each entry in the incoming data. It must understand the format of the incoming data and create output in the structure expected by the destination.

+For example, a DCR that collects data from a virtual machine using Azure Monitor agent would specify particular data to collect from the client operating system. It could also include a transformation that would get applied to that data after it's sent to the data ingestion pipeline that further filters the data or adds a calculated column. This workflow is shown in the following diagram.

+Another example is data sent from a custom application using the [logs ingestion API](../logs/logs-ingestion-api-overview.md). In this case, the application sends the data to a [data collection endpoint](data-collection-endpoint-overview.md) and specifies a data collection rule in the REST API call. The DCR includes the transformation and the destination workspace and table.

+## Workspace transformation DCR

+The workspace transformation DCR is a special DCR that's applied directly to a Log Analytics workspace. It includes default transformations for one more [supported tables](../logs/tables-feature-support.md). These transformations are applied to any data sent to these tables unless that data came from another DCR.

+For example, if you create a transformation in the workspace transformation DCR for the `Event` table, it would be applied to events collected by virtual machines running the [Log Analytics agent](../agents/log-analytics-agent.md) since this agent doesn't use a DCR. The transformation would be ignored by any data sent from the [Azure Monitor agent](../agents/azure-monitor-agent-overview.md) though since it uses a DCR and would be expected to provide its own transformation.

+A common use of the workspace transformation DCR is collection of [resource logs](resource-logs.md) which are configured with a [diagnostic setting](diagnostic-settings.md). This is shown in the example below.

+## Creating a transformation

+There are multiple methods to create transformations depending on the data collection method. The following table lists guidance for different methods for creating transformations.

+| Type | Reference |

+|:|:|

+| Logs ingestion API with transformation | [Send data to Azure Monitor Logs using REST API (Azure portal)](../logs/tutorial-logs-ingestion-portal.md)<br>[Send data to Azure Monitor Logs using REST API (Resource Manager templates)](../logs/tutorial-logs-ingestion-api.md) |

+| Transformation in workspace DCR | [Add workspace transformation to Azure Monitor Logs using the Azure portal (preview)](../logs/tutorial-workspace-transformations-portal.md)<br>[Add workspace transformation to Azure Monitor Logs using resource manager templates (preview)](../logs/tutorial-workspace-transformations-api.md)

+## Next steps

+- [Create a data collection rule](../agents/data-collection-rule-azure-monitor-agent.md) and an association to it from a virtual machine using the Azure Monitor agent.

+ Title: Data collection in Azure Monitor

+description: Monitoring data collected by Azure Monitor is separated into metrics that are lightweight and capable of supporting near real-time scenarios and logs that are used for advanced analysis.

+# Data collection in Azure Monitor

+Azure Monitor has a [common data platform](../data-platform.md) that consolidates data from a variety of sources. Currently, different sources of data for Azure Monitor use different methods to deliver their data, and each typically require different types of configuration. Get a description of the most common data sources at [Sources of monitoring data for Azure Monitor](../data-sources.md).

+Azure Monitor is implementing a new [ETL](/azure/architecture/data-guide/relational-data/etl)-like data collection pipeline that improves on legacy data collection methods. This process uses a common data ingestion pipeline for all data sources and provides a standard method of configuration that's more manageable and scalable than current methods. Specific advantages of the new data collection include the following:

+- Common set of destinations for different data sources.

+- Ability to apply a transformation to filter or modify incoming data before it's stored.

+- Consistent method for configuration of different data sources.

+- Scalable configuration options supporting infrastructure as code and DevOps processes.

+When implementation is complete, all data collected by Azure Monitor will use the new data collection process and be managed by data collection rules. Currently, only certain data collection methods support the ingestion pipeline, and they may have limited configuration options. There's no difference between data collected with the new ingestion pipeline and data collected using other methods. The data is all stored together as [Logs](../logs/data-platform-logs.md) and [Metrics](data-platform-metrics.md), supporting Azure Monitor features such as log queries, alerts, and workbooks. The only difference is in the method of collection.

+## Data collection rules

+Azure Monitor data collection is configured using a [data collection rule (DCR)](data-collection-rule-overview.md). A DCR defines the details of a particular data collection scenario including what data should be collected, how to potentially transform that data, and where to send that data. A single DCR can be used with multiple monitored resources, giving you a consistent method to configure a variety of monitoring scenarios. In some cases, Azure Monitor will create and configure a DCR for you using options in the Azure portal. You may also directly edit DCRs to configure particular scenarios.

+See [Data collection rules in Azure Monitor](data-collection-rule-overview.md) for details on data collection rules including how to view and create them.

+## Transformations

+One of the most valuable features of the new data collection process is [data transformations](data-collection-transformations.md), which allow you to apply a KQL query to incoming data to modify it before sending it to its destination. You might filter out unwanted data or modify existing data to improve your query or reporting capabilities.

+See [Data collection transformations in Azure Monitor (preview)](data-collection-transformations.md) For complete details on transformations including how to write transformation queries.

+## Data collection scenarios

+The following sections describe the data collection scenarios that are currently supported using DCR and the new data ingestion pipeline.

+### Azure Monitor agent

+The diagram below shows data collection for the [Azure Monitor agent](../agents/azure-monitor-agent-overview.md) running on a virtual machine. In this scenario, the DCR specifies events and performance data to collect from the agent machine, a transformation to filter and modify the data after its collected, and a Log Analytics workspace to send the transformed data. To implement this scenario, you create an association between the DCR and the agent. One agent can be associated with multiple DCRs, and one DCR can be associated with multiple agents.

+See [Collect data from virtual machines with the Azure Monitor agent](../agents/data-collection-rule-azure-monitor-agent.md) for details on creating a DCR for the Azure Monitor agent.

+### Log ingestion API

+The diagram below shows data collection for the [Logs ingestion API](../logs/logs-ingestion-api-overview.md), which allows you to send data to a Log Analytics workspace from any REST client. In this scenario, the API call connects to a [data collection endpoint (DCE)](data-collection-endpoint-overview.md) and specifies a DCR to accept its incoming data. The DCR understands the structure of the incoming data, includes a transformation that ensures that the data is in the format of the target table, and specifies a workspace and table to send the transformed data.

+See [Logs ingestion API in Azure Monitor (Preview)](../logs/logs-ingestion-api-overview.md) for details on the Logs ingestion API.

+### Workspace transformation DCR

+The diagram below shows data collection for [resource logs](resource-logs.md) using a [workspace transformation DCR](data-collection-transformations.md#workspace-transformation-dcr). This is a special DCR that's associated with a workspace and provides a default transformation for [supported tables](../logs/tables-feature-support.md). This transformation is applied to any data sent to the table that doesn't use another DCR. The example here shows resource logs using a diagnostic setting, but this same transformation could be applied to other data collection methods such as Log Analytics agent or Container insights.

+See [Workspace transformation DCR](data-collection-transformations.md#workspace-transformation-dcr) for details about workspace transformation DCRs and links to walkthroughs for creating them.

+## Next steps

+- Read more about [data collection rules](data-collection-rule-overview.md).

+- Read more about [transformations](data-collection-transformations.md).

+- Learn about the [monitoring data available](../data-sources.md) for various resources in Azure.

+[Sources of monitoring data for Azure Monitor](../data-sources.md) describes the data tiers for Azure applications and the kinds of data available for each. The following table lists each of these tiers and a description of how that data can be streamed to an event hub. Follow the links provided for further detail.

+| [Azure tenant](../data-sources.md#azure-tenant) | Azure Active Directory audit logs | Configure a tenant diagnostic setting on your Azure AD tenant. See [Tutorial: Stream Azure Active Directory logs to an Azure event hub](../../active-directory/reports-monitoring/tutorial-azure-monitor-stream-logs-to-event-hub.md) for details. |

+| [Azure subscription](../data-sources.md#azure-subscription) | Azure Activity Log | Create a log profile to export Activity Log events to Event Hubs. See [Stream Azure platform logs to Azure Event Hubs](../essentials/resource-logs.md#send-to-azure-event-hubs) for details. |

+| [Azure resources](../data-sources.md#azure-resources) | Platform metrics<br> Resource logs |Both types of data are sent to an event hub using a resource diagnostic setting. See [Stream Azure resource logs to an event hub](../essentials/resource-logs.md#send-to-azure-event-hubs) for details. |

+| [Operating system (guest)](../data-sources.md#operating-system-guest) | Azure virtual machines | Install the [Azure Diagnostics Extension](../agents/diagnostics-extension-overview.md) on Windows and Linux virtual machines in Azure. See [Streaming Azure Diagnostics data in the hot path by using Event Hubs](../agents/diagnostics-extension-stream-event-hubs.md) for details on Windows VMs and [Use Linux Diagnostic Extension to monitor metrics and logs](../../virtual-machines/extensions/diagnostics-linux.md#protected-settings) for details on Linux VMs. |

+| [Application code](../data-sources.md#application-code) | Application Insights | Use diagnostic settings to stream to event hubs. This is only available with workspace-based Application Insights resources. For help with setting up workspace-based Application Insights resources, see [Workspace-based Application Insights resources](../app/create-workspace-resource.md#workspace-based-application-insights-resources) and [Migrate to workspace-based Application Insights resources](../app/convert-classic-resource.md#migrate-to-workspace-based-application-insights-resources).|

+| IBM QRadar | No | The Microsoft Azure DSM and Microsoft Azure Event Hubs Protocol are available for download from [the IBM support website](https://www.ibm.com/support). |

+| SumoLogic | No | Instructions for setting up SumoLogic to consume data from an event hub are available at [Collect Logs for the Azure Audit App from Event Hubs](https://help.sumologic.com/Send-Data/Applications-and-Other-Data-Sources/Azure-Audit/02Collect-Logs-for-Azure-Audit-from-Event-Hub). |

+| ArcSight | No | The ArcSight Azure Event Hubs smart connector is available as part of [the ArcSight smart connector collection](https://community.microfocus.com/cyberres/arcsight/f/arcsight-product-announcements/163662/announcing-general-availability-of-arcsight-smart-connectors-7-10-0-8114-0). |

+- See [Data collection transformations in Azure Monitor (preview)](../essentials/data-collection-transformations.md) for details on using transformations to reduce the amount of data you collected in a Log Analytics workspace by filtering unwanted records and columns.

+You can delete [Custom Log](logs-ingestion-api-overview.md), [Search Results](search-jobs.md) and [Restored Logs](restore.md) tables.

+- All tables created with the [Data Collection Rule (DCR)-based logs ingestion API.](logs-ingestion-api-overview.md)

+Data volume is measured as the size of the data that will be stored in GB (10^9 bytes). The data size of a single record is calculated from a string representation of the columns that are stored in the Log Analytics workspace for that record, regardless of whether the data is sent from an agent or added during the ingestion process. This includes any custom columns added by the [logs ingestion API](logs-ingestion-api-overview.md), [transformations](../essentials/data-collection-transformations.md), or [custom fields](custom-fields.md) that are added as data is collected and then stored in the workspace.

+For situations in which older or archived logs need to be intensively queried with the full analytic query capabilities, the [data restore](restore.md) feature is a powerful tool. The restore operation makes a specific time range of data in a table available in the hot cache for high-performance queries. You can later dismiss the data when you're done. Log data restore is billed by the amount of data restored, and by the time the restore is kept active. The minimal values billed for any data restore are 2 TB and 12 hours. Data restored of more than 2 TB and/or more than 12 hours in duration are billed on a pro-rated basis.

+When Microsoft Sentinel is enabled in a Log Analytics workspace, all data collected in that workspace is subject to Sentinel charges in addition to Log Analytics charges. For this reason, you will often separate your security and operational data in different workspaces so that you don't incur [Sentinel charges](../../sentinel/billing.md) for operational data. For some particular situations though, combining this data can actually result in a cost savings. This is typically when you aren't collecting enough security and operational data to each reach a commitment tier on their own, but the combined data is enough to reach a commitment tier. See **Combining your SOC and non-SOC data** in [Design your Microsoft Sentinel workspace architecture](../../sentinel/design-your-workspace-architecture.md#decision-tree) for details and a sample cost calculation.

+Subscriptions that contained a Log Analytics workspace or Application Insights resource on April 2, 2018, or are linked to an Enterprise Agreement that started before February 1, 2019 and is still active, will continue to have access to use the following legacy pricing tiers:

+ Title: Migrate from Data Collector API and custom fields-enabled tables to DCR-based custom log collection

+description: Steps that you must perform when migrating from Data Collector API and custom fields-enabled tables to DCR-based custom log collection.

+# Migrate from Data Collector API and custom fields-enabled tables to DCR-based custom log collection

+This article describes how to migrate from [Data Collector API](data-collector-api.md) or [custom fields](custom-fields.md) in Azure Monitor to [DCR-based custom log collection](../essentials/data-collection-rule-overview.md). It includes configuration required for custom tables created in your Log Analytics workspace so that they can be used by [Logs ingestion API](logs-ingestion-api-overview.md) and [workspace transformations](../essentials/data-collection-transformations.md#workspace-transformation-dcr).

+> You do not need to follow this article if you are configuring your DCR-based custom logs [using the Azure Portal](tutorial-workspace-transformations-portal.md) since the configuration will be performed for you. This article only applies if you're configuring using Resource Manager templates APIs.

+To use a table with the [Logs ingestion API](logs-ingestion-api-overview.md) or with a [workspace transformation](../essentials/data-collection-transformations.md#workspace-transformation-dcr), it must be configured to support new features. When you complete the process described in this article, the following actions are taken:

+- The table is reconfigured to enable all DCR-based custom logs features. This includes DCR and DCE support and management with the new **Tables** control plane.

+- You're going to send data to the table using the [Logs ingestion API](logs-ingestion-api-overview.md) or configure a transformation for the table in the [workspace transformation DCR](../essentials/data-collection-transformations.md#workspace-transformation-dcr), preserving both schema and historical data in that table.

+- The table was either created using the Data Collector API, or has custom fields defined in it.

+- You want to migrate using the APIs instead of the Azure portal as described in [Send custom logs to Azure Monitor Logs using the Azure portal (preview)](tutorial-logs-ingestion-portal.md) or [Add transformation in workspace data collection rule using the Azure portal (preview)](tutorial-workspace-transformations-portal.md).

+If all of these conditions aren't true, then you can use DCR-based log collection without following the procedure described here.

+If the table that you're targeting with DCR-based log collection fits the criteria above, then you must perform the following steps:

+1. Configure your data collection rule (DCR) following procedures at [Send custom logs to Azure Monitor Logs using Resource Manager templates (preview)](tutorial-logs-ingestion-api.md) or [Add transformation in workspace data collection rule to Azure Monitor using resource manager templates (preview)](tutorial-workspace-transformations-api.md).

+1. If using the Logs ingestion API, also [configure the data collection endpoint (DCE)](tutorial-logs-ingestion-api.md#create-data-collection-endpoint) and the agent or component that will be sending data to the API.

+1. Discontinue use of the Data Collector API and start using the new Logs ingestion API.

+- [Walk through a tutorial sending custom logs using the Azure portal.](tutorial-logs-ingestion-portal.md)

+- [Walk through a tutorial sending custom logs using Resource Manager templates and REST API.](tutorial-logs-ingestion-api.md)

+The sample [data collection rule](../essentials/data-collection-rule-overview.md) below is for use with [custom logs](../logs/logs-ingestion-api-overview.md). It has the following details:

+- Applies a [transformation](../essentials//data-collection-transformations.md) to the incoming data.

+- [Walk through a tutorial on configuring custom logs using resource manager templates.](tutorial-logs-ingestion-api.md)

+- [Get an overview on custom logs](logs-ingestion-api-overview.md).

+- [Configure data sources on the workspace](../data-sources.md) to collect more events and performance data.

+- Learn about the [monitoring data available](../data-sources.md) for various resources in Azure.

+## Workspace transformation DCR

+[Data collection rules (DCRs)](../essentials/data-collection-rule-overview.md) that define data coming into Azure Monitor can include transformations that allow you to filter and transform data before it's ingested into the workspace. Since all data sources don't yet support DCRs, each workspace can have a [workspace transformation DCR](../essentials/data-collection-transformations.md#workspace-transformation-dcr).

+[Transformations](../essentials/data-collection-transformations.md) in the workspace transformation DCR are defined for each table in a workspace and apply to all data sent to that table, even if sent from multiple sources. These transformations only apply to workflows that don't already use a DCR. For example, [Azure Monitor agent](../agents/azure-monitor-agent-overview.md) uses a DCR to define data collected from virtual machines. This data won't be subject to any ingestion-time transformations defined in the workspace.

+* Integration with Azure services and other tools ΓÇô export to Event Hubs as data arrives and is processed in Azure Monitor.

+Once you've configured data export rules in Log Analytics workspace, new data for tables in rules is exported from Azure Monitor pipeline to your Storage Account or Event Hubs as it arrives.

+- Configure Diagnostic Settings in Azure resources. Logs are sent to destination directly and has lower latency compared to data export in Log Analytics.

+- Legacy custom log using the [HTTP Data Collector API](./data-collector-api.md) wonΓÇÖt be supported in export, while data for [DCR based custom logs](./logs-ingestion-api-overview.md) can be exported.

+Blobs are stored in 5-minute folders in path structure: *WorkspaceResourceId=/subscriptions/subscription-id/resourcegroups/\<resource-group\>/providers/microsoft.operationalinsights/workspaces/\<workspace\>/y=\<four-digit numeric year\>/m=\<two-digit numeric month\>/d=\<two-digit numeric day\>/h=\<two-digit 24-hour clock hour\>/m=\<two-digit 60-minute clock minute\>/PT05M.json*. Appends to blobs are limited to 50-K writes. More blobs will be added in folder as: PT05M_#.json*, where # is incremental blob count.

+Data is sent to your Event Hubs as it reaches Azure Monitor and exported to destinations located in workspace region. You can create multiple export rules to the same Event Hubs namespace by providing different `event hub name` in rule. When `event hub name` isn't provided, default Event Hubs is created for tables that you export with name: *am-* followed by the name of the table. For example, the table *SecurityEvent* would be sent to an Event Hubs named: *am-SecurityEvent*. The [number of supported Event Hubs in 'Basic' and 'Standard' namespaces tiers is 10](../../event-hubs/event-hubs-quotas.md#common-limits-for-all-tiers). When exporting more than 10 tables to these tiers, either split the tables between several export rules, to different Event Hubs namespaces, or provide an Event Hubs name to export all tables to it.

+ | namespaces-name | Event Hubs standard metrics | Incoming bytes | Sum | 80% of max ingress per alert evaluation period. For example, limit is 1 MB/s per unit ("TU" or "PU") and five units used. Threshold is 1200 MB per 5-minutes evaluation period |

+ | namespaces-name | Event Hubs standard metrics | Incoming requests | Count | 80% of max events per alert evaluation period. For example, limit is 1000/s per unit ("TU" or ""PU") and five units used. Threshold is 1200000 per 5-minutes evaluation period |

+ | namespaces-name | Event Hubs standard metrics | Quota Exceeded Errors | Count | Between 1% of request. For example, requests per 5-minute is 600000. Threshold is 6000 per 5-minute evaluation period |

+> - Export to Event Hubs - if Event Hubs name isn't provided, a separate Event Hubs is created for each table. The [number of supported Event Hubs in 'Basic' and 'Standard' namespaces tiers is 10](../../event-hubs/event-hubs-quotas.md#common-limits-for-all-tiers). When exporting more than 10 tables to these tiers, either split the tables between several export rules to different Event Hubs namespaces, or provide an Event Hubs name in the rule to export all tables to it.

+Use the following command to create a data export rule to a specific Event Hubs using PowerShell. All tables are exported to the provided Event Hubs name and can be filtered by "Type" field to separate tables.

+Use the following command to create a data export rule to an Event Hubs using PowerShell. When specific Event Hubs name isn't provided, a separate container is created for each table, up to the [number of Event Hubs supported in Event Hubs tier](../../event-hubs/event-hubs-quotas.md#common-limits-for-all-tiers). To export more tables, provide an Event Hubs name in rule, or set another rule and export the remaining tables to another Event Hubs namespace.

+Use the following command to create a data export rule to a specific Event Hubs using CLI. All tables are exported to the provided Event Hubs name and can be filtered by "Type" field to separate tables.

+Use the following command to create a data export rule to an Event Hubs using CLI. When specific Event Hubs name isn't provided, a separate container is created for each table up to the [number of supported Event Hubs for your Event Hubs tier](../../event-hubs/event-hubs-quotas.md#common-limits-for-all-tiers). If you have more tables to export, provide Event Hubs name to export any number of tables, or set another rule to export the remaining tables to another Event Hubs namespace.

+Following is a sample body for the REST request for an Event Hubs where Event Hubs name is provided. In this case, all exported data is sent to it.

+Use the following command to create a data export rule to an Event Hubs using Resource Manager template. A separate Event Hubs is created for each table.

+Use the following command to create a data export rule to a specific Event Hubs using Resource Manager template. All tables are exported to it.

+ Title: Logs ingestion API in Azure Monitor (Preview)

+description: Send data to Log Analytics workspace using REST API.

+# Logs ingestion API in Azure Monitor (Preview)

+The Logs ingestion API in Azure Monitor lets you send data to a Log Analytics workspace from any REST API client. This allows you to send data from virtually any source to [supported built-in tables](#supported-tables) or to custom tables that you create. You can even extend the schema of built-in tables with custom columns.

+> [!NOTE]

+> The Logs ingestion API was previously referred to as the custom logs API.

+## Basic operation

+Your application sends data to a [data collection endpoint](../essentials/data-collection-endpoint-overview.md) which is a unique connection point for your subscription. The payload of your API call includes the source data formatted in JSON. The call specifies a [data collection rule](../essentials/data-collection-rule-overview.md) that understands the format of the source data, potentially filters and transforms it for the target table, and then directs it to a specific table in a specific workspace. You can modify the target table and workspace by modifying the data collection rule without any change to the REST API call or source data.

+> [!NOTE]

+> See [Migrate from Data Collector API and custom fields-enabled tables to DCR-based custom logs](custom-logs-migrate.md) to migrate solutions from the [Data Collector API](data-collector-api.md).

+## Supported tables

+### Custom tables

+Logs ingestion API can send data to any custom table that you create and to certain built-in tables in your Log Analytics workspace. The target table must exist before you can send data to it.

+### Built-in tables

+Logs ingestion API can send data to the following built-in tables. Other tables may be added to this list as support for them is implemented.

+- [CommonSecurityLog](/azure/azure-monitor/reference/tables/commonsecuritylog)

+- [SecurityEvents](/azure/azure-monitor/reference/tables/securityevent)

+- [Syslog](/azure/azure-monitor/reference/tables/syslog)

+- [WindowsEvents](/azure/azure-monitor/reference/tables/windowsevent)

+### Table limits

+* Custom tables must have the `_CL` suffix.

+* Column names can consist of alphanumeric characters as well as the characters `_` and `-`. They must start with a letter.

+* Columns extended on top of built-in tables must have the suffix `_CF`. Columns in a custom table do not need this suffix.

+## Authentication

+Authentication for the logs ingestion API is performed at the data collection endpoint which uses standard Azure Resource Manager authentication. A common strategy is to use an Application ID and Application Key as described in [Tutorial: Add ingestion-time transformation to Azure Monitor Logs (preview)](tutorial-logs-ingestion-portal.md).

+## Source data

+The source data sent by your application is formatted in JSON and must match the structure expected by the data collection rule. It doesn't necessarily need to match the structure of the target table since the DCR can include a [transformation](../essentials//data-collection-transformations.md) to convert the data to match the table's structure.

+## Data collection rule

+[Data collection rules](../essentials/data-collection-rule-overview.md) define data collected by Azure Monitor and specify how and where that data should be sent or stored. The REST API call must specify a DCR to use. A single DCE can support multiple DCRs, so you can specify a different DCR for different sources and target tables.

+The DCR must understand the structure of the input data and the structure of the target table. If the two don't match, it can use a [transformation](../essentials/data-collection-transformations.md) to convert the source data to match the target table. You may also use the transformation to filter source data and perform any other calculations or conversions.

+## Sending data

+To send data to Azure Monitor with the logs ingestion API, make a POST call to the data collection endpoint over HTTP. Details of the call are as follows:

+### Endpoint URI

+The endpoint URI uses the following format, where the `Data Collection Endpoint` and `DCR Immutable ID` identify the DCE and DCR. `Stream Name` refers to the [stream](../essentials/data-collection-rule-structure.md#custom-logs) in the DCR that should handle the custom data.

+```

+{Data Collection Endpoint URI}/dataCollectionRules/{DCR Immutable ID}/streams/{Stream Name}?api-version=2021-11-01-preview

+```

+> [!NOTE]

+> You can retrieve the immutable ID from the JSON view of the DCR. See [Collect information from DCR](tutorial-logs-ingestion-portal.md#collect-information-from-dcr).

+### Headers

+| Header | Required? | Value | Description |

+|:|:|:|:|

+| Authorization | Yes | Bearer {Bearer token obtained through the Client Credentials Flow} | |

+| Content-Type | Yes | `application/json` | |

+| Content-Encoding | No | `gzip` | Use the GZip compression scheme for performance optimization. |

+| x-ms-client-request-id | No | String-formatted GUID | Request ID that can be used by Microsoft for any troubleshooting purposes. |

+### Body

+The body of the call includes the custom data to be sent to Azure Monitor. The shape of the data must be a JSON object or array with a structure that matches the format expected by the stream in the DCR.

+## Sample call

+For sample data and API call using the logs ingestion API, see either [Send custom logs to Azure Monitor Logs using the Azure portal (preview)](tutorial-logs-ingestion-portal.md) or [Send custom logs to Azure Monitor Logs using Resource Manager templates](tutorial-logs-ingestion-api.md)

+## Limits and restrictions

+For limits related to Logs ingestion API, see [Azure Monitor service limits](../service-limits.md#logs-ingestion-api).

+

+## Next steps

+- [Walk through a tutorial sending custom logs using the Azure portal.](tutorial-logs-ingestion-portal.md)

+- [Walk through a tutorial sending custom logs using Resource Manager templates and REST API.](tutorial-logs-ingestion-api.md)

+> Tables created by the [Logs ingestion API](../essentials/../logs/logs-ingestion-api-overview.md) don't yet support table-level RBAC.

+# Tables that support transformations in Azure Monitor Logs (preview)

+The following list identifies the tables in a [Log Analytics workspace](log-analytics-workspace-overview.md) that support [transformations](../essentials/data-collection-transformations.md).

+ Title: Tutorial - Send data to Azure Monitor Logs using REST API (Resource Manager templates)

+description: Tutorial on how to send data to a Log Analytics workspace in Azure Monitor using REST API. Resource Manager template version.

+# Tutorial: Send data to Azure Monitor Logs using REST API (Resource Manager templates)

+[Logs ingestion API (preview)](logs-ingestion-api-overview.md) in Azure Monitor allow you to send external data to a Log Analytics workspace with a REST API. This tutorial uses Resource Manager templates to walk through configuration of a new table and a sample application to send log data to Azure Monitor.

+> [!NOTE]

+> This tutorial uses Resource Manager templates and REST API to configure custom logs. See [Tutorial: Send data to Azure Monitor Logs using REST API (Azure portal)](tutorial-logs-ingestion-portal.md) for a similar tutorial using the Azure portal.

+In this tutorial, you learn to:

+> [!div class="checklist"]

+> * Create a custom table in a Log Analytics workspace

+> * Create a data collection endpoint to receive data over HTTP

+> * Create a data collection rule that transforms incoming data to match the schema of the target table

+> * Create a sample application to send custom data to Azure Monitor

+> [!NOTE]

+> This tutorial uses PowerShell from Azure Cloud Shell to make REST API calls using the Azure Monitor **Tables** API and the Azure portal to install Resource Manager templates. You can use any other method to make these calls.

+## Prerequisites

+To complete this tutorial, you need the following:

+- Log Analytics workspace where you have at least [contributor rights](manage-access.md#azure-rbac) .

+- [Permissions to create Data Collection Rule objects](../essentials/data-collection-rule-overview.md#permissions) in the workspace.

+## Collect workspace details

+Start by gathering information that you'll need from your workspace.

+1. Navigate to your workspace in the **Log Analytics workspaces** menu in the Azure portal. From the **Properties** page, copy the **Resource ID** and save it for later use.

+ :::image type="content" source="media/tutorial-logs-ingestion-api/workspace-resource-id.png" lightbox="media/tutorial-logs-ingestion-api/workspace-resource-id.png" alt-text="Screenshot showing workspace resource ID.":::

+## Configure application

+Start by registering an Azure Active Directory application to authenticate against the API. Any ARM authentication scheme is supported, but this will follow the [Client Credential Grant Flow scheme](../../active-directory/develop/v2-oauth2-client-creds-grant-flow.md) for this tutorial.

+1. From the **Azure Active Directory** menu in the Azure portal, select **App registrations** and then **New registration**.

+ :::image type="content" source="media/tutorial-logs-ingestion-portal/new-app-registration.png" lightbox="media/tutorial-logs-ingestion-portal/new-app-registration.png" alt-text="Screenshot showing app registration screen.":::

+2. Give the application a name and change the tenancy scope if the default is not appropriate for your environment. A **Redirect URI** isn't required.

+ :::image type="content" source="media/tutorial-logs-ingestion-portal/new-app-name.png" lightbox="media/tutorial-logs-ingestion-portal/new-app-name.png" alt-text="Screenshot showing app details.":::

+3. Once registered, you can view the details of the application. Note the **Application (client) ID** and the **Directory (tenant) ID**. You'll need these values later in the process.

+ :::image type="content" source="media/tutorial-logs-ingestion-portal/new-app-id.png" lightbox="media/tutorial-logs-ingestion-portal/new-app-id.png" alt-text="Screenshot showing app ID.":::

+4. You now need to generate an application client secret, which is similar to creating a password to use with a username. Select **Certificates & secrets** and then **New client secret**. Give the secret a name to identify its purpose and select an **Expires** duration. *1 year* is selected here although for a production implementation, you would follow best practices for a secret rotation procedure or use a more secure authentication mode such a certificate.

+ :::image type="content" source="media/tutorial-logs-ingestion-portal/new-app-secret.png" lightbox="media/tutorial-logs-ingestion-portal/new-app-secret.png" alt-text="Screenshot showing secret for new app.":::

+5. Click **Add** to save the secret and then note the **Value**. Ensure that you record this value since You can't recover it once you navigate away from this page. Use the same security measures as you would for safekeeping a password as it's the functional equivalent.

+ :::image type="content" source="media/tutorial-logs-ingestion-portal/new-app-secret-value.png" lightbox="media/tutorial-logs-ingestion-portal/new-app-secret-value.png" alt-text="Screenshot show secret value for new app.":::

+## Create new table in Log Analytics workspace

+The custom table must be created before you can send data to it. The table for this tutorial will include three columns, as described in the schema below. The `name`, `type`, and `description` properties are mandatory for each column. The properties `isHidden` and `isDefaultDisplay` both default to `false` if not explicitly specified. Possible data types are `string`, `int`, `long`, `real`, `boolean`, `dateTime`, `guid`, and `dynamic`.

+Use the **Tables - Update** API to create the table with the PowerShell code below.

+> [!IMPORTANT]

+> Custom tables must use a suffix of *_CL*.

+1. Click the **Cloud Shell** button in the Azure portal and ensure the environment is set to **PowerShell**.

+ :::image type="content" source="media/tutorial-workspace-transformations-api/open-cloud-shell.png" lightbox="media/tutorial-workspace-transformations-api/open-cloud-shell.png" alt-text="Screenshot of opening Cloud Shell":::

+2. Copy the following PowerShell code and replace the **Path** parameter with the appropriate values for your workspace in the `Invoke-AzRestMethod` command. Paste it into the Cloud Shell prompt to run it.

+ ```PowerShell

+ $tableParams = @'

+ {

+ "properties": {

+ "schema": {

+ "name": "MyTable_CL",

+ "columns": [

+ {

+ "name": "TimeGenerated",

+ "type": "datetime",

+ "description": "The time at which the data was generated"

+ },

+ {

+ "name": "AdditionalContext",

+ "type": "dynamic",

+ "description": "Additional message properties"

+ },

+ {

+ "name": "ExtendedColumn",

+ "type": "string",

+ "description": "An additional column extended at ingestion time"

+ }

+ ]

+ }

+ }

+ }

+ '@

+ Invoke-AzRestMethod -Path "/subscriptions/{subscription}/resourcegroups/{resourcegroup}/providers/microsoft.operationalinsights/workspaces/{workspace}/tables/MyTable_CL?api-version=2021-12-01-preview" -Method PUT -payload $tableParams

+ ```

+## Create data collection endpoint

+A [data collection endpoint (DCE)](../essentials/data-collection-endpoint-overview.md) is required to accept the data being sent to Azure Monitor. Once you configure the DCE and link it to a data collection rule, you can send data over HTTP from your application. The DCE must be located in the same region as the Log Analytics Workspace where the data will be sent.

+1. In the Azure portal's search box, type in *template* and then select **Deploy a custom template**.

+ :::image type="content" source="media/tutorial-workspace-transformations-api/deploy-custom-template.png" lightbox="media/tutorial-workspace-transformations-api/deploy-custom-template.png" alt-text="Screenshot to deploy custom template.":::

+2. Click **Build your own template in the editor**.

+ :::image type="content" source="media/tutorial-workspace-transformations-api/build-custom-template.png" lightbox="media/tutorial-workspace-transformations-api/build-custom-template.png" alt-text="Screenshot to build template in the editor.":::

+3. Paste the Resource Manager template below into the editor and then click **Save**. You don't need to modify this template since you will provide values for its parameters.

+ :::image type="content" source="media/tutorial-workspace-transformations-api/edit-template.png" lightbox="media/tutorial-workspace-transformations-api/edit-template.png" alt-text="Screenshot to edit Resource Manager template.":::

+ ```json

+ {

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

+ "contentVersion": "1.0.0.0",

+ "parameters": {

+ "dataCollectionEndpointName": {

+ "type": "string",

+ "metadata": {

+ "description": "Specifies the name of the Data Collection Endpoint to create."

+ }

+ },

+ "location": {

+ "type": "string",

+ "defaultValue": "westus2",

+ "allowedValues": [

+ "westus2",

+ "eastus2",

+ "eastus2euap"

+ ],

+ "metadata": {

+ "description": "Specifies the location in which to create the Data Collection Endpoint."

+ }

+ }

+ },

+ "resources": [

+ {

+ "type": "Microsoft.Insights/dataCollectionEndpoints",

+ "name": "[parameters('dataCollectionEndpointName')]",

+ "location": "[parameters('location')]",

+ "apiVersion": "2021-04-01",

+ "properties": {

+ "networkAcls": {

+ "publicNetworkAccess": "Enabled"

+ }

+ }

+ }

+ ],

+ "outputs": {

+ "dataCollectionEndpointId": {

+ "type": "string",

+ "value": "[resourceId('Microsoft.Insights/dataCollectionEndpoints', parameters('dataCollectionEndpointName'))]"

+ }

+ }

+ }

+ ```

+4. On the **Custom deployment** screen, specify a **Subscription** and **Resource group** to store the data collection rule and then provide values a **Name** for the data collection endpoint. The **Location** should be the same location as the workspace. The **Region** will already be populated and is used for the location of the data collection endpoint.

+ :::image type="content" source="media/tutorial-workspace-transformations-api/custom-deployment-values.png" lightbox="media/tutorial-workspace-transformations-api/custom-deployment-values.png" alt-text="Screenshot to edit custom deployment values.":::

+5. Click **Review + create** and then **Create** when you review the details.

+6. Once the DCE is created, select it so you can view its properties. Note the **Logs ingestion URI** since you'll need this in a later step.

+ :::image type="content" source="media/tutorial-logs-ingestion-api/data-collection-endpoint-overview.png" lightbox="media/tutorial-logs-ingestion-api/data-collection-endpoint-overview.png" alt-text="Screenshot for data collection endpoint uri.":::

+7. Click **JSON View** to view other details for the DCE. Copy the **Resource ID** since you'll need this in a later step.

+ :::image type="content" source="media/tutorial-logs-ingestion-api/data-collection-endpoint-json.png" lightbox="media/tutorial-logs-ingestion-api/data-collection-endpoint-json.png" alt-text="Screenshot for data collection endpoint resource ID.":::

+## Create data collection rule

+The [data collection rule (DCR)](../essentials/data-collection-rule-overview.md) defines the schema of data that being sent to the HTTP endpoint, the transformation that will be applied to it, and the destination workspace and table the transformed data will be sent to.

+1. In the Azure portal's search box, type in *template* and then select **Deploy a custom template**.

+ :::image type="content" source="media/tutorial-workspace-transformations-api/deploy-custom-template.png" lightbox="media/tutorial-workspace-transformations-api/deploy-custom-template.png" alt-text="Screenshot to deploy custom template.":::

+2. Click **Build your own template in the editor**.

+ :::image type="content" source="media/tutorial-workspace-transformations-api/build-custom-template.png" lightbox="media/tutorial-workspace-transformations-api/build-custom-template.png" alt-text="Screenshot to build template in the editor.":::

+3. Paste the Resource Manager template below into the editor and then click **Save**.

+ :::image type="content" source="media/tutorial-workspace-transformations-api/edit-template.png" lightbox="media/tutorial-workspace-transformations-api/edit-template.png" alt-text="Screenshot to edit Resource Manager template.":::

+ Notice the following details in the DCR defined in this template:

+ - `dataCollectionEndpointId`: Resource ID of the data collection endpoint.

+ - `streamDeclarations`: Defines the columns of the incoming data.

+ - `destinations`: Specifies the destination workspace.

+ - `dataFlows`: Matches the stream with the destination workspace and specifies the transformation query and the destination table.

+ ```json

+ {

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

+ "contentVersion": "1.0.0.0",

+ "parameters": {

+ "dataCollectionRuleName": {

+ "type": "string",

+ "metadata": {

+ "description": "Specifies the name of the Data Collection Rule to create."

+ }

+ },

+ "location": {

+ "type": "string",

+ "defaultValue": "westus2",

+ "allowedValues": [

+ "westus2",

+ "eastus2",

+ "eastus2euap"

+ ],

+ "metadata": {

+ "description": "Specifies the location in which to create the Data Collection Rule."

+ }

+ },

+ "workspaceResourceId": {

+ "type": "string",

+ "metadata": {

+ "description": "Specifies the Azure resource ID of the Log Analytics workspace to use."

+ }

+ },

+ "endpointResourceId": {

+ "type": "string",

+ "metadata": {

+ "description": "Specifies the Azure resource ID of the Data Collection Endpoint to use."

+ }

+ }

+ },

+ "resources": [

+ {

+ "type": "Microsoft.Insights/dataCollectionRules",

+ "name": "[parameters('dataCollectionRuleName')]",

+ "location": "[parameters('location')]",

+ "apiVersion": "2021-09-01-preview",

+ "properties": {

+ "dataCollectionEndpointId": "[parameters('endpointResourceId')]",

+ "streamDeclarations": {

+ "Custom-MyTableRawData": {

+ "columns": [

+ {

+ "name": "Time",

+ "type": "datetime"

+ },

+ {

+ "name": "Computer",

+ "type": "string"

+ },

+ {

+ "name": "AdditionalContext",

+ "type": "string"

+ }

+ ]

+ }

+ },

+ "destinations": {

+ "logAnalytics": [

+ {

+ "workspaceResourceId": "[parameters('workspaceResourceId')]",

+ "name": "clv2ws1"

+ }

+ ]

+ },

+ "dataFlows": [

+ {

+ "streams": [

+ "Custom-MyTableRawData"

+ ],

+ "destinations": [

+ "clv2ws1"

+ ],

+ "transformKql": "source | extend jsonContext = parse_json(AdditionalContext) | project TimeGenerated = Time, Computer, AdditionalContext = jsonContext, ExtendedColumn=tostring(jsonContext.CounterName)",

+ "outputStream": "Custom-MyTable_CL"

+ }

+ ]

+ }

+ }

+ ],

+ "outputs": {

+ "dataCollectionRuleId": {

+ "type": "string",

+ "value": "[resourceId('Microsoft.Insights/dataCollectionRules', parameters('dataCollectionRuleName'))]"

+ }

+ }

+ }

+ ```

+4. On the **Custom deployment** screen, specify a **Subscription** and **Resource group** to store the data collection rule and then provide values defined in the template. This includes a **Name** for the data collection rule and the **Workspace Resource ID** that you collected in a previous step. The **Location** should be the same location as the workspace. The **Region** will already be populated and is used for the location of the data collection rule.

+ :::image type="content" source="media/tutorial-workspace-transformations-api/custom-deployment-values.png" lightbox="media/tutorial-workspace-transformations-api/custom-deployment-values.png" alt-text="Screenshot to edit custom deployment values.":::

+5. Click **Review + create** and then **Create** when you review the details.

+6. When the deployment is complete, expand the **Deployment details** box and click on your data collection rule to view its details. Click **JSON View**.

+ :::image type="content" source="media/tutorial-workspace-transformations-api/data-collection-rule-details.png" lightbox="media/tutorial-workspace-transformations-api/data-collection-rule-details.png" alt-text="Screenshot for data collection rule details.":::

+7. Copy the **Resource ID** for the data collection rule. You'll use this in the next step.

+ :::image type="content" source="media/tutorial-workspace-transformations-api/data-collection-rule-json-view.png" lightbox="media/tutorial-workspace-transformations-api/data-collection-rule-json-view.png" alt-text="Screenshot for data collection rule JSON view.":::

+ > [!NOTE]

+ > All of the properties of the DCR, such as the transformation, may not be displayed in the Azure portal even though the DCR was successfully created with those properties.

+## Assign permissions to DCR

+Once the data collection rule has been created, the application needs to be given permission to it. This will allow any application using the correct application ID and application key to send data to the new DCE and DCR.

+1. From the DCR in the Azure portal, select **Access Control (IAM)** and then **Add role assignment**.

+ :::image type="content" source="media/tutorial-logs-ingestion-portal/add-role-assignment.png" lightbox="media/tutorial-logs-ingestion-portal/custom-log-create.png" alt-text="Screenshot for adding custom role assignment to DCR.":::

+2. Select **Monitoring Metrics Publisher** and click **Next**. You could instead create a custom action with the `Microsoft.Insights/Telemetry/Write` data action.

+ :::image type="content" source="media/tutorial-logs-ingestion-portal/add-role-assignment-select-role.png" lightbox="media/tutorial-logs-ingestion-portal/add-role-assignment-select-role.png" alt-text="Screenshot for selecting role for DCR role assignment.":::

+3. Select **User, group, or service principal** for **Assign access to** and click **Select members**. Select the application that you created and click **Select**.

+ :::image type="content" source="media/tutorial-logs-ingestion-portal/add-role-assignment-select-member.png" lightbox="media/tutorial-logs-ingestion-portal/add-role-assignment-select-member.png" alt-text="Screenshot for selecting members for DCR role assignment.":::

+4. Click **Review + assign** and verify the details before saving your role assignment.

+ :::image type="content" source="media/tutorial-logs-ingestion-portal/add-role-assignment-save.png" lightbox="media/tutorial-logs-ingestion-portal/add-role-assignment-save.png" alt-text="Screenshot for saving DCR role assignment.":::

+## Send sample data

+The following PowerShell code sends data to the endpoint using HTTP REST fundamentals.

+> [!NOTE]

+> This tutorial uses commands that require PowerShell v7.0 or later. Please make sure your local installation of PowerShell is up to date, or execute this script using the Azure CloudShell.

+1. Run the following PowerShell command which adds a required assembly for the script.

+ ```powershell

+ Add-Type -AssemblyName System.Web

+ ```

+1. Replace the parameters in the *step 0* section with values from the resources that you just created. You may also want to replace the sample data in the *step 2* section with your own.

+ ```powershell

+ ##################

+ ### Step 0: set parameters required for the rest of the script

+ ##################

+ #information needed to authenticate to AAD and obtain a bearer token

+ $tenantId = "00000000-0000-0000-0000-000000000000"; #Tenant ID the data collection endpoint resides in

+ $appId = "00000000-0000-0000-0000-000000000000"; #Application ID created and granted permissions

+ $appSecret = "00000000000000000000000"; #Secret created for the application

+ #information needed to send data to the DCR endpoint

+ $dcrImmutableId = "dcr-000000000000000"; #the immutableId property of the DCR object

+ $dceEndpoint = "https://my-dcr-name.westus2-1.ingest.monitor.azure.com"; #the endpoint property of the Data Collection Endpoint object

+ ##################

+ ### Step 1: obtain a bearer token used later to authenticate against the DCE

+ ##################

+ $scope= [System.Web.HttpUtility]::UrlEncode("https://monitor.azure.com//.default")

+ $body = "client_id=$appId&scope=$scope&client_secret=$appSecret&grant_type=client_credentials";

+ $headers = @{"Content-Type"="application/x-www-form-urlencoded"};

+ $uri = "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token"

+ $bearerToken = (Invoke-RestMethod -Uri $uri -Method "Post" -Body $body -Headers $headers).access_token

+ ##################

+ ### Step 2: Load up some sample data.

+ ##################

+ $currentTime = Get-Date ([datetime]::UtcNow) -Format O

+ $staticData = @"

+ [

+ {

+ "Time": "$currentTime",

+ "Computer": "Computer1",

+ "AdditionalContext": {

+ "InstanceName": "user1",

+ "TimeZone": "Pacific Time",

+ "Level": 4,

+ "CounterName": "AppMetric1",

+ "CounterValue": 15.3

+ }

+ },

+ {

+ "Time": "$currentTime",

+ "Computer": "Computer2",

+ "AdditionalContext": {

+ "InstanceName": "user2",

+ "TimeZone": "Central Time",

+ "Level": 3,

+ "CounterName": "AppMetric1",

+ "CounterValue": 23.5

+ }

+ }

+ ]

+ "@;

+ ##################

+ ### Step 3: send the data to Log Analytics via the DCE.

+ ##################

+ $body = $staticData;

+ $headers = @{"Authorization"="Bearer $bearerToken";"Content-Type"="application/json"};

+ $uri = "$dceEndpoint/dataCollectionRules/$dcrImmutableId/streams/Custom-MyTableRawData?api-version=2021-11-01-preview"

+ $uploadResponse = Invoke-RestMethod -Uri $uri -Method "Post" -Body $body -Headers $headers

+ ```

+ > [!NOTE]

+ > If you receive an `Unable to find type [System.Web.HttpUtility].` error, run the last line in section 1 of the script for a fix and executely. Executing it uncommented as part of the script will not resolve the issue - the command must be executed separately.

+2. After executing this script, you should see a `HTTP - 204` response, and in just a few minutes, the data arrive to your Log Analytics workspace.

+## Troubleshooting

+This section describes different error conditions you may receive and how to correct them.

+### Script returns error code 403

+Ensure that you have the correct permissions for your application to the DCR. You may also need to wait up to 30 minutes for permissions to propagate.

+### Script returns error code 413 or warning of `TimeoutExpired` with the message `ReadyBody_ClientConnectionAbort` in the response

+The message is too large. The maximum message size is currently 1MB per call.

+### Script returns error code 429

+API limits have been exceeded. Refer to [service limits for Logs ingestion API](../service-limits.md#logs-ingestion-api) for details on the current limits.

+### Script returns error code 503

+Ensure that you have the correct permissions for your application to the DCR. You may also need to wait up to 30 minutes for permissions to propagate.

+### You don't receive an error, but data doesn't appear in the workspace

+The data may take some time to be ingested, especially if this is the first time data is being sent to a particular table. It shouldn't take longer than 15 minutes.

+### IntelliSense in Log Analytics not recognizing new table

+The cache that drives IntelliSense may take up to 24 hours to update.

+## Next steps

+- [Complete a similar tutorial using the Azure portal.](tutorial-logs-ingestion-portal.md)

+- [Read more about custom logs.](logs-ingestion-api-overview.md)

+- [Learn more about writing transformation queries](../essentials//data-collection-transformations.md)

+ Title: Tutorial - Send data to Azure Monitor Logs using REST API (Azure portal)

+description: Tutorial on how to send data to a Log Analytics workspace in Azure Monitor using REST API. Azure portal version.

+# Tutorial: Send data to Azure Monitor Logs using REST API (Azure portal)

+[Logs ingestion API (preview)](logs-ingestion-api-overview.md) in Azure Monitor allow you to send external data to a Log Analytics workspace with a REST API. This tutorial uses the Azure portal to walk through configuration of a new table and a sample application to send log data to Azure Monitor.

+> [!NOTE]

+> This tutorial uses the Azure portal. See [Tutorial: Send data to Azure Monitor Logs using REST API (Resource Manager templates)](tutorial-logs-ingestion-api.md) for a similar tutorial using resource manager templates.

+In this tutorial, you learn to:

+> [!div class="checklist"]

+> * Create a custom table in a Log Analytics workspace

+> * Create a data collection endpoint to receive data over HTTP

+> * Create a data collection rule that transforms incoming data to match the schema of the target table

+> * Create a sample application to send custom data to Azure Monitor

+## Prerequisites

+To complete this tutorial, you need the following:

+- Log Analytics workspace where you have at least [contributor rights](manage-access.md#azure-rbac) .

+- [Permissions to create Data Collection Rule objects](../essentials/data-collection-rule-overview.md#permissions) in the workspace.

+## Overview of tutorial

+In this tutorial, you'll use a PowerShell script to send sample Apache access logs over HTTP to the API endpoint. This will require a script to convert this data to the JSON format that's required for the Azure Monitor logs ingestion API. The data will further be converted with a transformation in a data collection rule (DCR) that filters out records that shouldn't be ingested and create the columns required for the table that the data will be sent to. Once the configuration is complete, you'll send sample data from the command line and then inspect the results in Log Analytics.

+## Configure application

+Start by registering an Azure Active Directory application to authenticate against the API. Any ARM authentication scheme is supported, but this will follow the [Client Credential Grant Flow scheme](../../active-directory/develop/v2-oauth2-client-creds-grant-flow.md) for this tutorial.

+1. From the **Azure Active Directory** menu in the Azure portal, select **App registrations** and then **New registration**.

+ :::image type="content" source="media/tutorial-logs-ingestion-portal/new-app-registration.png" lightbox="media/tutorial-logs-ingestion-portal/new-app-registration.png" alt-text="Screenshot showing app registration screen.":::

+2. Give the application a name and change the tenancy scope if the default is not appropriate for your environment. A **Redirect URI** isn't required.

+ :::image type="content" source="media/tutorial-logs-ingestion-portal/new-app-name.png" lightbox="media/tutorial-logs-ingestion-portal/new-app-name.png" alt-text="Screenshot showing app details.":::

+3. Once registered, you can view the details of the application. Note the **Application (client) ID** and the **Directory (tenant) ID**. You'll need these values later in the process.

+ :::image type="content" source="media/tutorial-logs-ingestion-portal/new-app-id.png" lightbox="media/tutorial-logs-ingestion-portal/new-app-id.png" alt-text="Screenshot showing app id.":::

+4. You now need to generate an application client secret, which is similar to creating a password to use with a username. Select **Certificates & secrets** and then **New client secret**. Give the secret a name to identify its purpose and select an **Expires** duration. *1 year* is selected here although for a production implementation, you would follow best practices for a secret rotation procedure or use a more secure authentication mode such a certificate.

+ :::image type="content" source="media/tutorial-logs-ingestion-portal/new-app-secret.png" lightbox="media/tutorial-logs-ingestion-portal/new-app-secret.png" alt-text="Screenshot showing secret for new app.":::

+5. Click **Add** to save the secret and then note the **Value**. Ensure that you record this value since You can't recover it once you navigate away from this page. Use the same security measures as you would for safekeeping a password as it's the functional equivalent.

+ :::image type="content" source="media/tutorial-logs-ingestion-portal/new-app-secret-value.png" lightbox="media/tutorial-logs-ingestion-portal/new-app-secret-value.png" alt-text="Screenshot show secret value for new app.":::

+## Create data collection endpoint

+A [data collection endpoint (DCE)](../essentials/data-collection-endpoint-overview.md) is required to accept the data from the script. Once you configure the DCE and link it to a data collection rule, you can send data over HTTP from your application. The DCE must be located in the same region as the Log Analytics workspace where the data will be sent.

+1. To create a new DCE, go to the **Monitor** menu in the Azure portal. Select **Data Collection Endpoints** and then **Create**.

+ :::image type="content" source="media/tutorial-logs-ingestion-portal/new-data-collection-endpoint.png" lightbox="media/tutorial-logs-ingestion-portal/new-data-collection-endpoint.png" alt-text="Screenshot showing new data collection endpoint.":::

+2. Provide a name for the DCE and ensure that it's in the same region as your workspace. Click **Create** to create the DCE.

+ :::image type="content" source="media/tutorial-logs-ingestion-portal/data-collection-endpoint-details.png" lightbox="media/tutorial-logs-ingestion-portal/data-collection-endpoint-details.png" alt-text="Screenshot showing data collection endpoint details.":::

+3. Once the DCE is created, select it so you can view its properties. Note the **Logs ingestion** URI since you'll need this in a later step.

+ :::image type="content" source="media/tutorial-logs-ingestion-portal/data-collection-endpoint-uri.png" lightbox="media/tutorial-logs-ingestion-portal/data-collection-endpoint-uri.png" alt-text="Screenshot showing data collection endpoint uri.":::

+## Generate sample data

+The following PowerShell script both generates sample data to configure the custom table and sends sample data to the logs ingestion API to test the configuration.

+1. Run the following PowerShell command which adds a required assembly for the script.

+ ```powershell

+ Add-Type -AssemblyName System.Web

+ ```

+2. Update the values of `$tenantId`, `$appId`, and `$appSecret` with the values you noted for **Directory (tenant) ID**, **Application (client) ID**, and secret **Value** and then save with the file name *LogGenerator.ps1*.

+ ``` PowerShell

+ param ([Parameter(Mandatory=$true)] $Log, $Type="file", $Output, $DcrImmutableId, $DceURI, $Table)

+ ################

+ ##### Usage

+ ################

+ # LogGenerator.ps1

+ # -Log <String> - log file to be forwarded

+ # [-Type "file|API"] - whether the script should generate sample JSON file or send data via

+ # API call. Data will be written to a file by default

+ # [-Output <String>] - path to resulting JSON sample

+ # [-DcrImmutableId <string>] - DCR immutable ID

+ # [-DceURI] - Data collection endpoint URI

+ # [-Table] - The name of the custom log table, including "_CL" suffix

+ ##### >>>> PUT YOUR VALUES HERE <<<<<

+ # information needed to authenticate to AAD and obtain a bearer token

+ $tenantId = "<put tenant ID here>"; #the tenant ID in which the Data Collection Endpoint resides

+ $appId = "<put application ID here>"; #the app ID created and granted permissions

+ $appSecret = "<put secret value here>"; #the secret created for the above app - never store your secrets in the source code

+ ##### >>>> END <<<<<

+ $file_data = Get-Content $Log

+ if ("file" -eq $Type) {

+ ############

+ ## Convert plain log to JSON format and output to .json file

+ ############

+ # If not provided, get output file name

+ if ($null -eq $Output) {

+ $Output = Read-Host "Enter output file name"

+ };

+ # Form file payload

+ $payload = @();

+ $records_to_generate = [math]::min($file_data.count, 500)

+ for ($i=0; $i -lt $records_to_generate; $i++) {

+ $log_entry = @{

+ # Define the structure of log entry, as it will be sent

+ Time = Get-Date ([datetime]::UtcNow) -Format O

+ Application = "LogGenerator"

+ RawData = $file_data[$i]

+ }

+ $payload += $log_entry

+ }

+ # Write resulting payload to file

+ New-Item -Path $Output -ItemType "file" -Value ($payload | ConvertTo-Json) -Force

+ } else {

+ ############

+ ## Send the content to the data collection endpoint

+ ############

+ if ($null -eq $DcrImmutableId) {

+ $DcrImmutableId = Read-Host "Enter DCR Immutable ID"

+ };

+ if ($null -eq $DceURI) {

+ $DceURI = Read-Host "Enter data collection endpoint URI"

+ }

+ if ($null -eq $Table) {

+ $Table = Read-Host "Enter the name of custom log table"

+ }

+ ## Obtain a bearer token used to authenticate against the data collection endpoint

+ $scope = [System.Web.HttpUtility]::UrlEncode("https://monitor.azure.com//.default")

+ $body = "client_id=$appId&scope=$scope&client_secret=$appSecret&grant_type=client_credentials";

+ $headers = @{"Content-Type" = "application/x-www-form-urlencoded" };

+ $uri = "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token"

+ $bearerToken = (Invoke-RestMethod -Uri $uri -Method "Post" -Body $body -Headers $headers).access_token

+ ## Generate and send some data

+ foreach ($line in $file_data) {

+ # We are going to send log entries one by one with a small delay

+ $log_entry = @{

+ # Define the structure of log entry, as it will be sent

+ Time = Get-Date ([datetime]::UtcNow) -Format O

+ Application = "LogGenerator"

+ RawData = $line

+ }

+ # Sending the data to Log Analytics via the DCR!

+ $body = $log_entry | ConvertTo-Json -AsArray;

+ $headers = @{"Authorization" = "Bearer $bearerToken"; "Content-Type" = "application/json" };

+ $uri = "$DceURI/dataCollectionRules/$DcrImmutableId/streams/Custom-$Table"+"?api-version=2021-11-01-preview";

+ $uploadResponse = Invoke-RestMethod -Uri $uri -Method "Post" -Body $body -Headers $headers;

+ # Let's see how the response looks like

+ Write-Output $uploadResponse

+ Write-Output ""

+ # Pausing for 1 second before processing the next entry

+ Start-Sleep -Seconds 1

+ }

+ }

+ ```

+3. Copy the sample log data from [sample data](#sample-data) or copy your own Apache log data into a file called `sample_access.log`.

+4. To read the data in the file and create a JSON file called `data_sample.json` that you can send to the logs ingestion API, run:

+ ```PowerShell

+ .\LogGenerator.ps1 -Log "sample_access.log" -Type "file" -Output "data_sample.json"

+ ```

+

+## Add custom log table

+Before you can send data to the workspace, you need to create the custom table that the data will be sent to.

+1. Go to the **Log Analytics workspaces** menu in the Azure portal and select **Tables (preview)**. The tables in the workspace will be displayed. Select **Create** and then **New custom log (DCR based)**.

+ :::image type="content" source="media/tutorial-logs-ingestion-portal/new-custom-log.png" lightbox="media/tutorial-logs-ingestion-portal/new-custom-log.png" alt-text="Screenshot showing new DCR-based custom log.":::

+2. Specify a name for the table. You don't need to add the *_CL* suffix required for a custom table since this will be automatically added to the name you specify.

+3. Click **Create a new data collection rule** to create the DCR that will be used to send data to this table. If you have an existing data collection rule, you can choose to use it instead. Specify the **Subscription**, **Resource group**, and **Name** for the data collection rule that will contain the custom log configuration.

+ :::image type="content" source="media/tutorial-logs-ingestion-portal/new-data-collection-rule.png" lightbox="media/tutorial-logs-ingestion-portal/new-data-collection-rule.png" alt-text="Screenshot showing new data collection rule.":::

+4. Select the data collection endpoint that you created and click **Next**.

+ :::image type="content" source="media/tutorial-logs-ingestion-portal/custom-log-table-name.png" lightbox="media/tutorial-logs-ingestion-portal/custom-log-table-name.png" alt-text="Screenshot showing custom log table name.":::

+## Parse and filter sample data

+Instead of directly configuring the schema of the table, the portal allows you to upload sample data so that Azure Monitor can determine the schema. The sample is expected to be a JSON file containing one or multiple log records structured in the same way they will be sent in the body of HTTP request of the logs ingestion API call.

+1. Click **Browse for files** and locate *data_sample.json* that you previously created.

+ :::image type="content" source="media/tutorial-logs-ingestion-portal/custom-log-browse-files.png" lightbox="media/tutorial-logs-ingestion-portal/custom-log-browse-files.png" alt-text="Screenshot showing custom log browse for files.":::

+2. Data from the sample file is displayed with a warning that a `TimeGenerated` is not in the data. All log tables within Azure Monitor Logs are required to have a `TimeGenerated` column populated with the timestamp of logged event. In this sample, the timestamp of event is stored in field called `Time`. You're going to add a transformation that will rename this column in the output.

+3. Click **Transformation editor** to open the transformation editor to add this column. You're going to add a transformation that will rename this column in the output. The transformation editor lets you create a transformation for the incoming data stream. This is a KQL query that is run against each incoming record. The results of the query will be stored in the destination table. See [Data collection rule transformations in Azure Monitor](../essentials//data-collection-transformations.md) for details on transformation queries.

+ :::image type="content" source="media/tutorial-logs-ingestion-portal/custom-log-data-preview.png" lightbox="media/tutorial-logs-ingestion-portal/custom-log-data-preview.png" alt-text="Screenshot showing custom log data preview.":::

+4. Add the following query to the transformation editor to add the `TimeGenerated` column to the output.

+ ```kusto

+ source

+ | extend TimeGenerated = todatetime(Time)

+ ```

+5. Click **Run** to view the results. You can see that the `TimeGenerated` column is now added to the other columns. Most of the interesting data is contained in the `RawData` column though

+ :::image type="content" source="media/tutorial-logs-ingestion-portal/custom-log-query-01.png" lightbox="media/tutorial-logs-ingestion-portal/custom-log-query-01.png" alt-text="Screenshot showing initial custom log data query.":::

+6. Modify the query to the following, which extracts the client IP address, HTTP method, address of the page being access, and the response code from each log entry.

+ ```kusto

+ source

+ | extend TimeGenerated = todatetime(Time)

+ | parse RawData with

+ ClientIP:string

+ ' ' *

+ ' ' *

+ ' [' * '] "' RequestType:string

+ " " Resource:string

+ " " *

+ '" ' ResponseCode:int

+ " " *

+ ```

+7. Click **Run** to views the results. This extracts the contents of `RawData` into separate columns `ClientIP`, `RequestType`, `Resource`, and `ResponseCode`.

+ :::image type="content" source="media/tutorial-logs-ingestion-portal/custom-log-query-02.png" lightbox="media/tutorial-logs-ingestion-portal/custom-log-query-02.png" alt-text="Screenshot showing custom log data query with parse command.":::

+8. The query can be optimized more though by removing the `RawData` and `Time` columns since they aren't needed anymore.You can also filter out any records with `ResponseCode` of 200 since you're only interested in collecting data for requests that were not successful. This reduces the volume of data being ingested which reduces its overall cost.

+ ```kusto

+ source

+ | extend TimeGenerated = todatetime(Time)

+ | parse RawData with

+ ClientIP:string

+ ' ' *

+ ' ' *

+ ' [' * '] "' RequestType:string

+ " " Resource:string

+ " " *

+ '" ' ResponseCode:int

+ " " *

+ | where ResponseCode != 200

+ | project-away Time, RawData

+ ```

+9. Click **Run** to views the results.

+ :::image type="content" source="media/tutorial-logs-ingestion-portal/custom-log-query-03.png" lightbox="media/tutorial-logs-ingestion-portal/custom-log-query-03.png" alt-text="Screenshot showing custom log data query with filter.":::

+10. Click **Apply** to save the transformation and view the schema of the table that's about to be created. Click **Next** to proceed.

+ :::image type="content" source="media/tutorial-logs-ingestion-portal/custom-log-final-schema.png" lightbox="media/tutorial-logs-ingestion-portal/custom-log-final-schema.png" alt-text="Screenshot showing custom log final schema.":::

+11. Verify the final details and click **Create** to save the custom log.

+ :::image type="content" source="media/tutorial-logs-ingestion-portal/custom-log-create.png" lightbox="media/tutorial-logs-ingestion-portal/custom-log-create.png" alt-text="Screenshot showing custom log create.":::

+## Collect information from DCR

+With the data collection rule created, you need to collect its ID which is needed in the API call.

+1. From the **Monitor** menu in the Azure portal, select **Data collection rules** and select the DCR you just created. From **Overview** for the data collection rule, select the **JSON View**.

+ :::image type="content" source="media/tutorial-logs-ingestion-portal/data-collection-rule-json-view.png" lightbox="media/tutorial-logs-ingestion-portal/data-collection-rule-json-view.png" alt-text="Screenshot showing data collection rule JSON view.":::

+2. Copy the **immutableId** value.

+ :::image type="content" source="media/tutorial-logs-ingestion-portal/data-collection-rule-immutable-id.png" lightbox="media/tutorial-logs-ingestion-portal/data-collection-rule-immutable-id.png" alt-text="Screenshot showing collecting immutable ID from JSON view.":::

+## Assign permissions to DCR

+The final step is to give the application permission to use the DCR. This will allow any application using the correct application ID and application key to send data to the new DCE and DCR.

+1. Select **Access Control (IAM)** for the DCR and then **Add role assignment**.

+ :::image type="content" source="media/tutorial-logs-ingestion-portal/add-role-assignment.png" lightbox="media/tutorial-logs-ingestion-portal/custom-log-create.png" alt-text="Screenshot showing adding custom role assignment to DCR.":::

+2. Select **Monitoring Metrics Publisher** and click **Next**. You could instead create a custom action with the `Microsoft.Insights/Telemetry/Write` data action.

+ :::image type="content" source="media/tutorial-logs-ingestion-portal/add-role-assignment-select-role.png" lightbox="media/tutorial-logs-ingestion-portal/add-role-assignment-select-role.png" alt-text="Screenshot showing selecting role for DCR role assignment.":::

+3. Select **User, group, or service principal** for **Assign access to** and click **Select members**. Select the application that you created and click **Select**.

+ :::image type="content" source="media/tutorial-logs-ingestion-portal/add-role-assignment-select-member.png" lightbox="media/tutorial-logs-ingestion-portal/add-role-assignment-select-member.png" alt-text="Screenshot showing selecting members for DCR role assignment.":::

+4. Click **Review + assign** and verify the details before saving your role assignment.

+ :::image type="content" source="media/tutorial-logs-ingestion-portal/add-role-assignment-save.png" lightbox="media/tutorial-logs-ingestion-portal/add-role-assignment-save.png" alt-text="Screenshot showing saving DCR role assignment.":::

+## Send sample data

+Allow at least 30 minutes for the configuration to take effect. You may also experience increased latency for the first few entries, but this should normalize.

+1. Run the following command providing the values that you collected for your data collection rule and data collection endpoint. The script will start ingesting data by placing calls to the API at pace of approximately 1 record per second.

+```PowerShell

+.\LogGenerator.ps1 -Log "sample_access.log" -Type "API" -Table "ApacheAccess_CL" -DcrImmutableId <immutable ID> -DceUri <data collection endpoint URL>

+```

+2. From Log Analytics, query your newly created table to verify that data arrived and if it is transformed properly.

+## Troubleshooting

+This section describes different error conditions you may receive and how to correct them.

+### Script returns error code 403

+Ensure that you have the correct permissions for your application to the DCR. You may also need to wait up to 30 minutes for permissions to propagate.

+### Script returns error code 413 or warning of `TimeoutExpired` with the message `ReadyBody_ClientConnectionAbort` in the response

+The message is too large. The maximum message size is currently 1MB per call.

+### Script returns error code 429

+API limits have been exceeded. The limits are currently set to 500MB of data/minute for both compressed and uncompressed data, as well as 300,000 requests/minute. Retry after the duration listed in the `Retry-After` header in the response.

+### Script returns error code 503

+Ensure that you have the correct permissions for your application to the DCR. You may also need to wait up to 30 minutes for permissions to propagate.

+### You don't receive an error, but data doesn't appear in the workspace

+The data may take some time to be ingested, especially if this is the first time data is being sent to a particular table. It shouldn't take longer than 15 minutes.

+### IntelliSense in Log Analytics not recognizing new table

+The cache that drives IntelliSense may take up to 24 hours to update.

+## Sample data

+Following is sample data that you can use for the tutorial. Alternatively, you can use your own data if you have your own Apache access logs.

+```

+0.0.139.0

+0.0.153.185

+0.0.153.185

+0.0.66.230

+0.0.148.92

+0.0.35.224

+0.0.162.225

+0.0.162.225

+0.0.148.108

+0.0.148.1

+0.0.203.24

+0.0.4.214

+0.0.10.125

+0.0.10.125

+0.0.10.125

+0.0.10.125

+0.0.10.117

+0.0.10.114

+0.0.10.114

+0.0.10.125

+0.0.10.117

+0.0.10.117

+0.0.10.114

+0.0.10.114

+0.0.10.125

+0.0.10.114

+0.0.10.114

+0.0.10.125

+0.0.10.117

+0.0.10.117

+0.0.10.114

+0.0.10.125

+0.0.10.117

+0.0.10.114

+0.0.10.117

+0.0.10.125

+0.0.10.125

+0.0.10.125

+0.0.10.125

+0.0.10.125

+0.0.10.125

+0.0.10.114

+0.0.10.117

+0.0.167.138

+0.0.149.55

+0.0.229.86

+0.0.117.249

+0.0.117.249

+0.0.117.249

+0.0.64.41

+0.0.208.79

+0.0.208.79

+0.0.208.79

+0.0.208.79

+0.0.196.129

+0.0.196.129

+0.0.66.158

+0.0.161.12

+0.0.161.12

+0.0.51.36

+0.0.51.36

+0.0.145.131

+0.0.145.131

+0.0.0.179

+0.0.0.179

+0.0.145.131

+0.0.145.131

+0.0.95.52

+0.0.95.52

+0.0.51.36

+0.0.51.36

+0.0.227.31

+0.0.227.31

+0.0.51.36

+0.0.51.36

+0.0.51.36

+0.0.51.36

+0.0.4.22

+0.0.4.22

+0.0.143.24

+0.0.143.24

+0.0.0.98

+0.0.0.98

+0.0.51.62

+0.0.51.62

+0.0.51.36

+0.0.51.36

+0.0.0.98

+0.0.0.98

+0.0.58.254

+0.0.58.254

+0.0.51.62

+0.0.51.62

+0.0.227.31

+0.0.227.31

+0.0.0.179

+0.0.0.179

+0.0.58.254

+0.0.58.254

+0.0.95.52

+0.0.95.52

+0.0.0.98

+0.0.0.98

+0.0.58.90

+0.0.58.90

+0.0.51.36

+0.0.51.36

+0.0.207.154

+0.0.207.154

+0.0.95.52

+0.0.95.52

+0.0.51.62

+0.0.51.62

+0.0.145.131

+0.0.145.131

+0.0.58.90

+0.0.58.90

+0.0.227.55

+0.0.227.55

+0.0.95.52

+0.0.95.52

+0.0.161.12

+0.0.161.12

+0.0.227.55

+0.0.227.55

+0.0.143.30

+0.0.143.30

+0.0.227.31

+0.0.227.31

+0.0.161.6

+0.0.161.6

+0.0.161.6

+0.0.227.31

+0.0.227.31

+0.0.51.62

+0.0.51.62

+0.0.227.31

+0.0.227.31

+0.0.95.20

+0.0.95.20

+0.0.207.154

+0.0.207.154

+0.0.0.98

+0.0.0.98

+0.0.51.36

+0.0.51.36

+0.0.227.55

+0.0.227.55

+0.0.207.154

+0.0.207.154

+0.0.51.36

+0.0.51.36

+0.0.51.36

+0.0.51.36

+0.0.207.221

+0.0.207.221

+0.0.0.179

+0.0.0.179

+0.0.161.12

+0.0.161.12

+0.0.58.90

+0.0.58.90

+0.0.145.106

+0.0.145.106

+0.0.145.106

+0.0.145.106

+0.0.0.179

+0.0.0.179

+0.0.149.8

+0.0.207.154

+0.0.207.154

+0.0.227.31

+0.0.227.31

+0.0.51.62

+0.0.51.62

+0.0.227.55

+0.0.227.55

+0.0.143.30

+0.0.143.30

+0.0.95.52

+0.0.95.52

+0.0.145.131

+0.0.145.131

+0.0.51.62

+0.0.51.62

+0.0.0.98

+0.0.0.98

+0.0.207.221

+0.0.145.131

+0.0.207.221

+0.0.145.131

+0.0.51.62

+0.0.51.62

+0.0.51.36

+0.0.51.36

+0.0.145.131

+0.0.145.131

+0.0.58.254

+0.0.58.254

+0.0.145.106

+0.0.145.106

+0.0.207.221

+0.0.207.221

+0.0.227.31

+0.0.227.31

+0.0.145.106

+0.0.145.106

+0.0.145.131

+0.0.145.131

+0.0.0.179

+0.0.0.179

+0.0.227.31

+0.0.227.31

+0.0.227.55

+0.0.227.55

+0.0.95.52

+0.0.95.52

+0.0.0.98

+0.0.0.98

+0.0.4.35

+0.0.4.35

+0.0.4.22

+0.0.4.22

+0.0.58.90

+0.0.58.90

+0.0.145.106

+0.0.145.106

+0.0.143.24

+0.0.143.24

+0.0.227.55

+0.0.227.55

+0.0.207.154

+0.0.207.154

+0.0.143.30

+0.0.143.30

+0.0.227.31

+0.0.227.31

+0.0.0.179

+0.0.0.179

+0.0.0.98

+0.0.0.98

+0.0.207.221

+0.0.207.221

+0.0.0.179

+0.0.0.179

+0.0.0.98

+0.0.0.98

+0.0.207.221

+0.0.207.221

+0.0.207.154

+0.0.207.154

+0.0.58.254

+0.0.58.254

+0.0.51.36

+0.0.51.36

+0.0.51.36

+0.0.51.36

+0.0.207.154

+0.0.207.154

+0.0.161.6

+0.0.145.131

+0.0.145.131

+0.0.207.221

+0.0.207.221

+0.0.95.20

+0.0.95.20

+0.0.183.233

+0.0.183.233

+0.0.51.36

+0.0.51.36

+0.0.95.52

+0.0.95.52

+0.0.227.31

+0.0.227.31

+0.0.51.62

+0.0.51.62

+0.0.95.52

+0.0.95.52

+0.0.207.154

+0.0.207.154

+0.0.51.36

+0.0.51.36

+0.0.58.90

+0.0.58.90

+0.0.4.35

+0.0.4.35

+0.0.95.52

+0.0.95.52

+0.0.167.138

+0.0.51.36

+0.0.51.36

+0.0.161.6

+0.0.161.6

+0.0.58.254

+0.0.58.254

+0.0.207.154

+0.0.207.154

+0.0.58.90

+0.0.58.90

+0.0.51.62

+0.0.51.62

+0.0.58.90

+0.0.58.90

+0.0.81.164

+0.0.81.164

+0.0.207.221

+0.0.207.221

+0.0.227.55

+0.0.227.55

+0.0.227.55

+0.0.227.55

+0.0.207.221

+0.0.207.154

+0.0.207.154

+0.0.207.221

+0.0.143.30

+0.0.143.30

+0.0.0.179

+0.0.0.179

+0.0.51.62

+0.0.51.62

+0.0.4.35

+0.0.4.35

+0.0.207.221

+0.0.207.221

+0.0.51.62

+0.0.51.62

+0.0.51.62

+0.0.51.62

+0.0.95.20

+0.0.4.35

+0.0.4.35

+0.0.58.254

+0.0.58.254

+0.0.145.106

+0.0.145.106

+0.0.0.98

+0.0.0.98

+0.0.95.52

+0.0.95.52

+0.0.51.62

+0.0.51.62

+0.0.207.221

+0.0.207.221

+0.0.143.30

+0.0.143.30

+0.0.207.154

+0.0.207.154

+0.0.143.30

+0.0.95.20

+0.0.95.20

+0.0.0.98

+0.0.0.98

+0.0.145.131

+0.0.145.131

+0.0.161.12

+0.0.161.12

+0.0.95.52

+0.0.95.52

+0.0.161.12

+0.0.161.12

+0.0.0.179

+0.0.0.179

+0.0.4.35

+0.0.4.35

+0.0.164.246

+0.0.161.12

+0.0.161.12

+0.0.161.12

+0.0.161.12

+0.0.207.221

+0.0.207.221

+0.0.4.35

+0.0.4.35

+0.0.207.221

+0.0.207.221

+0.0.145.106

+0.0.145.106

+0.0.4.22

+0.0.4.22

+0.0.161.12

+0.0.161.12

+0.0.58.254

+0.0.58.254

+0.0.161.12

+0.0.161.12

+0.0.66.216

+0.0.0.179

+0.0.0.179

+0.0.145.131

+0.0.145.131

+0.0.4.35

+0.0.4.35

+0.0.58.254

+0.0.58.254

+0.0.143.24

+0.0.143.24

+0.0.143.24

+0.0.143.24

+0.0.207.221

+0.0.207.221

+0.0.58.254

+0.0.58.254

+0.0.145.131

+0.0.145.131

+0.0.51.36

+0.0.51.36

+0.0.227.31

+0.0.161.12

+0.0.227.31

+0.0.161.6

+0.0.161.6

+0.0.207.221

+0.0.207.221

+0.0.161.12

+0.0.145.106

+0.0.145.106

+0.0.161.6

+0.0.161.6

+0.0.95.20

+0.0.95.20

+0.0.4.35

+0.0.4.35

+0.0.95.52

+0.0.95.52

+0.0.128.50

+0.0.227.31

+0.0.227.31

+0.0.227.31

+0.0.227.31

+0.0.227.55

+0.0.227.55

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+0.0.29.211

+```

+## Next steps

+- [Complete a similar tutorial using the Azure portal.](tutorial-logs-ingestion-api.md)

+- [Read more about custom logs.](logs-ingestion-api-overview.md)

+- [Learn more about writing transformation queries](../essentials//data-collection-transformations.md)

+ Title: Tutorial - Add ingestion-time transformation to Azure Monitor Logs using resource manager templates

+description: Describes how to add a custom transformation to data flowing through Azure Monitor Logs using resource manager templates.

+# Tutorial: Add transformation in workspace data collection rule to Azure Monitor using resource manager templates (preview)

+This tutorial walks you through configuration of a sample [transformation in a workspace data collection rule](../essentials/data-collection-transformations.md) using resource manager templates. [Transformations](../essentials/data-collection-transformations.md) in Azure Monitor allow you to filter or modify incoming data before it's sent to its destination. Workspace transformations provide support for [ingestion-time transformations](../essentials/data-collection-transformations.md) for workflows that don't yet use the [Azure Monitor data ingestion pipeline](../essentials/data-collection.md).

+Workspace transformations are stored together in a single [data collection rule (DCR)](../essentials/data-collection-rule-overview.md) for the workspace, called the workspace DCR. Each transformation is associated with a particular table. The transformation will be applied to all data sent to this table from any workflow not using a DCR.

+> [!NOTE]

+> This tutorial uses resource manager templates and REST API to configure a workspace transformation. See [Tutorial: Add transformation in workspace data collection rule to Azure Monitor using the Azure portal (preview)](tutorial-workspace-transformations-portal.md) for the same tutorial using the Azure portal.

+In this tutorial, you learn to:

+> [!div class="checklist"]

+> * Configure [workspace transformation](../essentials/data-collection-transformations.md#workspace-transformation-dcr) for a table in a Log Analytics workspace.

+> * Write a log query for an ingestion-time transform.

+> [!NOTE]

+> This tutorial uses PowerShell from Azure Cloud Shell to make REST API calls using the Azure Monitor **Tables** API and the Azure portal to install resource manager templates. You can use any other method to make these calls.

+## Prerequisites

+To complete this tutorial, you need the following:

+- Log Analytics workspace where you have at least [contributor rights](manage-access.md#azure-rbac).

+- [Permissions to create Data Collection Rule objects](../essentials/data-collection-rule-overview.md#permissions) in the workspace.

+- The table must already have some data.

+- The table can't already be linked to the [workspace transformation DCR](../essentials/data-collection-transformations.md#workspace-transformation-dcr).

+## Overview of tutorial

+In this tutorial, you'll reduce the storage requirement for the `LAQueryLogs` table by filtering out certain records. You'll also remove the contents of a column while parsing the column data to store a piece of data in a custom column. The [LAQueryLogs table](query-audit.md#audit-data) is created when you enable [log query auditing](query-audit.md) in a workspace, but this is only used as a sample for the tutorial. You can use this same basic process to create a transformation for any [supported table](tables-feature-support.md) in a Log Analytics workspace.

+## Enable query audit logs

+You need to enable [query auditing](query-audit.md) for your workspace to create the `LAQueryLogs` table that you'll be working with. This is not required for all ingestion time transformations. It's just to generate the sample data that this sample transformation will use.

+1. From the **Log Analytics workspaces** menu in the Azure portal, select **Diagnostic settings** and then **Add diagnostic setting**.

+ :::image type="content" source="media/tutorial-workspace-transformations-portal/diagnostic-settings.png" lightbox="media/tutorial-workspace-transformations-portal/diagnostic-settings.png" alt-text="Screenshot of diagnostic settings.":::

+2. Provide a name for the diagnostic setting and select the workspace so that the auditing data is stored in the same workspace. Select the **Audit** category and then click **Save** to save the diagnostic setting and close the diagnostic setting page.

+ :::image type="content" source="media/tutorial-workspace-transformations-portal/new-diagnostic-setting.png" lightbox="media/tutorial-workspace-transformations-portal/new-diagnostic-setting.png" alt-text="Screenshot of new diagnostic setting.":::

+3. Select **Logs** and then run some queries to populate `LAQueryLogs` with some data. These queries don't need to actually return any data.

+ :::image type="content" source="media/tutorial-workspace-transformations-portal/sample-queries.png" lightbox="media/tutorial-workspace-transformations-portal/sample-queries.png" alt-text="Screenshot of sample log queries.":::

+## Update table schema

+Before you can create the transformation, the following two changes must be made to the table:

+- The table must be enabled for workspace transformation. This is required for any table that will have a transformation, even if the transformation doesn't modify the table's schema.

+- Any additional columns populated by the transformation must be added to the table.

+Use the **Tables - Update** API to configure the table with the PowerShell code below. Calling the API enables the table for workspace transformations, whether or not custom columns are defined. In this sample, it includes a custom column called *Resources_CF* that will be populated with the transformation query.

+> [!IMPORTANT]

+> Any custom columns added to a built-in table must end in *_CF*. Columns added to a custom table (a table with a name that ends in *_CL*) does not need to have this suffix.

+1. Click the **Cloud Shell** button in the Azure portal and ensure the environment is set to **PowerShell**.

+ :::image type="content" source="media/tutorial-workspace-transformations-api/open-cloud-shell.png" lightbox="media/tutorial-workspace-transformations-api/open-cloud-shell.png" alt-text="Screenshot of opening cloud shell.":::

+2. Copy the following PowerShell code and replace the **Path** parameter with the details for your workspace.

+ ```PowerShell

+ $tableParams = @'

+ {

+ "properties": {

+ "schema": {

+ "name": "LAQueryLogs",

+ "columns": [

+ {

+ "name": "Resources_CF",

+ "description": "The list of resources, this query ran against",

+ "type": "string",

+ "isDefaultDisplay": true,

+ "isHidden": false

+ }

+ ]

+ }

+ }

+ }

+ '@

+ Invoke-AzRestMethod -Path "/subscriptions/{subscription}/resourcegroups/{resourcegroup}/providers/microsoft.operationalinsights/workspaces/{workspace}/tables/LAQueryLogs?api-version=2021-12-01-preview" -Method PUT -payload $tableParams

+ ```

+3. Paste the code into the cloud shell prompt to run it.

+ :::image type="content" source="media/tutorial-workspace-transformations-api/cloud-shell-script.png" lightbox="media/tutorial-workspace-transformations-api/cloud-shell-script.png" alt-text="Screenshot of script in cloud shell.":::

+4. You can verify that the column was added by going to the **Log Analytics workspace** menu in the Azure portal. Select **Logs** to open Log Analytics and then expand the `LAQueryLogs` table to view its columns.

+ :::image type="content" source="media/tutorial-workspace-transformations-portal/verify-table.png" lightbox="media/tutorial-workspace-transformations-portal/verify-table.png" alt-text="Screenshot of Log Analytics with new column.":::

+## Define transformation query

+Use Log Analytics to test the transformation query before adding it to a data collection rule.

+1. Open your workspace in the **Log Analytics workspaces** menu in the Azure portal and select **Logs** to open Log Analytics.

+2. Run the following query to view the contents of the `LAQueryLogs` table. Notice the contents of the `RequestContext` column. The transformation will retrieve the workspace name from this column and remove the rest of the data in it.

+ ```kusto

+ LAQueryLogs

+ | take 10

+ ```

+ :::image type="content" source="media/tutorial-workspace-transformations-portal/initial-query.png" lightbox="media/tutorial-workspace-transformations-portal/initial-query.png" alt-text="Screenshot of initial query in Log Analytics.":::

+3. Modify the query to the following:

+ ``` kusto

+ LAQueryLogs

+ | where QueryText !contains 'LAQueryLogs'

+ | extend Context = parse_json(RequestContext)

+ | extend Workspace_CF = tostring(Context['workspaces'][0])

+ | project-away RequestContext, Context

+ ```

+ This makes the following changes:

+ - Drop rows related to querying the `LAQueryLogs` table itself to save space since these log entries aren't useful.

+ - Add a column for the name of the workspace that was queried.

+ - Remove data from the `RequestContext` column to save space.

+ :::image type="content" source="media/tutorial-workspace-transformations-portal/modified-query.png" lightbox="media/tutorial-workspace-transformations-portal/modified-query.png" alt-text="Screenshot of modified query in Log Analytics.":::

+4. Make the following changes to the query to use it in the transformation:

+ - Instead of specifying a table name (`LAQueryLogs` in this case) as the source of data for this query, use the `source` keyword. This is a virtual table that always represents the incoming data in a transformation query.

+ - Remove any operators that aren't supported by transform queries. See [Supported tables for ingestion-time transformations](tables-feature-support.md) for a detail list of operators that are supported.

+ - Flatten the query to a single line so that it can fit into the DCR JSON.

+ Following is the query that you will use in the transformation after these modifications:

+ ```kusto

+ source | where QueryText !contains 'LAQueryLogs' | extend Context = parse_json(RequestContext) | extend Resources_CF = tostring(Context['workspaces']) |extend RequestContext = ''

+ ```

+## Create data collection rule (DCR)

+Since this is the first transformation in the workspace, you need to create a [workspace transformation DCR](../essentials/data-collection-transformations.md#workspace-transformation-dcr). If you create workspace transformations for other tables in the same workspace, they must be stored in this same DCR.

+1. In the Azure portal's search box, type in *template* and then select **Deploy a custom template**.

+ :::image type="content" source="media/tutorial-workspace-transformations-api/deploy-custom-template.png" lightbox="media/tutorial-workspace-transformations-api/deploy-custom-template.png" alt-text="Screenshot to deploy custom template.":::

+2. Click **Build your own template in the editor**.

+ :::image type="content" source="media/tutorial-workspace-transformations-api/build-custom-template.png" lightbox="media/tutorial-workspace-transformations-api/build-custom-template.png" alt-text="Screenshot to build template in the editor.":::

+3. Paste the resource manager template below into the editor and then click **Save**. This template defines the DCR and contains the transformation query. You don't need to modify this template since it will collect values for its parameters.

+ :::image type="content" source="media/tutorial-workspace-transformations-api/edit-template.png" lightbox="media/tutorial-workspace-transformations-api/edit-template.png" alt-text="Screenshot to edit resource manager template.":::

+ ```json

+ {

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

+     "contentVersion": "1.0.0.0",

+     "parameters": {

+         "dataCollectionRuleName": {

+             "type": "string",

+             "metadata": {

+                 "description": "Specifies the name of the Data Collection Rule to create."

+             }

+         },

+         "location": {

+             "type": "string",

+             "defaultValue": "westus2",

+             "allowedValues": [

+                 "westus2",

+ "eastus2",

+                 "eastus2euap"

+             ],

+             "metadata": {

+                 "description": "Specifies the location in which to create the Data Collection Rule."

+             }

+         },

+         "workspaceResourceId": {

+             "type": "string",

+             "metadata": {

+                 "description": "Specifies the Azure resource ID of the Log Analytics workspace to use."

+             }

+         }

+     },

+     "resources": [

+         {

+             "type": "Microsoft.Insights/dataCollectionRules",

+             "name": "[parameters('dataCollectionRuleName')]",

+             "location": "[parameters('location')]",

+             "apiVersion": "2021-09-01-preview",

+             "kind": "WorkspaceTransforms",

+             "properties": {

+ "destinations": {

+ "logAnalytics": [

+ {

+ "workspaceResourceId": "[parameters('workspaceResourceId')]",

+ "name": "clv2ws1"

+ }

+ ]

+ },

+ "dataFlows": [

+ {

+ "streams": [

+ "Microsoft-Table-LAQueryLogs"

+ ],

+ "destinations": [

+ "clv2ws1"

+ ],

+ "transformKql": "source |where QueryText !contains 'LAQueryLogs' | extend Context = parse_json(RequestContext) | extend Resources_CF = tostring(Context['workspaces']) |extend RequestContext = ''"

+ }

+ ]

+             }

+         }

+     ],

+     "outputs": {

+         "dataCollectionRuleId": {

+             "type": "string",

+             "value": "[resourceId('Microsoft.Insights/dataCollectionRules', parameters('dataCollectionRuleName'))]"

+         }

+     }

+ }

+ ```

+4. On the **Custom deployment** screen, specify a **Subscription** and **Resource group** to store the data collection rule and then provide values defined in the template. This includes a **Name** for the data collection rule and the **Workspace Resource ID** that you collected in a previous step. The **Location** should be the same location as the workspace. The **Region** will already be populated and is used for the location of the data collection rule.

+ :::image type="content" source="media/tutorial-workspace-transformations-api/custom-deployment-values.png" lightbox="media/tutorial-workspace-transformations-api/custom-deployment-values.png" alt-text="Screenshot to edit custom deployment values.":::

+5. Click **Review + create** and then **Create** when you review the details.

+6. When the deployment is complete, expand the **Deployment details** box and click on your data collection rule to view its details. Click **JSON View**.

+ :::image type="content" source="media/tutorial-workspace-transformations-api/data-collection-rule-details.png" lightbox="media/tutorial-workspace-transformations-api/data-collection-rule-details.png" alt-text="Screenshot for data collection rule details.":::

+7. Copy the **Resource ID** for the data collection rule. You'll use this in the next step.

+ :::image type="content" source="media/tutorial-workspace-transformations-api/data-collection-rule-json-view.png" lightbox="media/tutorial-workspace-transformations-api/data-collection-rule-json-view.png" alt-text="Screenshot for data collection rule JSON view.":::

+## Link workspace to DCR

+The final step to enable the transformation is to link the DCR to the workspace.

+> [!IMPORTANT]

+> A workspace can only be connected to a single DCR, and the linked DCR must contain this workspace as a destination.

+Use the **Workspaces - Update** API to configure the table with the PowerShell code below.

+1. Click the **Cloud shell** button to open cloud shell again. Copy the following PowerShell code and replace the parameters with values for your workspace and DCR.

+ ```PowerShell

+ $defaultDcrParams = @'

+ {

+ "properties": {

+ "defaultDataCollectionRuleResourceId": "/subscriptions/{subscription}/resourceGroups/{resourcegroup}/providers/Microsoft.Insights/dataCollectionRules/{DCR}"

+ }

+ }

+ '@

+ Invoke-AzRestMethod -Path "/subscriptions/{subscription}/resourcegroups/{resourcegroup}/providers/microsoft.operationalinsights/workspaces/{workspace}?api-version=2021-12-01-preview" -Method PATCH -payload $defaultDcrParams

+ ```

+2. Paste the code into the cloud shell prompt to run it.

+ :::image type="content" source="media/tutorial-workspace-transformations-api/cloud-shell-script-link-workspace.png" lightbox="media/tutorial-workspace-transformations-api/cloud-shell-script-link-workspace.png" alt-text="Screenshot of script to link workspace to DCR.":::

+## Test transformation

+Allow about 30 minutes for the transformation to take effect, and you can then test it by running a query against the table. Only data sent to the table after the transformation was applied will be affected.

+For this tutorial, run some sample queries to send data to the `LAQueryLogs` table. Include some queries against `LAQueryLogs` so you can verify that the transformation filters these records. Notice that the output has the new `Workspace_CF` column, and there are no records for `LAQueryLogs`.

+## Troubleshooting

+This section describes different error conditions you may receive and how to correct them.

+### IntelliSense in Log Analytics not recognizing new columns in the table

+The cache that drives IntelliSense may take up to 24 hours to update.

+### Transformation on a dynamic column isn't working

+There is currently a known issue affecting dynamic columns. A temporary workaround is to explicitly parse dynamic column data using `parse_json()` prior to performing any operations against them.

+## Next steps

+- [Read more about transformations](../essentials/data-collection-transformations.md)

+- [See which tables support workspace transformations](tables-feature-support.md)

+- [Learn more about writing transformation queries](../essentials/data-collection-transformations-structure.md)

+ Title: Tutorial - Add workspace transformation to Azure Monitor Logs using Azure portal

+description: Describes how to add a custom transformation to data flowing through Azure Monitor Logs using the Azure portal.

+# Tutorial: Add transformation in workspace data collection rule using the Azure portal (preview)

+This tutorial walks you through configuration of a sample [transformation in a workspace data collection rule](../essentials/data-collection-transformations.md) using the Azure portal. [Transformations](../essentials/data-collection-transformations.md) in Azure Monitor allow you to filter or modify incoming data before it's sent to its destination. Workspace transformations provide support for [ingestion-time transformations](../essentials/data-collection-transformations.md) for workflows that don't yet use the [Azure Monitor data ingestion pipeline](../essentials/data-collection.md).

+Workspace transformations are stored together in a single [data collection rule (DCR)](../essentials/data-collection-rule-overview.md) for the workspace, called the workspace DCR. Each transformation is associated with a particular table. The transformation will be applied to all data sent to this table from any workflow not using a DCR.

+> [!NOTE]

+> This tutorial uses the Azure portal to configure a workspace transformation. See [Tutorial: Add transformation in workspace data collection rule to Azure Monitor using resource manager templates (preview)](tutorial-workspace-transformations-api.md) for the same tutorial using resource manager templates and REST API.

+In this tutorial, you learn to:

+> [!div class="checklist"]

+> * Configure [workspace transformation](../essentials/data-collection-transformations.md#workspace-transformation-dcr) for a table in a Log Analytics workspace.

+> * Write a log query for a workspace transformation.

+## Prerequisites

+To complete this tutorial, you need the following:

+- Log Analytics workspace where you have at least [contributor rights](manage-access.md#azure-rbac).

+- [Permissions to create data collection rule (DCR) objects](../essentials/data-collection-rule-overview.md#permissions) in the workspace.

+- The table must already have some data.

+- The table can't be linked to the [workspace transformation DCR](../essentials/data-collection-transformations.md#workspace-transformation-dcr).

+## Overview of tutorial

+In this tutorial, you'll reduce the storage requirement for the `LAQueryLogs` table by filtering out certain records. You'll also remove the contents of a column while parsing the column data to store a piece of data in a custom column. The [LAQueryLogs table](query-audit.md#audit-data) is created when you enable [log query auditing](query-audit.md) in a workspace. You can use this same basic process to create a transformation for any [supported table](tables-feature-support.md) in a Log Analytics workspace.

+This tutorial will use the Azure portal which provides a wizard to walk you through the process of creating an ingestion-time transformation. The following actions are performed for you when you complete this wizard:

+- Updates the table schema with any additional columns from the query.

+- Creates a `WorkspaceTransforms` data collection rule (DCR) and links it to the workspace if a default DCR isn't already linked to the workspace.

+- Creates an ingestion-time transformation and adds it to the DCR.

+## Enable query audit logs

+You need to enable [query auditing](query-audit.md) for your workspace to create the `LAQueryLogs` table that you'll be working with. This is not required for all ingestion time transformations. It's just to generate the sample data that we'll be working with.

+1. From the **Log Analytics workspaces** menu in the Azure portal, select **Diagnostic settings** and then **Add diagnostic setting**.

+ :::image type="content" source="media/tutorial-workspace-transformations-portal/diagnostic-settings.png" lightbox="media/tutorial-workspace-transformations-portal/diagnostic-settings.png" alt-text="Screenshot of diagnostic settings.":::

+2. Provide a name for the diagnostic setting and select the workspace so that the auditing data is stored in the same workspace. Select the **Audit** category and then click **Save** to save the diagnostic setting and close the diagnostic setting page.

+ :::image type="content" source="media/tutorial-workspace-transformations-portal/new-diagnostic-setting.png" lightbox="media/tutorial-workspace-transformations-portal/new-diagnostic-setting.png" alt-text="Screenshot of new diagnostic setting.":::

+3. Select **Logs** and then run some queries to populate `LAQueryLogs` with some data. These queries don't need to return data to be added to the audit log.

+ :::image type="content" source="media/tutorial-workspace-transformations-portal/sample-queries.png" lightbox="media/tutorial-workspace-transformations-portal/sample-queries.png" alt-text="Screenshot of sample log queries.":::

+## Add transformation to the table

+Now that the table's created, you can create the transformation for it.

+1. From the **Log Analytics workspaces** menu in the Azure portal, select **Tables (preview)**. Locate the `LAQueryLogs` table and select **Create transformation**.

+ :::image type="content" source="media/tutorial-workspace-transformations-portal/create-transformation.png" lightbox="media/tutorial-workspace-transformations-portal/create-transformation.png" alt-text="Screenshot of creating a new transformation.":::

+2. Since this is the first transformation in the workspace, you need to create a [workspace transformation DCR](../essentials/data-collection-transformations.md#workspace-transformation-dcr). If you create transformations for other tables in the same workspace, they will be stored in this same DCR. Click **Create a new data collection rule**. The **Subscription** and **Resource group** will already be populated for the workspace. Provide a name for the DCR and click **Done**.

+ :::image type="content" source="media/tutorial-workspace-transformations-portal/new-data-collection-rule.png" lightbox="media/tutorial-workspace-transformations-portal/new-data-collection-rule.png" alt-text="Screenshot of creating a new data collection rule.":::

+3. Click **Next** to view sample data from the table. As you define the transformation, the result will be applied to the sample data allowing you to evaluate the results before applying it to actual data. Click **Transformation editor** to define the transformation.

+ :::image type="content" source="media/tutorial-workspace-transformations-portal/sample-data.png" lightbox="media/tutorial-workspace-transformations-portal/sample-data.png" alt-text="Screenshot of sample data from the log table.":::

+4. In the transformation editor, you can see the transformation that will be applied to the data prior to its ingestion into the table. The incoming data is represented by a virtual table named `source`, which has the same set of columns as the destination table itself. The transformation initially contains a simple query returning the `source` table with no changes.

+5. Modify the query to the following:

+ ``` kusto

+ source

+ | where QueryText !contains 'LAQueryLogs'

+ | extend Context = parse_json(RequestContext)

+ | extend Workspace_CF = tostring(Context['workspaces'][0])

+ | project-away RequestContext, Context

+ ```

+ This makes the following changes:

+ - Drop rows related to querying the `LAQueryLogs` table itself to save space since these log entries aren't useful.

+ - Add a column for the name of the workspace that was queried.

+ - Remove data from the `RequestContext` column to save space.

+ > [!Note]

+ > Using the Azure portal, the output of the transformation will initiate changes to the table schema if required. Columns will be added to match the transformation output if they don't already exist. Make sure that your output doesn't contain any additional columns that you don't want added to the table. If the output does not include columns that are already in the table, those columns will not be removed, but data will not be added.

+ >

+ > Any custom columns added to a built-in table must end in *_CF*. Columns added to a custom table (a table with a name that ends in *_CL*) does not need to have this suffix.

+6. Copy the query into the transformation editor and click **Run** to view results from the sample data. You can verify that the new `Workspace_CF` column is in the query.

+ :::image type="content" source="media/tutorial-workspace-transformations-portal/transformation-editor.png" lightbox="media/tutorial-workspace-transformations-portal/transformation-editor.png" alt-text="Screenshot of transformation editor.":::

+7. Click **Apply** to save the transformation and then **Next** to review the configuration. Click **Create** to update the data collection rule with the new transformation.

+ :::image type="content" source="media/tutorial-workspace-transformations-portal/save-transformation.png" lightbox="media/tutorial-workspace-transformations-portal/save-transformation.png" alt-text="Screenshot of saving transformation.":::

+## Test transformation

+Allow about 30 minutes for the transformation to take effect and then test it by running a query against the table. Only data sent to the table after the transformation was applied will be affected.

+For this tutorial, run some sample queries to send data to the `LAQueryLogs` table. Include some queries against `LAQueryLogs` so you can verify that the transformation filters these records. Notice that the output has the new `Workspace_CF` column, and there are no records for `LAQueryLogs`.

+## Troubleshooting

+This section describes different error conditions you may receive and how to correct them.

+### IntelliSense in Log Analytics not recognizing new columns in the table

+The cache that drives IntelliSense may take up to 24 hours to update.

+### Transformation on a dynamic column isn't working

+There is currently a known issue affecting dynamic columns. A temporary workaround is to explicitly parse dynamic column data using `parse_json()` prior to performing any operations against them.

+## Next steps

+- [Read more about transformations](../essentials/data-collection-transformations.md)

+- [See which tables support workspace transformations](tables-feature-support.md)

+- [Learn more about writing transformation queries](../essentials/data-collection-transformations-structure.md)

+- Central workspace. The service provider creates a workspace in its tenant and use a script that utilizes the [Query API](api/overview.md) with the [logs ingestion API](logs-ingestion-api-overview.md) to bring the data from the tenant workspaces to this central location. Another option is to use [Azure Logic Apps](../../logic-apps/logic-apps-overview.md) to copy data to the central workspace.

+ Title: Observability data in Azure Monitor

+description: Describes the

+documentationcenter: ''

+ na

+# Observability data in Azure Monitor

+Enabling observability across today's complex computing environments running distributed applications that rely on both cloud and on-premises services, requires collection of operational data from every layer and every component of the distributed system. You need to be able to perform deep insights on this data and consolidate it into a single pane of glass with different perspectives to support the multitude of stakeholders in your organization.

+[Azure Monitor](overview.md) collects and aggregates data from a variety of sources into a common data platform where it can be used for analysis, visualization, and alerting. It provides a consistent experience on top of data from multiple sources, which gives you deep insights across all your monitored resources and even with data from other services that store their data in Azure Monitor.

+## Pillars of observability

+Metrics, logs, and distributed traces are commonly referred to as the three pillars of observability. These are the different kinds of data that a monitoring tool must collect and analyze to provide sufficient observability of a monitored system. Observability can be achieved by correlating data from multiple pillars and aggregating data across the entire set of resources being monitored. Because Azure Monitor stores data from multiple sources together, the data can be correlated and analyzed using a common set of tools. It also correlates data across multiple Azure subscriptions and tenants, in addition to hosting data for other services.

+Azure resources generate a significant amount of monitoring data. Azure Monitor consolidates this data along with monitoring data from other sources into either a Metrics or Logs platform. Each is optimized for particular monitoring scenarios, and each supports different features in Azure Monitor. Features such as data analysis, visualizations, or alerting require you to understand the differences so that you can implement your required scenario in the most efficient and cost effective manner. Insights in Azure Monitor such as [Application Insights](app/app-insights-overview.md) or [VM insights](vm/vminsights-overview.md) have analysis tools that allow you to focus on the particular monitoring scenario without having to understand the differences between the two types of data.

+## Metrics

+[Metrics](essentials/data-platform-metrics.md) are numerical values that describe some aspect of a system at a particular point in time. They are collected at regular intervals and are identified with a timestamp, a name, a value, and one or more defining labels. Metrics can be aggregated using a variety of algorithms, compared to other metrics, and analyzed for trends over time.

+Metrics in Azure Monitor are stored in a time-series database which is optimized for analyzing time-stamped data. This makes metrics particularly suited for alerting and fast detection of issues. They can tell you how your system is performing but typically need to be combined with logs to identify the root cause of issues.

+Metrics are available for interactive analysis in the Azure portal with [Azure Metrics Explorer](essentials/metrics-getting-started.md). They can be added to an [Azure dashboard](app/tutorial-app-dashboards.md) for visualization in combination with other data and used for near-real time [alerting](alerts/alerts-metric.md).

+Read more about Azure Monitor Metrics including their sources of data in [Metrics in Azure Monitor](essentials/data-platform-metrics.md).

+## Logs

+[Logs](logs/data-platform-logs.md) are events that occurred within the system. They can contain different kinds of data and may be structured or free form text with a timestamp. They may be created sporadically as events in the environment generate log entries, and a system under heavy load will typically generate more log volume.

+Logs in Azure Monitor are stored in a Log Analytics workspace that's based on [Azure Data Explorer](/azure/data-explorer/) which provides a powerful analysis engine and [rich query language](/azure/kusto/query/). Logs typically provide enough information to provide complete context of the issue being identified and are valuable for identifying root case of issues.

+> [!NOTE]

+> It's important to distinguish between Azure Monitor Logs and sources of log data in Azure. For example, subscription level events in Azure are written to an [activity log](essentials/platform-logs-overview.md) that you can view from the Azure Monitor menu. Most resources will write operational information to a [resource log](essentials/platform-logs-overview.md) that you can forward to different locations. Azure Monitor Logs is a log data platform that collects activity logs and resource logs along with other monitoring data to provide deep analysis across your entire set of resources.

+ You can work with [log queries](logs/log-query-overview.md) interactively with [Log Analytics](logs/log-query-overview.md) in the Azure portal or add the results to an [Azure dashboard](app/tutorial-app-dashboards.md) for visualization in combination with other data. You can also create [log alerts](alerts/alerts-log.md) which will trigger an alert based on the results of a schedule query.

+Read more about Azure Monitor Logs including their sources of data in [Logs in Azure Monitor](logs/data-platform-logs.md).

+## Distributed traces

+Traces are series of related events that follow a user request through a distributed system. They can be used to determine behavior of application code and the performance of different transactions. While logs will often be created by individual components of a distributed system, a trace measures the operation and performance of your application across the entire set of components.

+Distributed tracing in Azure Monitor is enabled with the [Application Insights SDK](app/distributed-tracing.md), and trace data is stored with other application log data collected by Application Insights. This makes it available to the same analysis tools as other log data including log queries, dashboards, and alerts.

+Read more about distributed tracing at [What is Distributed Tracing?](app/distributed-tracing.md).

+## Next steps

+- Read more about [Metrics in Azure Monitor](essentials/data-platform-metrics.md).

+- Read more about [Logs in Azure Monitor](logs/data-platform-logs.md).

+- Learn about the [monitoring data available](data-sources.md) for different resources in Azure.

+ Title: Azure Monitor overview

+The following diagram gives a high-level view of Azure Monitor. At the center of the diagram are the data stores for metrics and logs, which are the two fundamental types of data used by Azure Monitor. On the left are the [sources of monitoring data](data-sources.md) that populate these [data stores](data-platform.md). On the right are the different functions that Azure Monitor performs with this collected data. This includes such actions as analysis, alerting, and streaming to external systems.

+## Observability data in Azure Monitor

+Metrics, logs, and distributed traces are commonly referred to as the three pillars of observability. These are the different kinds of data that a monitoring tool must collect and analyze to provide sufficient observability of a monitored system. Observability can be achieved by correlating data from multiple pillars and aggregating data across the entire set of resources being monitored. Because Azure Monitor stores data from multiple sources together, the data can be correlated and analyzed using a common set of tools. It also correlates data across multiple Azure subscriptions and tenants, in addition to hosting data for other services.

+Azure resources generate a significant amount of monitoring data. Azure Monitor consolidates this data along with monitoring data from other sources into either a Metrics or Logs platform. Each is optimized for particular monitoring scenarios, and each supports different features in Azure Monitor. Features such as data analysis, visualizations, or alerting require you to understand the differences so that you can implement your required scenario in the most efficient and cost effective manner. Insights in Azure Monitor such as [Application Insights](app/app-insights-overview.md) or [Container insights](containers/container-insights-overview.md) have analysis tools that allow you to focus on the particular monitoring scenario without having to understand the differences between the two types of data.

+| Pillar | Description |

+|:|:|

+| Metrics | Metrics are numerical values that describe some aspect of a system at a particular point in time. They are collected at regular intervals and are identified with a timestamp, a name, a value, and one or more defining labels. Metrics can be aggregated using a variety of algorithms, compared to other metrics, and analyzed for trends over time.<br><br>Metrics in Azure Monitor are stored in a time-series database which is optimized for analyzing time-stamped data. For more information, see [Azure Monitor Metrics](essentials/data-platform-metrics.md). |

+| Logs | [Logs](logs/data-platform-logs.md) are events that occurred within the system. They can contain different kinds of data and may be structured or free form text with a timestamp. They may be created sporadically as events in the environment generate log entries, and a system under heavy load will typically generate more log volume.<br><br>Logs in Azure Monitor are stored in a Log Analytics workspace that's based on [Azure Data Explorer](/azure/data-explorer/) which provides a powerful analysis engine and [rich query language](/azure/kusto/query/). For more information, see [Azure Monitor Logs](logs/data-platform-logs.md). |

+| Distributed traces | Traces are series of related events that follow a user request through a distributed system. They can be used to determine behavior of application code and the performance of different transactions. While logs will often be created by individual components of a distributed system, a trace measures the operation and performance of your application across the entire set of components.<br><br>Distributed tracing in Azure Monitor is enabled with the [Application Insights SDK](app/distributed-tracing.md), and trace data is stored with other application log data collected by Application Insights and stored in Azure Monitor Logs. For more information, see [What is Distributed Tracing?](app/distributed-tracing.md). |

+> [!NOTE]

+> It's important to distinguish between Azure Monitor Logs and sources of log data in Azure. For example, subscription level events in Azure are written to an [activity log](essentials/platform-logs-overview.md) that you can view from the Azure Monitor menu. Most resources will write operational information to a [resource log](essentials/platform-logs-overview.md) that you can forward to different locations. Azure Monitor Logs is a log data platform that collects activity logs and resource logs along with other monitoring data to provide deep analysis across your entire set of resources.

+* [Data sources](data-sources.md) for how the different components of your application send telemetry.

+ Title: Enable Profiler for ASP.NET Core web applications hosted in Linux on App Services | Microsoft Docs

+description: Learn how to enable Profiler on your ASP.NET Core web application hosted in Linux on App Services.

+# Enable Profiler for ASP.NET Core web applications hosted in Linux on App Services

+Using Profiler, you can track how much time is spent in each method of your live ASP.NET Core web apps that are hosted in Linux on Azure App Service. While this guide focuses on web apps hosted in Linux, you can experiment using Linux, Windows, and Mac development environments.

+In this guide, you'll:

+> [!div class="checklist"]

+> - Set up and deploy an ASP.NET Core web application hosted on Linux.

+> - Add Application Insights Profiler to the ASP.NET Core web application.

+

+- Install the [latest and greatest .NET Core SDK](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).

+1. Open a Command Prompt window on your machine.

+1. In your preferred code editor, enable Application Insights and Profiler in `Program.cs`:

+1. In the Azure portal, create a web app environment by using App Service on Linux:

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

+1. Go to your new web app resource and select **Deployment Center** > **FTPS credentials** to create the deployment credentials. Make note of your credentials to use later.

+ :::image type="content" source="./media/profiler-aspnetcore-linux/credentials.png" alt-text="Screenshot of creating the deployment credentials.":::

+1. Click **Save**.

+1. Select the **Settings** tab.

+1. In the drop-down, select **Local Git** to set up a local Git repository in the web app.

+ :::image type="content" source="./media/profiler-aspnetcore-linux/deployment-options.png" alt-text="Screenshot of view deployment options in a drop-down.":::

+1. Click **Save** to create a Git repository with a Git Clone Uri.

+ :::image type="content" source="./media/profiler-aspnetcore-linux/local-git-repo.png" alt-text="Screenshot of setting up the local Git repository.":::

+ For more deployment options, see [App Service documentation](../../app-service/deploy-best-practices.md).

+## Add Application Insights to monitor your web app

+You can add Application Insights to your web app either via:

+- The Enablement blade in the Azure portal,

+- The Configuration blade in the Azure portal, or

+- Manually adding to your web app settings.

+# [Enablement blade](#tab/enablement)

+1. In your web app on the Azure portal, select **Application Insights** in the left side menu.

+1. Click **Turn on Application Insights**.

+ :::image type="content" source="./media/profiler-aspnetcore-linux/turn-on-app-insights.png" alt-text="Screenshot of turning on Application Insights.":::

+1. Under **Application Insights**, select **Enable**.

+ :::image type="content" source="./media/profiler-aspnetcore-linux/enable-app-insights.png" alt-text="Screenshot of enabling Application Insights.":::

+1. Under **Link to an Application Insights resource**, either create a new resource or select an existing resource. For this example, we'll create a new resource.

+ :::image type="content" source="./media/profiler-aspnetcore-linux/link-app-insights.png" alt-text="Screenshot of linking your Application Insights to a new or existing resource.":::

+1. Click **Apply** > **Yes** to apply and confirm.

+# [Configuration blade](#tab/config)

+1. [Create an Application Insights resource](../app/create-workspace-resource.md) in the same Azure subscription as your App Service.

+1. Navigate to the Application Insights resource.

+1. Copy the **Instrumentation Key** (iKey).

+1. In your web app on the Azure portal, select **Configuration** in the left side menu.

+1. Click **New application setting**.

+ :::image type="content" source="./media/profiler-aspnetcore-linux/new-setting-configuration.png" alt-text="Screenshot of adding new application setting in the configuration blade.":::

+1. Add the following settings in the **Add/Edit application setting** pane, using your saved iKey:

+ | Name | Value |

+ | - | -- |

+ | APPINSIGHTS_INSTRUMENTATIONKEY | [YOUR_APPINSIGHTS_KEY] |

+ :::image type="content" source="./media/profiler-aspnetcore-linux/add-ikey-settings.png" alt-text="Screenshot of adding iKey to the settings pane.":::

+1. Click **OK**.

+ :::image type="content" source="./media/profiler-aspnetcore-linux/save-app-insights-key.png" alt-text="Screenshot of saving the application insights key settings.":::

+1. Click **Save**.

+# [Web app settings](#tab/appsettings)

+1. [Create an Application Insights resource](../app/create-workspace-resource.md) in the same Azure subscription as your App Service.

+1. Navigate to the Application Insights resource.

+1. Copy the **Instrumentation Key** (iKey).

+1. In your preferred code editor, navigate to your ASP.NET Core project's `appsettings.json` file.

+1. Add the following and insert your copied iKey:

+ ```json

+ "ApplicationInsights":

+ {

+ "InstrumentationKey": "<your-instrumentation-key>"

+ }

+ ```

+1. Save `appsettings.json` to apply the settings change.

+## Next steps

+Learn how to...

+> [!div class="nextstepaction"]

+> [Generate load and view Profiler traces](./profiler-data.md)

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

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

+## Logs ingestion API

+1. [Add a parameters](workbooks-create-workbook.md#add-a-parameter-to-a-workbook), make it a [time range parameter](workbooks-time.md), and name it **TimeRange**.

+1. [Create a new empty workbook](workbooks-create-workbook.md) and [add a parameter component](workbooks-create-workbook.md#add-a-parameter-to-a-workbook).

+ Title: Create an Azure workbook

+description: Learn how to create a workbook in Azure Workbooks.

+# Create an Azure workbook

+This article describes how to create a new workbook and how to add elements to your Azure workbook.

+## Create a new workbook

+To create a new workbook:

+1. On the **Azure Workbooks** page, select an empty template or select **New**.

+ - [Text](#add-text)

+ - [Queries](#add-queries)

+ - [Parameters](#add-parameters)

+ - [Metric charts](#add-metric-charts)

+ - [Links](#add-links)

+ - [Groups](#add-groups)

+## Add text

+You can include text blocks in your workbooks. For example, the text can be human analysis of the telemetry, information to help users interpret the data, and section headings.

+ :::image type="content" source="media/workbooks-create-workbook/workbooks-text-example.png" alt-text="Screenshot that shows adding text to a workbook.":::

+Text is added through a Markdown control that you use to add your content. You can use the full formatting capabilities of Markdown like different heading and font styles, hyperlinks, and tables. By using Markdown, you can create rich Word- or portal-like reports or analytic narratives. Text can contain parameter values in the Markdown text. Those parameter references are updated as the parameters change.

+Edit mode:

+ :::image type="content" source="media/workbooks-create-workbook/workbooks-text-control-edit-mode.png" alt-text="Screenshot that shows adding text to a workbook in edit mode.":::

+Preview mode:

+ :::image type="content" source="media/workbooks-create-workbook/workbooks-text-control-edit-mode-preview.png" alt-text="Screenshot that shows adding text to a workbook in preview mode.":::

+### Add text to a workbook

+1. Make sure you're in edit mode by selecting **Edit**.

+1. Add text by doing one of these steps:

+ * Select **Add** > **Add text** below an existing element or at the bottom of the workbook.

+ * Select the ellipsis (...) to the right of the **Edit** button next to one of the elements in the workbook. Then select **Add** > **Add text**.

+1. Enter Markdown text in the editor field.

+1. Use the **Text Style** option to switch between plain Markdown and Markdown wrapped with the Azure portal's standard info, warning, success, and error styling.

+ > Use this [Markdown cheat sheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) to see the different formatting options.

+1. Use the **Preview** tab to see how your content will look. The preview shows the content inside a scrollable area to limit its size. At runtime, the Markdown content expands to fill whatever space it needs, without a scrollbar.

+These text styles are available.

+|plain| No formatting is applied. |

+|info| The portal's info style, with an `ℹ` or similar icon and blue background. |

+|error| The portal's error style, with an `❌` or similar icon and red background. |

+|success| The portal's success style, with a `Γ£ö` or similar icon and green background. |

+|upsell| The portal's upsell style, with a `🚀` or similar icon and purple background. |

+|warning| The portal's warning style, with a `ΓÜá` or similar icon and blue background. |

+You can also choose a text parameter as the source of the style. The parameter value must be one of the preceding text values. The absence of a value or any unrecognized value is treated as plain style.

+Info style example:

+ :::image type="content" source="media/workbooks-create-workbook/workbooks-text-control-edit-mode-preview.png" alt-text="Screenshot that shows adding text to a workbook in preview mode showing info style.":::

+Warning style example:

+ :::image type="content" source="media/workbooks-create-workbook/workbooks-text-example-warning.png" alt-text="Screenshot that shows a text visualization in warning style.":::

+## Add queries

+You can query any of the supported workbook [data sources](workbooks-data-sources.md).

+### Add a query to a workbook

+1. Make sure you're in edit mode by selecting **Edit**.

+1. Add a query by doing one of these steps:

+ - Select **Add** > **Add query** below an existing element or at the bottom of the workbook.

+ - Select the ellipsis (...) to the right of the **Edit** button next to one of the elements in the workbook. Then select **Add** > **Add query**.

+1. In the query section, enter your query, or select from a list of sample queries by selecting **Samples**. Then edit the query to your liking.

+1. When you're sure you have the query you want in your workbook, select **Done Editing**.

+## Add parameters

+This section discusses how to add parameters.

+### Best practices for using resource-centric log queries

+This video shows you how to use resource-level logs queries in Azure Workbooks. It also has tips and tricks on how to enable advanced scenarios and improve performance.

+#### Use a dynamic resource type parameter

+Dynamic resource type parameters use dynamic scopes for more efficient querying. The following snippet uses this heuristic:

+1. **Individual resources**: If the count of selected resource is less than or equal to 5

+1. **Resource groups**: If the number of resources is over 5 but the number of resource groups the resources belong to is less than or equal to 3

+1. **Subscriptions**: Otherwise

+#### Use a static resource scope for querying multiple resource types

+#### Use resource parameters grouped by resource type

+## Add a parameter

+You can control how your parameter controls are presented to consumers with workbooks. Examples include text box versus dropdown list, single- versus multi-select, or values from text, JSON, KQL, or Azure Resource Graph.

+### Add a parameter to a workbook

+1. Make sure you're in edit mode by selecting **Edit**.

+1. Add a parameter by doing one of these steps:

+ - Select **Add** > **Add parameter** below an existing element or at the bottom of the workbook.

+ - Select the ellipsis (...) to the right of the **Edit** button next to one of the elements in the workbook. Then select **Add** > **Add parameter**.

+1. In the new parameter pane that appears, enter values for these fields:

+ - **Parameter name**: Parameter names can't include spaces or special characters.

+ - **Display name**: Display names can include spaces, special characters, and emojis.

+ - **Parameter type**:

+ - **Required**:

+1. Select **Done Editing**.

+ :::image type="content" source="media/workbooks-parameters/workbooks-time-settings.png" alt-text="Screenshot that shows the creation of a time range parameter.":::

+## Add metric charts

+Most Azure resources emit metric data about state and health, such as CPU utilization, storage availability, count of database transactions, and failing app requests. You can create visualizations of this metric data as time-series charts in workbooks.

+The following example shows the number of transactions in a storage account over the prior hour. This information allows you to see the transaction trend and look for anomalies in behavior.

+ :::image type="content" source="media/workbooks-create-workbook/workbooks-metric-chart-storage-area.png" alt-text="Screenshot that shows a metric area chart for storage transactions in a workbook.":::

+### Add a metric chart to a workbook

+1. Make sure you're in edit mode by selecting **Edit**.

+1. Add a metric chart by doing one of these steps:

+ - Select **Add** > **Add metric** below an existing element or at the bottom of the workbook.

+ - Select the ellipsis (...) to the right of the **Edit** button next to one of the elements in the workbook. Then select **Add** > **Add metric**.

+1. Set parameters such as time range, split by, visualization, size, and color palette, if needed.

+Example of a metric chart in edit mode:

+| Parameter | Description | Examples |

+| Resource type| The resource type to target. | Storage or Virtual Machine |

+| Resources| A set of resources to get the metrics value from. | MyStorage1 |

+| Namespace | The namespace with the metric. | Storage > Blob |

+| Metric| The metric to visualize. | Storage > Blob > Transactions |

+| Aggregation | The aggregation function to apply to the metric. | Sum, count, average |

+| Time range | The time window to view the metric in. | Last hour, last 24 hours |

+| Visualization | The visualization to use. | Area, bar, line, scatter, grid |

+| Split by| Optionally split the metric on a dimension. | Transactions by geo type |

+| Size | The vertical size of the control. | Small, medium, or large |

+| Color palette | The color palette to use in the chart. It's ignored if the **Split by** parameter is used. | Blue, green, red |

+Examples of metric charts are shown.

+#### Transactions split by API name as a line chart

+ :::image type="content" source="media/workbooks-create-workbook/workbooks-metric-chart-storage-split-line.png" alt-text="Screenshot that shows a metric line chart for storage transactions split by API name.":::

+#### Transactions split by response type as a large bar chart

+ :::image type="content" source="media/workbooks-create-workbook/workbooks-metric-chart-storage-bar-large.png" alt-text="Screenshot that shows a large metric bar chart for storage transactions split by response type.":::

+#### Average latency as a scatter chart

+ :::image type="content" source="media/workbooks-create-workbook/workbooks-metric-chart-storage-scatter.png" alt-text="Screenshot that shows a metric scatter chart for storage latency.":::

+## Add links

+You can use links to create links to other views, workbooks, and other components inside a workbook, or to create tabbed views within a workbook. The links can be styled as hyperlinks, buttons, and tabs.

+You can apply styles to the link element itself and to individual links.

+#### Link element styles

+|Bullet List | :::image type="content" source="media/workbooks-create-workbook/workbooks-link-style-bullet.png" alt-text="Screenshot that shows a bullet-style workbook link."::: | The default, links, appears as a bulleted list of links, one on each line. The **Text before link** and **Text after link** fields can be used to add more text before or after the link components. |

+|List |:::image type="content" source="media/workbooks-create-workbook/workbooks-link-style-list.png" alt-text="Screenshot that shows a list-style workbook link."::: | Links appear as a list of links, with no bullets. |

+|Paragraph | :::image type="content" source="media/workbooks-create-workbook/workbooks-link-style-paragraph.png" alt-text="Screenshot that shows a paragraph-style workbook link."::: |Links appear as a paragraph of links, wrapped like a paragraph of text. |

+|Navigation | :::image type="content" source="media/workbooks-create-workbook/workbooks-link-style-navigation.png" alt-text="Screenshot that shows a navigation-style workbook link."::: | Links appear as links with vertical dividers, or pipes, between each link. |

+|Tabs | :::image type="content" source="media/workbooks-create-workbook/workbooks-link-style-tabs.png" alt-text="Screenshot that shows a tabs-style workbook link."::: |Links appear as tabs. Each link appears as a tab. No link styling options apply to individual links. To configure tabs, see the [Use tabs](#use-tabs) section. |

+|Toolbar | :::image type="content" source="media/workbooks-create-workbook/workbooks-link-style-toolbar.png" alt-text="Screenshot that shows a toolbar-style workbook link."::: | Links appear as an Azure portal-styled toolbar, with icons and text. Each link appears as a toolbar button. To configure toolbars, see the [Use toolbars](#use-toolbars) section. |

+#### Link styles

+| Link | By default, links appear as a hyperlink. URL links can only be link style. |

+| Button (primary) | The link appears as a "primary" button in the portal, usually a blue color. |

+| Button (secondary) | The links appear as a "secondary" button in the portal, usually a "transparent" color, a white button in light themes, and a dark gray button in dark themes. |

+If required parameters are used in button text, tooltip text, or value fields, and the required parameter is unset when you use buttons, the button is disabled. You can use this capability, for example, to disable buttons when no value is selected in another parameter or control.

+Links can use all the link actions available in [link actions](workbooks-link-actions.md), and they have two more available actions.

+|Set a parameter value | A parameter can be set to a value when you select a link, button, or tab. Tabs are often configured to set a parameter to a value, which hides and shows other parts of the workbook based on that value.|

+|Scroll to a step| When you select a link, the workbook moves focus and scrolls to make another component visible. This action can be used to create a "table of contents" or a "go back to the top"-style experience. |

+### Use tabs

+Most of the time, tab links are combined with the **Set a parameter value** action. This example shows the links step configured to create two tabs, where selecting either tab sets a **selectedTab** parameter to a different value. The example also shows a third tab being edited to show the parameter name and parameter value placeholders.

+ :::image type="content" source="media/workbooks-create-workbook/workbooks-creating-tabs.png" alt-text="Screenshot that shows creating tabs in workbooks.":::

+You can then add other components in the workbook that are conditionally visible if the **selectedTab** parameter value is **1** by using the advanced settings.

+ :::image type="content" source="media/workbooks-create-workbook/workbooks-selected-tab.png" alt-text="Screenshot that shows conditionally visible tab in workbooks.":::

+The first tab is selected by default, initially setting **selectedTab** to **1** and making that component visible. Selecting the second tab changes the value of the parameter to **2**, and different content is displayed.

+ :::image type="content" source="media/workbooks-create-workbook/workbooks-selected-tab2.png" alt-text="Screenshot that shows workbooks with content displayed when the selected tab is 2.":::

+A sample workbook with the preceding tabs is available in [sample Azure workbooks with links](workbooks-sample-links.md#sample-workbook-with-links).

+ - You can use tabs to open other views, but use this functionality sparingly. Most users won't expect to navigate by selecting a tab. If other tabs set a parameter to a specific value, a tab that opens a view wouldn't change that value, so the rest of the workbook content will continue to show the view/data for the previous tab.

+### Use toolbars

+Use the toolbar style to have your links appear styled as a toolbar. In toolbar style, you must fill in fields for:

+ - **Button text**: The text to display on the toolbar. Parameters can be used in this field.

+ - **Icons**: The icons to display on the toolbar.

+ - **Tooltip text**: Text to be displayed on the toolbar button's tooltip text. Parameters can be used in this field.

+If any required parameters are used in button text, tooltip text, or value fields, and the required parameter is unset, the toolbar button will be disabled. For example, this functionality can be used to disable toolbar buttons when no value is selected in another parameter/control.

+A sample workbook with toolbars, global parameters, and Azure Resource Manager actions is available in [sample workbooks with links](workbooks-sample-links.md#sample-workbook-with-toolbar-links).

+## Add groups

+You can logically group a set of components by using a group component in a workbook.

+ - **Visibility**: When you want several components to hide or show together, you can set the visibility of the entire group of components, instead of setting visibility settings on each individual component. This functionality can be useful in templates that use tabs. You can use a group as the content of the tab, and the entire group can be hidden or shown based on a parameter set by the selected tab.

+ - **Performance**: When you have a large template with many sections or tabs, you can convert each section into its own subtemplate. You can use groups to load all the subtemplates within the top-level template. The content of the subtemplates won't load or run until a user makes those groups visible. Learn more about [how to split a large template into many templates](#split-a-large-template-into-many-templates).

+1. Make sure you're in edit mode by selecting **Edit**.

+1. Add a group by doing one of these steps:

+ - Select **Add** > **Add group** below an existing element or at the bottom of the workbook.

+ - Select the ellipsis (...) to the right of the **Edit** button next to one of the elements in the workbook. Then select **Add** > **Add group**.

+ :::image type="content" source="media/workbooks-create-workbook/workbooks-add-group.png" alt-text="Screenshot that shows adding a group to a workbook. ":::

+1. Select **Done Editing.**

+ This group is in read mode with two components inside: a text component and a query component.

+ :::image type="content" source="media/workbooks-create-workbook/workbooks-groups-view.png" alt-text="Screenshot that shows a group in read mode in a workbook.":::

+ In edit mode, you can see those two components are actually inside a group component. In the following screenshot, the group is in edit mode. The group contains two components inside the dashed area. Each component can be in edit or read mode, independent of each other. For example, the text step is in edit mode while the query step is in read mode.

+A group is treated as a new scope in the workbook. Any parameters created in the group are only visible inside the group. This is also true for merge. You can only see data inside the group or at the parent level.

+ - **Editable**: The group in the workbook allows you to add, remove, or edit the contents of the components in the group. This group is most commonly used for layout and visibility purposes.

+ - **From a template**: The group in the workbook loads from the contents of another workbook by its ID. The content of that workbook is loaded and merged into the workbook at runtime. In edit mode, you can't modify any of the contents of the group. They'll just load again from the template the next time the component loads. When you load a group from a template, use the full Azure Resource ID of an existing workbook.

+Lazy loading is the default. In lazy loading, the group is only loaded when the component is visible. This functionality allows a group to be used by tab components. If the tab is never selected, the group never becomes visible, so the content isn't loaded.

+In this mode, a button is displayed where the group would be. No content is retrieved or created until the user explicitly selects the button to load the content. This functionality is useful in scenarios where the content might be expensive to compute or rarely used. You can specify the text to appear on the button.

+This screenshot shows explicit load settings with a configured **Load More** button:

+ :::image type="content" source="media/workbooks-create-workbook/workbooks-groups-explicitly-loaded.png" alt-text="Screenshot that shows explicit load settings for a group in the workbook.":::

+This screenshot shows the group before being loaded in the workbook:

+ :::image type="content" source="media/workbooks-create-workbook/workbooks-groups-explicitly-loaded-before.png" alt-text="Screenshot that shows an explicit group before being loaded in the workbook.":::

+This screenshot shows the group after being loaded in the workbook:

+ :::image type="content" source="media/workbooks-create-workbook/workbooks-groups-explicitly-loaded-after.png" alt-text="Screenshot that shows an explicit group after being loaded in the workbook.":::

+In **Always** mode, the content of the group is always loaded and created as soon as the workbook loads. This functionality is most frequently used when you're using a group only for layout purposes, where the content is always visible.

+### Use templates inside a group

+When a group is configured to load from a template, by default, that content is loaded in lazy mode. It only loads when the group is visible.

+When a template is loaded into a group, the workbook attempts to merge any parameters declared in the template with parameters that already exist in the group. Any parameters that already exist in the workbook with identical names are merged out of the template being loaded. If all parameters in a parameter component are merged out, the entire parameters component disappears.

+Suppose you have a template that has two parameters at the top, a time range parameter and a text parameter named **Filter**:

+ :::image type="content" source="media/workbooks-create-workbook/workbooks-groups-top-level-params.png" alt-text="Screenshot that shows top-level parameters in a workbook.":::

+ :::image type="content" source="media/workbooks-create-workbook/workbooks-groups-merged-away.png" alt-text="Screenshot that shows a workbook template with top-level parameters.":::

+When the second template is loaded into the group, the duplicate parameters are merged out. Because all the parameters are merged away, the inner parameters component is also merged out. The result is that the group contains only the text component.

+Suppose you have a template that has two parameters at the top, a time range parameter and a text parameter named **FilterB** ():

+ :::image type="content" source="media/workbooks-create-workbook/workbooks-groups-wont-merge-away.png" alt-text="Screenshot that shows a group component with the result of parameters merged away.":::

+ :::image type="content" source="media/workbooks-create-workbook/workbooks-groups-wont-merge-away-result.png" alt-text="Screenshot that shows a workbook group where parameters won't merge away.":::

+If the loaded template had contained **TimeRange** and **Filter** (instead of **FilterB**), the resulting workbook would have a parameters component and a group with only the text component remaining.

+### Split a large template into many templates

+To improve performance, it's helpful to break up a large template into multiple smaller templates that load some content in lazy mode or on demand by the user. This arrangement makes the initial load faster because the top-level template can be much smaller.

+When you split a template into parts, you need to split the template into many templates (subtemplates) that all work individually. If the top-level template has a **TimeRange** parameter that other components use, the subtemplate also needs to have a parameters component that defines a parameter with the same exact name. The subtemplates work independently and can load inside larger templates in groups.

+To turn a larger template into multiple subtemplates:

+1. Create a new empty group near the top of the workbook, after the shared parameters. This new group eventually becomes a subtemplate.

+1. Create a copy of the shared parameters component. Then use **move into group** to move the copy into the group created in step 1. This parameter allows the subtemplate to work independently of the outer template and is merged out when it's loaded inside the outer template.

+ > Subtemplates don't technically need to have the parameters that get merged out if you never plan on the subtemplates being visible by themselves. If the subtemplates don't have the parameters, they'll be hard to edit or debug if you need to do so later.

+1. Move each component in the workbook you want to be in the subtemplate into the group created in step 1.

+1. If the individual components moved in step 3 had conditional visibilities, that will become the visibility of the outer group (like used in tabs). Remove them from the components inside the group and add that visibility setting to the group itself. Save here to avoid losing changes. You can also export and save a copy of the JSON content.

+1. If you want that group to be loaded from a template, you can use **Edit** in the group. This action opens only the content of that group as a workbook in a new window. You can then save it as appropriate and close this workbook view. Don't close the browser. Only close that view to go back to the previous workbook where you were editing.

+1. You can then change the group component to load from a template and set the template ID field to the workbook/template you created in step 5. To work with workbook IDs, the source needs to be the full Azure Resource ID of a shared workbook. Select **Load** and the content of that group is now loaded from that subtemplate instead of being saved inside this outer workbook.

+[Common Azure Workbooks use cases](workbooks-commonly-used-components.md)

+ Title: Azure Workbooks criteria parameters

+description: Learn about adding criteria parameters to your workbook.

+When a query depends on many parameters, the query will be stalled until each of its parameters has been resolved. Sometimes a parameter could have a simple query that concatenates a string or performs a conditional evaluation. These queries still make network calls to services that perform these basic operations, and that process increases the time it takes for a parameter to resolve a value. The result is long load times for complex workbooks.

+When you use criteria parameters, you can define a set of criteria based on previously specified parameters that will be evaluated to provide a dynamic value. The main benefit of using criteria parameters is that criteria parameters can resolve values of previously specified parameters and perform simple conditional operations without making any network calls. The following example is a criteria-parameters use case.

+Consider the following conditional query:

+If you're focused on the `metric.counter` object, the value of the parameter `isNetworkCounter` should be true if the parameter `Counter` has `Bytes Received/sec`, `Bytes Sent/sec`, `Total Bytes Received`, or `Total Bytes Transmitted`.

+This can be translated to a criteria text parameter:

+In the preceding screenshot, the conditions will be evaluated from top to bottom and the value of the parameter `isNetworkCounter` will take the value of whichever condition evaluates to true first. All conditions except for the default condition (the "else" condition) can be reordered to get the desired outcome.

+ 1. Select **Add parameters** > **Add Parameter**.

+ 1. In the new parameter pane that opens, enter:

+ - **Parameter name**: `rand`

+ - **Parameter type**: `Text`

+ - **Required**: `checked`

+ - **Get data from**: `Query`

+ - Enter `print rand(0-1)` in the query editor. This parameter will output a value between 0-1.

+ 1. Select **Save** to create the parameter.

+ > The first parameter in the workbook won't show the **Criteria** tab.

+ :::image type="content" source="media/workbooks-criteria/workbooks-criteria-first-param.png" alt-text="Screenshot that shows the first parameter.":::

+1. In the table with the `rand` parameter, select **Add Parameter**.

+1. In the new parameter pane that opens, enter:

+ - **Parameter name**: `randCriteria`

+ - **Parameter type**: `Text`

+ - **Required**: `checked`

+ - **Get data from**: `Criteria`

+1. A grid appears. Select **Edit** next to the blank text box to open the **Criteria Settings** form. For a description of each field, see [Criteria Settings form](#criteria-settings-form).

+ :::image type="content" source="media/workbooks-criteria/workbooks-criteria-setting.png" alt-text="Screenshot that shows the Criteria Settings form.":::

+1. Enter the following data to populate the first criteria, and then select **OK**:

+ - **First operand**: `rand`

+ - **Operator**: `>`

+ - **Value from**: `Static Value`

+ - **Second operand**: `0.25`

+ - **Value from**: `Static Value`

+ - **Result is**: `is over 0.25`

+ :::image type="content" source="media/workbooks-criteria/workbooks-criteria-setting-filled.png" alt-text="Screenshot that shows the Criteria Settings form filled in.":::

+1. Select **Edit** next to the condition `Click edit to specify a result for the default condition` to edit the default condition.

+ > For the default condition, everything should be disabled except for the last `Value from` and `Result is` fields.

+1. Enter the following data to populate the default condition, and then select **OK**:

+ - **Value from**: Static Value

+ - **Result is**: is 0.25 or under

+ :::image type="content" source="media/workbooks-criteria/workbooks-criteria-default.png" alt-text="Screenshot that shows the Criteria Settings default form filled.":::

+1. Save the parameter.

+1. Refresh the workbook to see the `randCriteria` parameter in action. Its value will be based on the value of `rand`.

+## Criteria Settings form

+|First operand| This dropdown list consists of parameter names that have already been created. The value of the parameter will be used on the left side of the comparison. |

+|Operator|The operator used to compare the first and second operands. Can be a numerical or string evaluation. The operator `is empty` will disable the `Second operand` because only the `First operand` is required.|

+|Value from|If set to `Parameter`, a dropdown list consisting of parameters that have already been created appears. The value of that parameter will be used on the right side of the comparison.<br/> If set to `Static Value`, a text box appears where you can enter a value for the right side of the comparison.|

+|Second operand| Will be either a dropdown menu consisting of created parameters or a text box depending on the preceding `Value from` selection.|

+|Value from|If set to `Parameter`, a dropdown list consisting of parameters that have already been created appears. The value of that parameter will be used for the return value of the current parameter.<br/> If set to `Static Value`:<br>- A text box appears where you can enter a value for the result.<br>- You can also dereference other parameters by using curly braces around the parameter name.<br>- It's possible to concatenate multiple parameters and create a custom string, for example, "`{paramA}`, `{paramB}`, and some string." <br><br>If set to `Expression`:<br> - A text box appears where you can enter a mathematical expression that will be evaluated as the result.<br>- Like the `Static Value` case, multiple parameters might be dereferenced in this text box.<br>- If the parameter value referenced in the text box isn't a number, it will be treated as the value `0`.|

+|Result is| Will be either a dropdown menu consisting of created parameters or a textbox depending on the preceding `Value from` selection. The text box will be evaluated as the final result of this **Criteria Settings** form.

+ Title: Azure Monitor workbook dropdown parameters

+description: Simplify complex reporting with prebuilt and custom parameterized workbooks containing dropdown parameters.

+# Workbook dropdown parameters

+By using dropdown parameters, you can collect one or more input values from a known set. For example, you can use a dropdown parameter to select one of your app's requests. Dropdown parameters also provide a user-friendly way to collect arbitrary inputs from users. Dropdown parameters are especially useful in enabling filtering in your interactive reports.

+The easiest way to specify a dropdown parameter is by providing a static list in the parameter setting. A more interesting way is to get the list dynamically via a KQL query. You can also specify whether it's single or multi-select by using parameter settings. If it's multi-select, you can specify how the result set should be formatted, for example, as delimiter or quotation.

+## Create a static dropdown parameter

+1. Select **Add parameters** > **Add Parameter**.

+1. In the new parameter pane that opens, enter:

+ 1. **Parameter name**: `Environment`

+ 1. **Parameter type**: `Drop down`

+ 1. **Required**: `checked`

+ 1. **Allow multiple selections**: `unchecked`

+ 1. **Get data from**: `JSON`

+1. In the **JSON Input** text block, insert this JSON snippet:

+1. Select **Update**.

+1. Select **Save** to create the parameter.

+1. The **Environment** parameter will be a dropdown list with the three values.

+ 

+## Create a static dropdown list with groups of items

+If your query result/JSON contains a `group` field, the dropdown list will display groups of values. Follow the preceding sample, but use the following JSON instead:

+

+## Create a dynamic dropdown parameter

+1. Select **Add parameters** > **Add Parameter**.

+1. In the new parameter pane that opens, enter:

+ 1. **Parameter name**: `RequestName`

+ 1. **Parameter type**: `Drop down`

+ 1. **Required**: `checked`

+ 1. **Allow multiple selections**: `unchecked`

+ 1. **Get data from**: `Query`

+1. In the **JSON Input** text block, insert this JSON snippet:

+1. Select **Run Query**.

+1. Select **Save** to create the parameter.

+1. The **RequestName** parameter will be a dropdown list with the names of all requests in the app.

+ 

+## Reference a dropdown parameter

+You can reference dropdown parameters.

+1. Select **Add query** to add a query control, and then select an Application Insights resource.

+1. In the KQL editor, enter this snippet:

+1. The snippet expands on query evaluation time to:

+1. Run the query to see the results. Optionally, render it as a chart.

+ 

+## Parameter value, label, selection, and group

+The query used in the preceding dynamic dropdown parameter returns a list of values that are rendered faithfully in the dropdown list. But what if you wanted a different display name or one of the names to be selected? Dropdown parameters use value, label, selection, and group columns for this functionality.

+The following sample shows how to get a list of Application Insights dependencies whose display names are styled with an emoji, has the first one selected, and is grouped by operation names:

+

+## Dropdown parameter options

+| Parameter | Description | Example |

+The examples so far explicitly set the parameter to select only one value in the dropdown list. Dropdown parameters also support *multiple selection*. To enable this option, select the **Allow multiple selections** checkbox.

+You can specify the format of the result set via the **Delimiter** and **Quote with** settings. The default returns the values as a collection in the form of **a**, **b**, **c**. You can also limit the number of selections.

+This example shows the multi-select dropdown parameter at work:

+

+[Getting started with Azure Workbooks](workbooks-getting-started.md)

+ Title: Azure Workbooks multi-value parameters

+description: Learn about adding multi-value parameters to your workbook.

+# Multi-value parameters

+A multi-value parameter allows the user to set one or more arbitrary text values. Multi-value parameters are commonly used for filtering, often when a dropdown control might contain too many values to be useful.

+## Create a static multi-value parameter

+1. Select **Add parameters** > **Add Parameter**.

+1. In the new parameter pane that opens, enter:

+ - **Parameter name**: `Filter`

+ - **Parameter type**: `Multi-value`

+ - **Required**: `unchecked`

+ - **Get data from**: `None`

+1. Select **Save** to create the parameter.

+1. The **Filter** parameter will be a multi-value parameter, initially with no values.

+ :::image type="content" source="media/workbooks-multi-value/workbooks-multi-value-create.png" alt-text="Screenshot that shows the creation of a multi-value parameter in a workbook.":::

+1. You can then add multiple values.

+ :::image type="content" source="media/workbooks-multi-value/workbooks-multi-value-third-value.png" alt-text="Screenshot that shows adding a third value in a workbook.":::

+A multi-value parameter behaves similarly to a multi-select [dropdown parameter](workbooks-dropdowns.md) and is commonly used in an "in"-like scenario.

+A multi-value parameter supports the following field styles:

+1. **Standard**: Allows you to add or remove arbitrary text items.

+ :::image type="content" source="media/workbooks-multi-value/workbooks-multi-value-standard.png" alt-text="Screenshot that shows the workbook standard multi-value field.":::

+1. **Password**: Allows you to add or remove arbitrary password fields. The password values are only hidden in the UI when you type. The values are still fully accessible as a parameter value when referred. They're stored unencrypted when the workbook is saved.

+ :::image type="content" source="media/workbooks-multi-value/workbooks-multi-value-password.png" alt-text="Screenshot that shows a workbook password multi-value field.":::

+## Create a multi-value parameter with initial values

+You can use a query to seed the multi-value parameter with initial values. You can then manually remove values or add more values. If a query is used to populate the multi-value parameter, a restore defaults button appears on the parameter to restore back to the originally queried values.

+1. Select **Add parameters** > **Add Parameter**.

+1. In the new parameter pane that opens, enter:

+ - **Parameter name**: `Filter`

+ - **Parameter type**: `Multi-value`

+ - **Required**: `unchecked`

+ - **Get data from**: `JSON`

+1. In the **JSON Input** text block, insert this JSON snippet:

+ All the items that are the result of the query are shown as multi-value items.

+ You aren't limited to JSON. You can use any query provider to provide initial values, but you'll be limited to the first 100 results.

+1. Select **Save** to create the parameter.

+1. The **Filter** parameter will be a multi-value parameter with three initial values.

+ :::image type="content" source="media/workbooks-multi-value/workbooks-multi-value-initial-values.png" alt-text="Screenshot that shows the creation of a dynamic dropdown in a workbook.":::

+- [Workbook parameters](workbooks-parameters.md)

+- [Workbook dropdown parameters](workbooks-dropdowns.md)

+ Title: Azure Workbooks options group parameters

+When you use an options group parameter, you can select one value from a known set. For example, you can select one of your app's requests. If you're working with a few values, an options group can be a better choice than a [dropdown parameter](workbooks-dropdowns.md). You can see all the possible values and see which one is selected.

+Options groups are commonly used for yes/no or on/off style choices. When there are many possible values, using a dropdown list is a better choice. Unlike dropdown parameters, an options group always allows only one selected value.

+- Providing a static list in the parameter setting.

+- Using a KQL query to retrieve the list dynamically.

+## Create a static options group parameter

+1. Select **Add parameters** > **Add Parameter**.

+1. In the new parameter pane that opens, enter:

+ - **Parameter name**: `Environment`

+ - **Parameter type**: `Options Group`

+ - **Required**: `checked`

+ - **Get data from**: `JSON`

+1. In the **JSON Input** text block, insert this JSON snippet:

+ You aren't limited to JSON. You can use any query provider to provide initial values, but you'll be limited to the first 100 results.

+1. Select **Save** to create the parameter.

+1. The **Environment** parameter will be an options group control with the three values.

+ :::image type="content" source="media/workbooks-options-group/workbooks-options-group-create.png" alt-text="Screenshot that shows the creation of a static options group in a workbook.":::

+- [Workbook parameters](workbooks-parameters.md)

+- [Workbook dropdown parameters](workbooks-dropdowns.md)

+ Title: Create workbook parameters

+By using parameters, you can collect input from consumers and reference it in other parts of a workbook. It's usually used to scope the result set or set the right visual. You can build interactive reports and experiences by using this key capability.

+When you use workbooks, you can control how your parameter controls are presented to consumers. They can be text box versus dropdown list, single- versus multi-select, and values from text, JSON, KQL, or Azure Resource Graph.

+* [Time](workbooks-time.md): Allows you to select from pre-populated time ranges or select a custom range

+* [Drop down](workbooks-dropdowns.md): Allows you to select from a value or set of values

+* [Options group](workbooks-options-group.md): Allows you to select one value from a known set

+* [Text](workbooks-text.md): Allows you to enter arbitrary text

+* [Criteria](workbooks-criteria.md): Allows you to define a set of criteria based on previously specified parameters, which will be evaluated to provide a dynamic value

+* [Resource](workbooks-resources.md): Allows you to select one or more Azure resources

+* [Subscription](workbooks-resources.md): Allows you to select one or more Azure subscription resources

+* [Multi-value](workbooks-multi-value.md): Allows you to set one or more arbitrary text values

+* Resource type: Allows you to select one or more Azure resource type values

+* Location: Allows you to select one or more Azure location values

+You can reference parameter values from other parts of workbooks either by using bindings or value expansions.

+### Reference a parameter with bindings

+1. Select **Add query** to add a query control, and then select an Application Insights resource.

+1. Open the **Time Range** dropdown list and select the **Time Range** option from the **Parameters** section at the bottom:

+ - This option binds the time range parameter to the time range of the chart.

+ - The time scope of the sample query is now **Last 24 hours**.

+1. Run the query to see the results.

+ :::image type="content" source="media/workbooks-parameters/workbooks-time-binding.png" alt-text="Screenshot that shows a time range parameter referenced via bindings.":::

+1. Select **Add query** to add a query control, and then select an Application Insights resource.

+1. In the KQL, enter a time scope filter by using the parameter `| where timestamp {TimeRange}`:

+ - This parameter expands on query evaluation time to `| where timestamp > ago(1d)`.

+ - This option is the time range value of the parameter.

+1. Run the query to see the results.

+ :::image type="content" source="media/workbooks-parameters/workbooks-time-in-code.png" alt-text="Screenshot that shows a time range referenced in the KQL query.":::

+### Reference a parameter with text

+1. In the Markdown, enter `The chosen time range is {TimeRange:label}`.

+1. Select **Done Editing**.

+1. The text control shows the text *The chosen time range is Last 24 hours*.

+Each parameter type has its own formatting options. Use the **Previews** section of the **Edit Parameter** pane to see the formatting expansion options for your parameter.

+ :::image type="content" source="media/workbooks-parameters/workbooks-time-settings.png" alt-text="Screenshot that shows time range parameter options.":::

+You can use these options to format all parameter types except for **Time range picker**. For examples of formatting times, see [Time parameter options](workbooks-time.md#time-parameter-options).

+Other parameter types include:

+ - **Resource picker**: Resource IDs are formatted.

+ - **Subscription picker**: Subscription values are formatted.

+**Original value**:

+**Formatted value**:

+**Original value**:

+**Formatted value**:

+**Original value**:

+**Formatted value**:

+## Format parameters by using JSONPath

+For example, you might have a string parameter named `selection` that was the result of a query or selection in a visualization that has the following value:

+By using JSONPath, you could get individual values from that object:

+Format | Result

+> If the parameter value isn't valid JSON, the result of the format will be an empty value.

+## Parameter style

+Pills style is the default style. The parameters look like text and require the user to select them once to go into the edit mode.

+ :::image type="content" source="media/workbooks-parameters/workbooks-pills-read-mode.png" alt-text="Screenshot that shows Azure Workbooks pills-style read mode.":::

+ :::image type="content" source="media/workbooks-parameters/workbooks-pills-edit-mode.png" alt-text="Screenshot that shows Azure Workbooks pills-style edit mode.":::

+ :::image type="content" source="media/workbooks-parameters/workbooks-standard.png" alt-text="Screenshot that shows Azure Workbooks standard style.":::

+### Form horizontal

+In form horizontal style, the controls are always visible, with the label on the left side of the control.

+ :::image type="content" source="media/workbooks-parameters/workbooks-form-horizontal.png" alt-text="Screenshot that shows Azure Workbooks form horizontal style.":::

+### Form vertical

+In form vertical style, the controls are always visible, with the label above the control. Unlike standard style, there's only one label or control in one row.

+ :::image type="content" source="media/workbooks-parameters/workbooks-form-vertical.png" alt-text="Screenshot that shows Azure Workbooks form vertical style.":::

+> In standard, form horizontal, and form vertical layouts, there's no concept of inline editing. The controls are always in edit mode.

+Now that you've learned how parameters work, and the limitations about only being able to use a parameter "downstream" of where it's set, it's time to learn about global parameters, which change those rules.

+With a global parameter, the parameter must still be declared before it can be used. But any step that sets a value to that parameter will affect all instances of that parameter in the workbook.

+> Because changing a global parameter has this "update all" behavior, the global setting should only be turned on for parameters that require this behavior. A combination of global parameters that depend on each other can create a cycle or oscillation where the competing globals change each other over and over. To avoid cycles, you can't "redeclare" a parameter that's been declared as global. Any subsequent declarations of a parameter with the same name will create a read-only parameter that can't be edited in that place.

+1. Synchronize time ranges between many charts:

+ - Without a global parameter, any time range brush in a chart will only be exported after that chart. So, selecting a time range in the third chart will only update the fourth chart.

+ - With a global parameter, you can create a global **timeRange** parameter, give it a default value, and have all the other charts use that as their bound time range and time brush output. In addition, set the **Only export the parameter when a range is brushed** setting. Any change of time range in any chart updates the global **timeRange** parameter at the top of the workbook. This functionality can be used to make a workbook act like a dashboard.

+1. Allow changing the selected tab in a links step via links or buttons:

+ - Without a global parameter, the links step only outputs a parameter for the selected tab.

+ - With a global parameter, you can create a global **selectedTab** parameter. Then you can use that parameter name in the tab selections in the links step. You can pass that parameter value into the workbook from a link or by using another button or link to change the selected tab. Using buttons from a links step in this way can make a wizard-like experience, where buttons at the bottom of a step can affect the visible sections above it.

+When you create the parameter in a parameters step, use the **Treat this parameter as a global** option in **Advanced Settings**. The only way to make a global parameter is to declare it with a parameters step. The other methods of creating parameters, via selections, brushing, links, buttons, and tabs, can only update a global parameter. They can't declare one themselves.

+ :::image type="content" source="media/workbooks-parameters/workbooks-parameters-global-setting.png" alt-text="Screenshot that shows setting global parameters in a workbook.":::

+### Update the value of an existing global parameter

+For the chart example, the most common way to update a global parameter is by using time brushing.

+In this example, the **timerange** parameter is declared as global. In a query step below that, create and run a query that uses that **timerange** parameter in the query and returns a time chart result. In **Advanced Settings** for the query step, enable the time range brushing setting. Use the same parameter name as the output for the time brush parameter. Also, select the **Only export the parameter when a range is brushed** option.

+ :::image type="content" source="media/workbooks-parameters/workbooks-global-time-range-brush.png" alt-text="Screenshot that shows the global time brush setting in a workbook.":::

+Whenever a time range is brushed in this chart, it also updates the **timerange** parameter above this query, and the query step itself, because it also depends on **timerange**.

+ - The time range is shown as **Last hour**.

+ :::image type="content" source="media/workbooks-parameters/workbooks-global-before-brush.png" alt-text="Screenshot that shows setting global parameters before brushing.":::

+ - The time range is still the last hour, and the brushing outlines are drawn.

+ - No parameters have changed. After you let go of the brush, the time range is updated.

+ :::image type="content" source="media/workbooks-parameters/workbooks-global-during-brush.png" alt-text="Screenshot that shows setting global parameters during brushing.":::

+ - The time range specified by the time brush is set by this step. It overrides the global value. The **timerange** dropdown list now displays that custom time range.

+ - Because the global value at the top has changed, and because this chart depends on **timerange** as an input, the time range of the query used in the chart also updates. As a result, the query and the chart will update.

+ :::image type="content" source="media/workbooks-parameters/workbooks-global-after-brush.png" alt-text="Screenshot that shows setting global parameters after brushing.":::

+ > If you don't use a global parameter, the **timerange** parameter value will only change below this query step. Things above this step or this item itself won't update.

+ Title: Azure Monitor workbook resource parameters

+description: Learn how to use resource parameters to allow picking of resources in workbooks. Use the resource parameters to set the scope from which to get the data.

+Resource parameters allow picking of resources in workbooks. This functionality is useful in setting the scope from which to get the data. An example would be allowing you to select the set of VMs, which charts use later when presenting the data.

+Values from resource pickers can come from the workbook context, static list, or Azure Resource Graph queries.

+1. Select **Add parameters** > **Add Parameter**.

+1. In the new parameter pane that opens, enter:

+ 1. **Parameter name**: `Applications`

+ 1. **Parameter type**: `Resource picker`

+ 1. **Required**: `checked`

+ 1. **Allow multiple selections**: `checked`

+ 1. **Get data from**: `Workbook Resources`

+ 1. **Include only resource types**: `Application Insights`

+1. Select **Save** to create the parameter.

+ 

+1. Select **Add parameters** > **Add Parameter**.

+1. In the new parameter pane that opens, enter:

+ 1. **Parameter name**: `Applications`

+ 1. **Parameter type**: `Resource picker`

+ 1. **Required**: `checked`

+ 1. **Allow multiple selections**: `checked`

+ 1. **Get data from**: `Query`

+ 1. **Query Type**: `Azure Resource Graph`

+ 1. **Subscriptions**: `Use default subscriptions`

+ 1. In the query control, add this snippet:

+1. Select **Save** to create the parameter.

+ 

+> Azure Resource Graph isn't yet available in all clouds. Ensure that it's supported in your target cloud if you choose this approach.

+For more information on Azure Resource Graph, see [What is Azure Resource Graph?](../../governance/resource-graph/overview.md).

+1. Select **Add parameters** > **Add Parameter**.

+1. In the new parameter pane that opens, enter:

+ 1. **Parameter name**: `Applications`

+ 1. **Parameter type**: `Resource picker`

+ 1. **Required**: `checked`

+ 1. **Allow multiple selections**: `checked`

+ 1. **Get data from**: `JSON`

+ 1. In the content control, add this JSON snippet:

+ ```json

+ [

+ { "value":"/subscriptions/<sub-id>/resourceGroups/<resource-group>/providers/<resource-type>/acmeauthentication", "label": "acmeauthentication", "selected":true, "group":"Acme Backend" },

+ { "value":"/subscriptions/<sub-id>/resourceGroups/<resource-group>/providers/<resource-type>/acmeweb", "label": "acmeweb", "selected":false, "group":"Acme Frontend" }

+ ]

+ ```

+ 1. Select **Update**.

+1. Optionally, set `Include only resource types` to **Application Insights**.

+1. Select **Save** to create the parameter.

+1. Select **Add query** to add a query control, and then select an Application Insights resource.

+1. Use the **Application Insights** dropdown list to bind the parameter to the control. This step sets the scope of the query to the resources returned by the parameter at runtime.

+1. In the KQL control, add this snippet:

+1. Run the query to see the results.

+ 

+This approach can be used to bind resources to other controls like metrics.

+| Parameter | Description | Example |

+| `{Applications}` | The selected resource ID. | _/subscriptions/\<sub-id\>/resourceGroups/\<resource-group\>/providers/\<resource-type\>/acmeauthentication_ |

+| `{Applications:label}` | The label of the selected resource. | `acmefrontend` |

+| `{Applications:value}` | The value of the selected resource. | _'/subscriptions/\<sub-id\>/resourceGroups/\<resource-group\>/providers/\<resource-type\>/acmeauthentication'_ |

+| `{Applications:name}` | The name of the selected resource. | `acmefrontend` |

+| `{Applications:resourceGroup}` | The resource group of the selected resource. | `acmegroup` |

+| `{Applications:resourceType}` | The type of the selected resource. | _microsoft.insights/components_ |

+| `{Applications:subscription}` | The subscription of the selected resource. | |

+| `{Applications:grid}` | A grid that shows the resource properties. Useful to render in a text block while debugging. | |

+[Getting started with Azure Workbooks](workbooks-getting-started.md)

+ Title: Azure Monitor workbook text parameters

+Text box parameters provide a simple way to collect text input from workbook users. They're used when it isn't practical to use a dropdown list to collect the input, for example, with an arbitrary threshold or generic filters. By using a workbook, you can get the default value of the text box from a query. This functionality allows for interesting scenarios like setting the default threshold based on the p95 of the metric.

+A common use of text boxes is as internal variables used by other workbook controls. You use a query for default values and make the input control invisible in read mode. For example, you might want a threshold to come from a formula, not a user, and then use the threshold in subsequent queries.

+1. Select **Add parameters** > **Add Parameter**.

+1. In the new parameter pane that opens, enter:

+ 1. **Parameter name**: `SlowRequestThreshold`

+ 1. **Parameter type**: `Text`

+ 1. **Required**: `checked`

+ 1. **Get data from**: `None`

+1. Select **Save** to create the parameter.

+ :::image type="content" source="./media/workbooks-text/text-create.png" alt-text="Screenshot that shows the creation of a text parameter.":::

+This screenshot shows how the workbook looks in read mode:

+The text parameter supports the following field styles:

+- **Standard**: A single line text field.

+ :::image type="content" source="./media/workbooks-text/standard-text.png" alt-text="Screenshot that shows a standard text field.":::

+- **Password**: A single line password field. The password value is only hidden in the UI when you type. The value is fully accessible as a parameter value when referred. It's stored unencrypted when the workbook is saved.

+ :::image type="content" source="./media/workbooks-text/password-text.png" alt-text="Screenshot that shows a password field.":::

+- **Multiline**: A multiline text field with support of rich IntelliSense and syntax colorization for the following languages:

+ You can also specify the height for the multiline editor.

+ :::image type="content" source="./media/workbooks-text/kql-text.png" alt-text="Screenshot that shows a multiline text field.":::

+1. Select **Add query** to add a query control, and then select an Application Insights resource.

+1. In the KQL box, add this snippet:

+1. By using the text parameter with a value of 500 coupled with the query control, you effectively run the following query:

+1. Run the query to see the results.

+ :::image type="content" source="./media/workbooks-text/text-reference.png" alt-text="Screenshot that shows a text parameter referenced in KQL.":::

+> In the preceding example, `{SlowRequestThreshold}` represents an integer value. If you were querying for a string like `{ComputerName}`, you would need to modify your Kusto query to add quotation marks `"{ComputerName}"` in order for the parameter field to accept an input without quotation marks.

+1. Select **Add parameters** > **Add Parameter**.

+1. In the new parameter pane that opens, enter:

+ 1. **Parameter name**: `SlowRequestThreshold`

+ 1. **Parameter type**: `Text`

+ 1. **Required**: `checked`

+ 1. **Get data from**: `Query`

+1. In the KQL box, add this snippet:

+1. Run the query to see the results.

+1. Select **Save** to create the parameter.

+ :::image type="content" source="./media/workbooks-text/text-default-value.png" alt-text="Screenshot that shows a text parameter with a default value from KQL.":::

+> While this example queries Application Insights data, the approach can be used for any log-based data source, such as Log Analytics and Azure Resource Graph.

+## Add validations

+For standard and password text parameters, you can add validation rules that are applied to the text field. Add a valid regex with an error message. If the message is set, it's shown as an error when the field is invalid.

+If the match is selected, the field is valid if the value matches the regex. If the match isn't selected, the field is valid if it doesn't match the regex.

+## Format JSON data

+If JSON is selected as the language for the multiline text field, the field will have a button that formats the JSON data of the field. You can also use the shortcut Ctrl + \ to format the JSON data.

+If data is coming from a query, you can select the option to pre-format the JSON data that's returned by the query.

+[Get started with Azure Workbooks](workbooks-getting-started.md)

+ Title: Azure Monitor workbook time parameters

+With time parameters, you can set the time context of analysis, which is used by almost all reports. Time parameters are simple to set up and use. You can use them to specify the time ranges to show in a dropdown list. You can also create custom time ranges.

+1. Select **Add parameters** > **Add Parameter**.

+1. In the new parameter pane that opens, enter:

+ - **Parameter name**: `TimeRange`

+ - **Parameter type**: `Time range picker`

+ - **Required**: `checked`

+ - **Available time ranges**: `Last hour`, `Last 12 hours`, `Last 24 hours`, `Last 48 hours`, `Last 3 days`, `Last 7 days`, and `Allow custom time range selection`.

+ :::image type="content" source="media/workbooks-time/parameters-time.png" alt-text="Screenshot that shows a time range parameter in read mode.":::

+This is what the workbook looks like in read mode.

+## Reference a time parameter

+You can reference time parameters with bindings, KQL, or text.

+### Reference a time parameter with bindings

+1. Select **Add query** to add a query control, and then select an Application Insights resource.

+1. Most workbook controls support a **Time Range** scope picker. Open the **Time Range** dropdown list and select the `{TimeRange}` in the **Time Range Parameters** group at the bottom:

+ * This control binds the time range parameter to the time range of the chart.

+ * The time scope of the sample query is now **Last 24 hours**.

+1. Run the query to see the results.

+ :::image type="content" source="media/workbooks-time/time-binding.png" alt-text="Screenshot that shows a time range parameter referenced via bindings.":::

+### Reference a time parameter with KQL

+1. Select **Add query** to add a query control, and then select an Application Insights resource.

+1. In the KQL, enter a time scope filter by using the parameter `| where timestamp {TimeRange}`:

+ * This parameter expands on the query evaluation time to `| where timestamp > ago(1d)`.

+ * This option is the time range value of the parameter.

+1. Run the query to see the results.

+ :::image type="content" source="media/workbooks-time/time-in-code.png" alt-text="Screenshot that shows a time range referenced in KQL.":::

+### Reference a time parameter in text

+1. In the Markdown, enter `The chosen time range is {TimeRange:label}`.

+1. Select **Done Editing**.

+1. The text control shows the text *The chosen time range is Last 24 hours*.

+| Parameter | Description | Example |

+| `{TimeRange:value}` | Time range value | > ago (1d) |

+| `{TimeRange:query}` | Time range query | > ago (1d) |

+### Use parameter options in a query

+[Getting started with Azure Workbooks](workbooks-getting-started.md)

+ # [CLI](#tab/CLI)

+ ```azurecli-interactive

+ echo "Enter the Resource Group name:" &&

+ read resourceGroupName &&

+ az identity list -g $resourceGroupName

+ ```

+ # [PowerShell](#tab/PowerShell)

+ ```powershell-interactive

+ $resourceGroupName = Read-Host -Prompt "Enter the Resource Group name"

+ (Get-AzUserAssignedIdentity -ResourceGroupName $resourceGroupname).id

+ Write-Host "Press [ENTER] to continue ..."

+ ```

+

+1. Run the following Azure CLI or Azure PowerShell script to deploy the template.

+ # [CLI](#tab/CLI)

+ ```azurecli-interactive

+ echo "Enter a project name that is used to generate resource names:" &&

+ read projectName &&

+ echo "Enter the location (i.e. centralus):" &&

+ read location &&

+ echo "Enter your email address used to sign in to Azure:" &&

+ read upn &&

+ echo "Enter the user-assigned managed identity ID:" &&

+ read identityId &&

+ adUserId=$((az ad user show --id jgao@microsoft.com) | jq -r '.id') &&

+ resourceGroupName="${projectName}rg" &&

+ keyVaultName="${projectName}kv" &&

+ az group create --name $resourceGroupName --location $location &&

+ az deployment group create --resource-group $resourceGroupName --template-file "$HOME/azuredeploy.json" --parameters identityId=$identityId keyVaultName=$keyVaultName objectId=$adUserId

+ ```

+ # [PowerShell](#tab/PowerShell)

+

+3. Select **New registration**.

+5. Select **Register** to confirm the register.

+1. On the **Client secrets** tab, select **New client secret**.

+| `AZURE_CLIENT_CERTIFICATE_PATH` | A path to a certificate and private key pair in PEM or PFX format, which can authenticate the App Registration. |

+| `AZURE_PASSWORD` | The password for the Azure Active Directory user account. Password isn't supported for accounts with MFA enabled. |

+You can use either [DefaultAzureCredential](/dotnet/api/azure.identity.defaultazurecredential) or [EnvironmentCredential](/dotnet/api/azure.identity.environmentcredential) to configure your SignalR endpoints.

+See [Environment variables](/dotnet/api/overview/azure/identity-readme#environment-variables) for the list of pre-defined environment variables. When you have multiple services, we recommend that you use the same application identity, so that you don't need to configure the identity for each service. These environment variables might also be used by other services according to the settings of other services.

+The SignalR specified variables share the same key prefix with `serviceUri` key. Here's the list of variables you might use:

+This article shows how to configure your SignalR resource and code to authorize a managed identity request to a SignalR resource.

+This example shows you how to configure `System-assigned managed identity` on a `Virtual Machine` using the Azure portal.

+1. Select the **Save** button to confirm the change.

+The system-assigned managed identity will be used by default, but **make sure that you don't configure any environment variables** that the [EnvironmentCredential](/dotnet/api/azure.identity.environmentcredential) preserved if you were using `DefaultAzureCredential`. Otherwise it will fall back to use `EnvironmentCredential` to make the request and it will result to a `Unauthorized` response in most cases.

+Azure Functions SignalR bindings use [application settings](../azure-functions/functions-how-to-use-azure-function-app-settings.md) on portal or [`local.settings.json`](../azure-functions/functions-develop-local.md#local-settings-file) at local to configure managed identity to access your SignalR resources.

+If you only configure the service URI, then the `DefaultAzureCredential` is used. This class is useful when you want to share the same configuration on Azure and local dev environment. To learn how `DefaultAzureCredential` works, see [DefaultAzureCredential](/dotnet/api/overview/azure/identity-readme#defaultazurecredential).

+On Azure portal, use the following example to configure a `DefaultAzureCredential`. If don't configure any [environment variables listed here](/dotnet/api/overview/azure/identity-readme#environment-variables), then the system-assigned identity will be used to authenticate.

+Here's a config sample of `DefaultAzureCredential` in the `local.settings.json` file. At the local scope there's no managed identity, and the authentication via Visual Studio, Azure CLI, and Azure PowerShell accounts will be attempted in order.

+If you want to use system-assigned identity independently and without the influence of [other environment variables](/dotnet/api/overview/azure/identity-readme#environment-variables), you should set the `credential` key with connection name prefix to `managedidentity`. Here's an application settings sample:

+If you want to use user-assigned identity, you need to assign one more `clientId` key with connection name prefix compared to system-assigned identity. Here's the application settings sample:

+You can view resource logs for Azure SignalR Service. These logs provide a richer view of connectivity to your Azure SignalR Service instance. The resource logs provide detailed information for every connection. For example, basic information (user ID, connection ID, and transport type, and so on) and event information (connect, disconnect and abort event, and so on) of the connection. resource logs can be used for issue identification, connection tracking and analysis.

+To use sample query for SignalR service, follow the steps below:

+Service reloading, try reconnecting | Azure SignalR Service is reloading. Azure SignalR support auto-reconnecting, you can wait until reconnected or manually reconnect to Azure SignalR Service

+To troubleshoot about unexpected connection growing, the first thing you need to do is filter out the extra connections. You can add unique test user ID to your test client connection. Check the resource logs. If you see more than one client connections have the same test user ID or IP, then it's likely the client side is creating more connections than expected. Check your client side.

+If you get 401 Unauthorized returned for client requests, check your resource logs. If you encounter `Failed to validate audience. Expected Audiences: <valid audience>. Actual Audiences: <actual audience>`, it means your all audiences in your access token are invalid. Try to use the valid audiences suggested in the log.

+If you find that you can't establish SignalR client connections to Azure SignalR Service, check your resource logs. If you encounter `Connection count reaches limit` in resource log, you establish too many connections to SignalR Service, which reach the connection count limit. Consider scaling up your SignalR Service. If you encounter `Message count reaches limit` in resource log, it means you use free tier, and you use up the quota of messages. If you want to send more messages, consider changing your SignalR Service to standard tier to send more messages. For more information, see [Azure SignalR Service Pricing](https://azure.microsoft.com/pricing/details/signalr-service/).

+If you don't mind potential performance effects and no client-to-server direction message, check the `Messaging` in `Log Source Settings/Types` to enable *collect-all* log collecting behavior. For more information about this behavior, see [collect all section](#collect-all).

+By checking the sign-in server and service side, you can easily find out whether the message is sent from server, arrives at SignalR service, and leaves from SignalR service. Basically, by checking if the *received* and *sent* message are matched or not based on message tracing ID, you can tell whether the message loss issue is in server or SignalR service in this direction. For more information, see the [details](#message-flow-detail-for-path3) below.

+By checking the sign-in server and service side, you can easily find out whether the message is pass the server or SignalR service successfully. Basically, by checking if the *received* and *sent* message are matched or not based on message tracing ID, you can tell whether the message loss issue is in server or SignalR service. For more information, see the details below.

+The tracing ID will be generated in SignalR service once the message arrives at SignalR service in **Path 1**. SignalR service will generate a log `Received a message <MessageTracingId> from client connection <ConnectionId>.` for each message in diagnostic client. Once the message leaves from the SignalR to server, SignalR service will generate a log message `Sent a message <MessageTracingId> to server connection <ConnectionId> successfully.` If you see these two logs, you can be sure that the message passes through SignalR service successfully.

+1. If message tracing ID A arriving time later than B arriving time, then you must be sending group message **before** the client joining the group.Then you need to make sure the client is in the group before sending group messages.

+## Advanced

+> If you open an issue in GitHub, keep your sensitive information (For example, resource ID, server/client logs) private, only send to members in Microsoft organization privately.

+An Azure resource group is a logical container in which you deploy and manage your Azure resources. The command [az group create][az-group-create] creates a resource group named *myResourceGroup* in the *eastus* region. If you want to use a different name for your resource group, set `RESOURCE_GROUP_NAME` to a different value.

+Next, deploy an Azure Signals Service into the resource group with the following commands.

+Once the SignalR Service has been created, the Azure CLI returns output similar to the following example:

+Once the deployment succeeds (it might take a few minutes), open your browser, and then go to your web app to make sure it's running:

+In Event Grid, you subscribe to a *topic* to tell it which events you want to track, and where to send them. The command [az eventgrid event-subscription create][az-eventgrid-event-subscription-create] subscribes to the Azure SignalR Service you created and specifies your web app's URL as the endpoint to which it should send events. The environment variables you populated in earlier sections are reused here, so no edits are required.

+When the subscription is completed, you should see output similar to the following example:

+Switch to the service mode to `Serverless Mode` and set up a client connection to the SignalR Service. You can take [Serverless Sample](https://github.com/aspnet/AzureSignalR-samples/tree/master/samples/Serverless) as a reference.

+You've now connected a client to the SignalR Service. Navigate to your Event Grid Viewer web app, and you should see a `ClientConnectionConnected` event. If you terminate the client, you'll also see a `ClientConnectionDisconnected` event.

+Each Azure SignalR Service instance has a pair of access keys called Primary and Secondary keys. They're used to authenticate SignalR clients when requests are made to the service. The keys are associated with the instance endpoint URL. Keep your keys secure, and rotate them regularly. You're provided with two access keys so that you can maintain connections by using one key while regenerating the other.

+- Verify that your Azure subscription allows you to create SignalR resource in the target region.

+description: In many scaling scenarios, customers often need to create multiple instances and use them together to create a large-scale deployment. For example, sharding requires multiple instances support.

+ When sending a message to a specific *connection* and the target connection is routed to current server, the message goes directly to that connected endpoint. Otherwise, the messages are broadcasted to every Azure SignalR endpoint.

+From SDK version 1.5.0, we're enabling dynamic scale ServiceEndpoints for ASP.NET Core version first. So you don't have to restart app server when you need to add/remove a ServiceEndpoint. As ASP.NET Core is supporting a default configuration like `appsettings.json` with `reloadOnChange: true`, you don't need to change code, and it's supported by nature. And if you'd like to add some customized configuration and work with hot-reload, refer to [Configuration in ASP.NET Core](/aspnet/core/fundamentals/configuration/?view=aspnetcore-3.1&preserve-view=true).

+> [!NOTE]

+When a client tries `/negotiate` with the app server, with the default router, SDK **randomly selects** one endpoint from the set of available `primary` endpoints. When the primary endpoint isn't available, SDK then **randomly selects** from all available `secondary` endpoints. The endpoint is marked as **available** when the connection between server and the service endpoint is alive.

+In cross-region scenario, when a client tries `/negotiate` with the app server hosted in *East US*, by default it always returns the `primary` endpoint located in the same region. When all *East US* endpoints aren't available, the client is redirected to endpoints in other regions. Fail over section below describes the scenario in detail.

+When all `primary` endpoints aren't available, client's `/negotiate` picks from the available `secondary` endpoints. This fail-over mechanism requires that each endpoint should serve as `primary` endpoint to at least one app server.

+The scale settings take a few minutes to apply. In rare cases, it may take around 30 minutes to apply. Scaling doesn't require you to change your code or redeploy your server application.

+3. Choose your pricing tier, and then select **Select**. Set the unit count for **Standard** Tier.

+4. Select **Save**.

+Make a note of the actual name generated for the new resource group. You'll use that resource group name when you want to delete all group resources.

+This article provides troubleshooting guidance for some of the common issues that customers might encounter.

+In some cases, `context.User.Claims` are used to store lots of information for app server, most of which aren't used by `Hub`s but by other components.

+There's a `ClaimsProvider` for you to customize the claims passing to **ASRS** inside the access token.

+* ASP.NET "The connection isn't active, data cannot be sent to the service." error [#324](https://github.com/Azure/azure-signalr/issues/324)

+Azure Service only supports TLS1.2 for security concerns. With .NET framework, it's possible that TLS1.2 isn't the default protocol. As a result, the server connections to ASRS can't be successfully established.

+Currently the default value of JWT token's lifetime is one (1) hour.

+For ASP.NET Core SignalR, when it's using WebSocket transport type, it's OK.

+For ASP.NET Core SignalR's other transport type, SSE and long-polling, the default lifetime means by default the connection can at most persist for one hour.

+For ASP.NET SignalR, the client sends a `/ping` "keep alive" request to the service from time to time, when the `/ping` fails, the client **aborts** the connection and never reconnect. For ASP.NET SignalR, the default token lifetime makes the connection last for *at most* one hour for all the transport type.

+For security concerns, extend TTL isn't encouraged. We suggest adding reconnect logic from the client to restart the connection when such 401 occurs. When the client restarts the connection, it will negotiate with app server to get the JWT token again and get a renewed token.

+* Check the URL of the request when 404 occurs. If the URL is targeting to your web app, and similar to `{your_web_app}/hubs/{hubName}`, check if the client `SkipNegotiation` is `true`. The client receives a redirect URL when it first negotiates with the app server. The client must *not* skip negotiation when using Azure SignalR.

+* Another 404 can happen when the connect request is handled more than five (5) seconds after `/negotiate` is called. Check the timestamp of the client request, and open an issue to us if the request to the service has a slow response.

+For ASP.NET SignalR, when the [client connection drops](#client_connection_drop), it reconnects using the same `connectionId` for three times before stopping the connection. `/reconnect` can help if the connection is dropped due to network intermittent issues that `/reconnect` can reestablish the persistent connection successfully. Under other circumstances, for example, the client connection is dropped due to the routed server connection is dropped, or SignalR Service has some internal errors like instance restart/failover/deployment, the connection no longer exists, thus `/reconnect` returns `404`. It's the expected behavior for `/reconnect` and after three times retry the connection stops. We suggest having [connection restart](#restart_connection) logic when connection stops.

+This error is reported when there's no server connection to Azure SignalR Service connected.

+* When `Hub` throws exceptions with the incoming request

+* When the server connection, which the client routed to, drops, see below section for details on [server connection drops](#server_connection_drop)

+* When a network connectivity issue happens between client and SignalR Service

+* When SignalR Service has some internal errors like instance restart, failover, deployment, and so on

+#### Azure Function example

+This issue often occurs when someone establishes a SignalR client connection in an Azure Function method instead of making it a static member in the function class. You might expect only one client connection to be established, but instead you see client connection count increase constantly in metrics. All these connections drop only after the Azure Function or Azure SignalR service restarts. This behavior is because for **each** request, Azure Function creates **one** client connection, and if you don't stop client connection in the function method, the client keeps the connections alive to Azure SignalR service.

+As the connections between the app server and SignalR Service are persistent connections, they may experience network connectivity issues. In the Server SDK, we have an **Always Reconnect** strategy to server connections. As a best practice, we also encourage users to add continuous reconnection logic to the clients with a random delay time to avoid massive simultaneous requests to the server.

+Regularly, there are new version releases for the Azure SignalR Service, and sometimes the Azure-wide patching or upgrades or occasionally interruption from our dependent services. These events may bring in a short period of service disruption, but as long as client-side has a disconnect/reconnect mechanism, the effect is minimal like any client-side caused disconnect-reconnect.

+If your server is starving, that means no threads are working on message processing. All threads aren't responding in a certain method.

+To simplify troubleshooting process, Azure SignalR service provides **live trace tool** to expose service traces on **connectivity** and **messaging** categories. The traces include but aren't limited to connection connected/disconnected events and message received/left events. With **live trace tool**, you can capture, view, sort, filter and export live traces. For more information, see [How to use live trace tool](./signalr-howto-troubleshoot-live-trace.md).

+SignalR *Server* maintains the *Server Connection* between *Server* and *Service*. When the app server starts, it starts the **WebSocket** connection to Azure SignalR service. All the client traffics are routed through Azure SignalR service to these *Server Connection*s and then dispatched to the `Hub`. When a *Server Connection* drops, the clients routed to this *Server Connection* will be impacted. Our Azure SignalR SDK has a logic "Always Retry" to reconnect the *Server Connection* with at most 1-minute delay to minimize the effects.

+*Server Connection*s can drop because of network instability or regular maintenance of Azure SignalR Service, or your hosted app server updates/maintainance. As long as client-side has the disconnect/reconnect mechanism, the effect is minimal like any client-side caused disconnect-reconnect.

+View the server-side network trace to find the status code and error detail why *Server Connection* drops or is rejected by the *Service*. Look for the root cause inside [Troubleshooting Guide](./signalr-howto-troubleshoot-guide.md).

+`Classic` mode is obsoleted and isn't encouraged to use. When in Classic mode, Azure SignalR service uses the connected *Server Connections* to determine if current service is in `default` mode or `serverless` mode. Classic mode can lead to intermediate client connectivity issues because, when there's a sudden drop of all the connected *Server Connection*, for example due to network instability, Azure SignalR believes it's now switched to `serverless` mode, and clients connected during this period will never be routed to the hosted app server. Enable [service-side logs](#add_logs_server) and check if there are any clients recorded as `ServerlessModeEntered` if you have hosted app server, however, some clients never reach the app server side. If you see any of these clients, [abort the client connections](https://github.com/Azure/azure-signalr/blob/dev/docs/rest-api.md#API), and then let the clients restart.

+ * Check the ip-address is same as the ip from portal.

+ * If all above options don't work, contact us by adding new support request in Azure portal.

+Azure Video Indexer supports detection, grouping, and recognition of characters in animated content, this functionality is available through the Azure portal and through API. Review [this overview](animated-characters-recognition.md) article.

+If you own an Azure Video Indexer paid account, you need to connect a Custom Vision account first. If you don't have a Custom Vision account already, create one. For more information, see [Custom Vision](../cognitive-services/custom-vision-service/overview.md).

+The training of the model should be done only via Azure Video Indexer, and not via the Custom Vision website.

+Follow these steps to connect your Custom Vision account to Azure Video Indexer, or to change the Custom Vision account that is currently connected to Azure Video Indexer:

+1. Browse to [www.customvision.ai](https://www.customvision.ai) and sign in.

+1. Select the question mark on the top-right corner of the page and choose **API Reference**.

+1. Make sure you're subscribed to API Management by clicking **Products** tab. If you have an API connected you can continue to the next step, otherwise, subscribe.

+1. On the developer portal, select the **Complete API Reference** and browse to **Operations**.

+1. Select **Connect Custom Vision Account (PREVIEW)** and select **Try it**.

+1. Fill in the required fields and the access token and select **Send**.

+1. Select the **Content model customization** button in the top-right corner.

+1. Once you select Manage models in Custom Vision, you'll be transferred to the Custom Vision account you just connected.

+1. Select **Add model**.

+1. Name your model and select enter to save the name.

+For the initial training, upload at least two videos. Each should be preferably longer than 15 minutes, before expecting good recognition model. If you have shorter episodes, we recommend uploading at least 30 minutes of video content before training. This will allow you to merge groups that belong to the same character from different scenes and backgrounds, and therefore increase the chance it will detect the character in the following episodes you index. To train a model on multiple videos (episodes), you need to index them all with the same animation model.

+1. Select the **Upload** button.

+1. Select **Advanced options**.

+1. Select upload.

+1. Once the video is indexed, you'll see the detected characters in the **Animated characters** section in the **Insights** pane.

+Before tagging and training the model, all animated characters will be named ΓÇ£Unknown #XΓÇ¥. After you train the model, they'll also be recognized.

+ 1. After the model created character group, it's recommended to review these groups in Custom Vision.

+ 1. To tag an animated character in your video, go to the **Insights** tab and select the **Edit** button on the top-right corner of the window.

+ 1. In the **Insights** pane, select any of the detected animated characters and change their names from "Unknown #X" to a temporary name (or the name that was previously assigned to the character).

+ 1. After typing in the new name, select the check icon next to the new name. This saves the new name in the model in Azure Video Indexer.

+ 1. Select the Edit button for the model you're working on to manage it in Custom Vision.

+ * If the group contains unrelated images, it's recommended to delete these in the Custom Vision website.

+ * If there are images that belong to a different character, change the tag on these specific images by select the image, adding the right tag and deleting the wrong tag.

+ * If the group isn't correct, meaning it contains mainly non-character images or images from multiple characters, you can delete in Custom Vision website or in Azure Video Indexer insights.

+ * The grouping algorithm will sometimes split your characters to different groups. It's therefore recommended to give all the groups that belong to the same character the same name (in Azure Video Indexer Insights), which will immediately cause all these groups to appear as on in Custom Vision website.

+ 1. Open the customization page and select the **Animated characters** tab and then select the **Train** button to train your model. In order to keep the connection between Video

+ 1. To delete an animated character in your video insights, go to the **Insights** tab and select the **Edit** button on the top-right corner of the window.

+ 1. Choose the animated character and then select the **Delete** button under their name.

+ 1. Select the **Content model customization** button on the top menu and go to the **Animated characters** tab.

+ 1. Select the ellipsis icon to the right of the model you wish to delete and then on the delete button.

+ * Paid account: the model will be disconnected from Azure Video Indexer and you won't be able to reconnect it.

+ If you donΓÇÖt have a Custom Vision account already, create one. For more information, see [Custom Vision](../cognitive-services/custom-vision-service/overview.md).

+* Currently, the "animation identification" capability isn't supported in East-Asia region.

+## Insights

+Insights contain an aggregated view of the data: faces, topics, emotions. Azure Video Indexer analyzes the video and audio content by running 30+ AI models, generating rich insights. Below is an illustration of the audio and video analysis performed by Azure Video Indexer in the background.

+> [!div class="mx-imgBorder"]

+> :::image type="content" source="./media/video-indexer-overview/model-chart.png" alt-text="Diagram of Azure Video Indexer flow.":::

+

+1. Select *Azure Video Indexer* under *Services*.

+Select *Explore Azure Video Indexer's portal* to view your new account on the [Azure Video Indexer portal](https://aka.ms/vi-portal-link).

+- select if you want Azure Video Indexer to exclude certain brands from being detected (essentially creating a blocklist of brands).

+You can use the Azure Video Indexer website to create, use, and edit custom Brands models detected in a video, as described in this article. You can also use the API, as described in [Customize Brands model using APIs](customize-brands-model-with-api.md).

+You can use the Azure Video Indexer website to edit faces that were detected in a video, as described in this article. You can also use the API, as described in [Customize a Person model using APIs](customize-person-model-with-api.md).

+ Azure Video Indexer can detect occurrences of this person in the future videos that you index and the current videos that you had already indexed, using the Person model to which you added this new face. Recognition of the person in your current videos might take some time to take effect, as this is a batch process.

+To use a Person model to reindex a video in your collection, go to your account videos on the Azure Video Indexer home page, and hover over the name of the video that you want to reindex.

+ Title: Deploy Zerto disaster recovery on Azure VMware Solution

+# Deploy Zerto disaster recovery on Azure VMware Solution

+In this article, you'll learn how to implement disaster recovery for on-premises VMware or Azure VMware Solution-based virtual machines (VMs). The solution in this article uses [Zerto disaster recovery](https://www.zerto.com/solutions/use-cases/disaster-recovery/). Instances of Zerto are deployed at both the protected and the recovery sites.

+Zerto is a disaster recovery solution designed to minimize downtime of VMs should a disaster occur. Zerto's platform is built on the foundation of Continuous Data Protection (CDP) that enables minimal or close to no data loss. The platform provides the level of protection wanted for many business-critical and mission-critical enterprise applications. Zerto also automates and orchestrates failover and failback to ensure minimal downtime in a disaster. Overall, Zerto simplifies management through automation and ensures fast and highly predictable recovery times.

+To learn more about Zerto platform architecture, see the [Zerto Platform Architecture Guide](https://www.zerto.com/wp-content/uploads/2021/07/Zerto-Platform-Architecture-Guide.pdf).

+- Azure VMware Solution private cloud must be deployed in the primary and secondary regions.

+- Network connectivity, ExpressRoute based, from Azure VMware Solution to the vNET used for disaster recovery.

+Currently, Zerto disaster recovery on Azure VMware Solution is in an Initial Availability (IA) phase. In the IA phase, you must contact Microsoft to request and qualify for IA support.

+> As part of the manual installation, Microsoft creates a new vCenter user account for Zerto. This user account is only for Zerto Virtual Manager (ZVM) to perform operations on the Azure VMware Solution vCenter. When installing ZVM on Azure VMware Solution, donΓÇÖt select the ΓÇ£Select to enforce roles and permissions using Zerto vCenter privilegesΓÇ¥ option.

+After the ZVM installation, select the options below from the Zerto Virtual Manager **Site Settings**.

+- As you scale your Azure VMware Solution private cloud operations, you might need to add new Azure VMware Solution hosts for Zerto protection or configure Zerto disaster recovery to new Azure VMware Solution vSphere Clusters. In both these scenarios, you'll be required to open a Support Request with the Azure VMware Solution team in the Initial Availability phase. You can open the [support ticket](https://rc.portal.azure.com/#create/Microsoft.Support) from the Azure portal for these Day 2 configurations.

+ :::image type="content" source="media/zerto-disaster-recovery/support-request-zerto-disaster-recovery.png" alt-text="Screenshot that shows the support request for Day 2 Zerto disaster recovery configurations.":::

+You can reuse pre-existing Zerto product licenses for Azure VMware Solution environments. If you need new Zerto licenses, email Zerto at **info@zerto.com** to acquire new licenses.

+Zerto and Microsoft support teams will engage each other as needed to troubleshoot Zerto disaster recovery issues on Azure VMware Solution.

+To learn about the limits for the VMware Site Recovery Manager Add-On with the Azure VMware Soltuion, check the [Azure subscription and service limits, quotas, and constraints.](/azure/azure-resource-manager/management/azure-subscription-service-limits#azure-vmware-solution-limits)

+ With Azure Monitor, you can collect data from different [sources to monitor and analyze](../azure-monitor/data-sources.md) and different types of [data for analysis, visualization, and alerting](../azure-monitor/data-platform.md). You can also create alert rules to identify issues in your environment, like high use of resources, missing patches, low disk space, and heartbeat of your VMs. You can set an automated response to detected events by sending an alert to IT Service Management (ITSM) tools. Alert detection notification can also be sent via email.

+Can collect data from different [sources to monitor and analyze](../azure-monitor/data-sources.md) and different types of [data for analysis, visualization, and alerting](../azure-monitor/data-platform.md). You can also create alert rules to identify issues in your environment, like high use of resources, missing patches, low disk space, and heartbeat of your VMs. You can set an automated response to detected events by sending an alert to IT Service Management (ITSM) tools. Alert detection notification can also be sent via email.

+1. You can use default name of RG or customize the name according to organizational requirements.

+ >[!Note]

+ >When Azure Backup creates an RG, a numeric is appended to the name of RG and used for restore point collection.

+Disks enabled for access with private EndPoint | Unsupported.

+ Title: Deploy S/4HANA infrastructure (preview)

+description: Learn how to deploy S/4HANA infrastructure with Azure Center for SAP solutions (ACSS) through the Azure portal. You can deploy High Availability (HA), non-HA, and single-server configurations.

+#Customer intent: As a developer, I want to deploy S/4HANA infrastructure using Azure Center for SAP solutions so that I can manage SAP workloads in the Azure portal.

+# Deploy S/4HANA infrastructure with Azure Center for SAP solutions (preview)

+In this how-to guide, you'll learn how to deploy S/4HANA infrastructure in *Azure Center for SAP solutions (ACSS)*. There are [three deployment options](#deployment-types): distributed with High Availability (HA), distributed non-HA, and single server.

+## Prerequisites

+- An Azure subscription.

+- An Azure account with **Contributor** role access to the subscriptions and resource groups in which you'll create the Virtual Instance for SAP solutions (VIS) resource.

+- The ACSS application **Azure SAP Workloads Management** also needs Contributor role access to the resource groups for the SAP system. There are two options to grant access:

+ - If your Azure account has **Owner** or **User Access Admin** role access, you can automatically grant access to the application when deploying or registering the SAP system.

+ - If your Azure account doesn't have Owner or User Access Admin role access, you must enable access for the ACSS application.

+- A [network set up for your infrastructure deployment](prepare-network.md).

+## Deployment types

+There are three deployment options that you can select for your infrastructure, depending on your use case.

+- **Distributed with High Availability (HA)** creates distributed HA architecture. This option is recommended for production environments. If you choose this option, you need to select a **High Availability SLA**. Select the appropriate SLA for your use case:

+ - **99.99% (Optimize for availability)** shows available zone pairs for VM deployment. The first zone is primary and the next is secondary. Active ASCS and Database servers are deployed in the primary zone. Passive ASCS and Database servers are deployed in the secondary zone. Application servers are deployed evenly across both zones. This option isn't shown in regions without availability zones, or without at least one M-series and E-series VM SKU available in the zonal pairs within that region.

+ - **99.95% (Optimize for cost)** shows three availability sets for all instances. The HA ASCS cluster is deployed in the first availability set. All Application servers are deployed across the second availability set. The HA Database server is deployed in the third availability set. No availability zone names are shown.

+- **Distributed** creates distributed non-HA architecture.

+- **Single Server** creates architecture with a single server. This option is available for non-production environments only.

+## Create deployment

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

+1. In the search bar, enter and select **Azure Center for SAP solutions**.

+1. On the ACSS landing page, select **Create a new SAP system**.

+1. On the **Create Virtual Instance for SAP solutions** page, on the **Basics** tab, fill in the details for your project.

+ 1. For **Subscription**, select the Azure subscription into which you're deploying the infrastructure.

+ 1. For **Resource group**, select the resource group for all resources that the VIS creates.

+1. Under **Instance details**, enter the details for your SAP instance.

+ 1. For **Name** enter the three-character SAP system identifier (SID). The VIS uses the same name as the SID.

+ 1. For **Region**, select the Azure region into which you're deploying the resources.

+ 1. For **Environment type**, select whether your environment is production or non-production. If you select **Production**, you can deploy a distributed HA or non-HA S/4HANA system. It's recommended to use distributed HA deployments for production systems. If you select **Non-production**, you can use a single-server deployment.

+ 1. For **SAP product**, keep the selection as **S/4HANA**.

+ 1. For **Database**, keep the selection as **HANA**.

+ 1. For **HANA scale method**, keep the selection as **Scale up**.

+ 1. For **Deployment type**, [select and configure your deployment type](#deployment-types).

+ 1. For **Network**, create the [network you created previously with subnets](prepare-network.md).

+ 1. For **Application subnet** and **Database subnet**, map the IP address ranges as required. It's recommended to use a different subnet for each deployment.

+1. Under **Operating systems**, enter the OS details.

+ 1. For **Application OS image**, select the OS image for the application server.

+ 1. For **Database OS image**, select the OS image for the database server.

+1. Under **Administrator account**, enter your administrator account details.

+ 1. For **Authentication type**, keep the setting as **SSH public**.

+ 1. For **Username**, enter a username.

+ 1. For **SSH public key source**, select a source for the public key. You can choose to generate a new key pair, use an existing key stored in Azure, or use an existing public key stored on your local computer. If you don't have keys already saved, it's recommended to generate a new key pair.

+ 1. For **Key pair name**, enter a name for the key pair.

+1. Select **Next: Virtual machines**.

+1. In the **Virtual machines** tab, generate SKU size and total VM count recommendations for each SAP instance from ACSS.

+ 1. For **Generate Recommendation based on**, under **Get virtual machine recommendations**, select **SAP Application Performance Standard (SAPS)**.

+ 1. For **SAPS for application tier**, provide the total SAPS for the application tier. For example, 30,000.

+ 1. For **Memory size for database (GiB)**, provide the total memory size required for the database tier. For example, 1024. The value must be greater than zero, and less than or equal to 11,400.

+

+ 1. Select **Generate Recommendation**.

+ 1. Review the VM size and count recommendations for ASCS, Application Server, and Database instances.

+ 1. To change a SKU size recommendation, select the drop-down menu or select **See all sizes**. Filter the list or search for your preferred SKU.

+ 1. To change the Application server count, enter a new count for **Number of VMs** under **Application virtual machines**.

+

+ The number of VMs for ASCS and Database instances aren't editable. The default number for each is **2**.

+ ACSS automatically configures a database disk layout for the deployment. To view the layout for a single database server, make sure to select a VM SKU. Then, select **View disk configuration**. If there's more than one database server, the layout applies to each server.

+ 1. Select **Next: Tags**.

+1. Optionally, enter tags to apply to all resources created by the ACSS process. These resources include the VIS, ASCS instances, Application Server instances, Database instances, VMs, disks, and NICs.

+1. Select **Review + Create**.

+1. Review your settings before deployment.

+ 1. Make sure the validations have passed, and there are no errors listed.

+ 1. Review the Terms of Service, and select the acknowledgment if you agree.

+ 1. Select **Create**.

+1. Wait for the infrastructure deployment to complete. Numerous resources are deployed and configured. This process takes approximately 7 minutes.

+## Confirm deployment

+To confirm a deployment is successful:

+1. In the [Azure portal](https://portal.azure.com), search for and select **Virtual Instances for SAP solutions**.

+1. On the **Virtual Instances for SAP solutions** page, select the **Subscription** filter, and choose the subscription where you created the deployment.

+1. In the table of records, find the name of the VIS. The **Infrastructure** column value shows **Deployed** for successful deployments.

+If the deployment fails, delete the VIS resource in the Azure portal, then recreate the infrastructure.

+## Next steps

+- [Install SAP software on your infrastructure](install-software.md)

+ Title: Get quality checks and insights for a Virtual Instance for SAP solutions (preview)

+description: Learn how to get quality checks and insights for a Virtual Instance for SAP solutions (VIS) resource in Azure Center for SAP solutions (ACSS) through the Azure portal.

+#Customer intent: As a developer, I want to use the quality checks feature so that I can learn more insights about virtual machines within my Virtual Instance for SAP resource.

+# Get quality checks and insights for a Virtual Instance for SAP solutions (preview)

+The *Quality Insights* Azure workbook in *Azure Center for SAP solutions (ACSS)* provides insights about the SAP system resources. The feature is part of the monitoring capabilities built in to the *Virtual Instance for SAP solutions (VIS)*. These quality checks make sure that your SAP system uses Azure and SAP best practices for reliability and performance.

+In this how-to guide, you'll learn how to use quality checks and insights to get more information about virtual machine (VM) configurations within your SAP system.