12 minute readApplies to: v4

How to use the Azure Application Insights tile

The Azure Application Insights tile is a Squared Up feature that enables you to view Azure App Insights data within your Squared Up dashboards.

Overview

The Azure App Insights tile allows you to query App Insights for data (both stand-alone and in the context of objects within SCOM) and display that information as part of your Squared Up dashboard.

Using this tile you can unify data held within SCOM and Azure on the same screen to bring all collected monitoring information together into a single pane of glass.

The ability to render information as a graph is a feature of the Azure portal rather than the App Insights Query language itself. At this time any queries run using the render statement will still return tabular or scalar data rather than graphs, depending on the tile.

Prerequisites

  • Squared Up v4 with an Enterprise Application Monitoring licence - this gives you the Azure App Insights tiles. See An Overview of Squared Up Licensing for more information
  • A Microsoft Azure App Insights Application
  • Azure subscription administrator role
  • Azure Active Directory User administrator role
  • If you use a proxy server you may need to configure the proxy to allow the Web API tile to communicate with Application Insights.

Connecting Squared Up to Azure App Insights is a simple procedure, but requires some one-time configuration in your Azure Active Directory (AAD) environment prior to making a Squared Up provider. These settings will enable permissions and connectivity for API access, and only need to be performed once regardless of the number of Squared Up instances you have.

Configure Azure Active Directory

In order for Squared Up to authenticate and access App Insights data you must create an Azure AD application that represents Squared Up and configure an SPN for that application with the appropriate permissions to access App Insights data for your applications(s).

In order to complete the Azure Active Directory configuration process, you will need to have Administrative permissions over Azure AD.

A. Add App Insights as a new Service Principal in your Azure Active Directory

This step is required to ensure that your Azure Active Directory is setup to interact with the App Insights API.

Adding the Service Principal is a one-time operation.

First, you will need to find your Azure Active Directory Tenant ID, and then create a new App Insights API Service Principal. The instructions below assume you have PowerShell v4 or later installed (if not, you can use the in-browser PowerShell session right from the Azure Portal).

  1. In the Azure Portal, open your Azure Active Directory resource. From here, click properties.

  2. Take note of the Directory ID as you will need it later. (This will be entered as the azure active directory id on the azure app insights provider page later).

    Azure Active Directory Tenant ID

  3. Start a new PowerShell prompt, and type in the below (where <AAD Tenant Directory ID> is the ID located in the previous step):

    Install-Module AzureAD

    Connect-AzureAD -TenantId <AAD Tenant Directory ID> -Credential (get-credential)

  4. You will get a prompt to log in using your Azure credentials.

  5. Execute the following command:

    New-AzureADServicePrincipal -AppId f5c26e74-f226-4ae8-85f0-b4af0080ac9e -DisplayName "Application Insights API"

B. Create an Azure Active Directory Application

In this step, you will create an AAD application, which Squared Up will use to authenticate against your AAD. If you have previously used the v3 OMS tile in this AD Tenant, you can use the existing application that was created for that tile (skip this section).

  1. Open your Azure Active Directory resource in the Azure Portal and click on App registrations.
  2. Click New application registration.
  3. Give your application a name (such as SquaredUp). Make sure the application type is set to Web app/API. Finally, enter a sign-on URL for Squared Up. This must be unique, but is only used if someone clicks on a link to the application within Azure. If you do not wish to enter your URL here, you can put in a dummy value such as http://squaredup.local/.
  4. Click create.

C. Allow the Application to access App Insights data

  1. Open the Azure Active Directory resource and under the App registrations page, find your Squared Up app, and click on it to open its details page.
  2. Take note of the Application ID as you will need it later. (This will be entered as the active directory application id on the azure app insights provider page later).
  3. Click settings then click required permissions.
  4. On the required permissions page, click add.
  5. On the Add API Access wizard, select the Service Principal you created in the first section of these instructions (i.e. Application Insights API).
  6. Next, in step 2 of the wizard, ensure that Read App Insights data as user is checked under Delegated Permissions. Click Select and then complete the add API access process by clicking Done.
  7. The last step to get your AAD application configured is to create an API access key. Back in the Settings page for our AD Application, click on Keys. Give your key a name and an expiry date and press Save. Your API Key will be generated and displayed - make sure to copy it down, as it cannot be retrieved once you navigate away from the page. (This will be entered as the application key on the azure app insights provider page later).

You now have an application that will allow us to authenticate against your Azure Active Directory!

D. Grant access from your Azure AD application to App Insights applications

In this step you will allow the Azure AD application to access App Insights applications. This step will need to be repeated on each App Insights app you want to query using Squared Up.

  1. Find your Application Insights resource on the Azure Portal.
  2. Click on API Access
  3. Take note of the Application ID, as you will need it later. (This will be entered as the application id (app insights application to query) on the azure app insights provider page later).
  4. Next, click on Access Control (IAM) and then Add.
  5. Set the Role to Reader.
  6. On the Select dropdown list click on the AAD application created earlier, and make sure it appears under Selected members.
  7. Click Save.

Walkthrough: In Squared Up create an Azure App Insights provider

Now that Squared Up has an identity within Azure Active Directory that it can use to query App Insights apps, you need to provide the details to Squared Up. A provider defines the App Insights Application that you wish to query, and the identity used for doing so (in this case, the Azure AD Application authenticates to query App Insights as the user who authorises the provider).

If you have multiple apps that you want to query, you can either create multiple providers (one per app) and/or create an empty App Insights app for use with the provider, and then use the additional applications option in each tile to query up to 10 apps simultaneously.

Create provider for a App Insights Application

  1. Log on to Squared Up and navigate to the right-hand menu ☰ then system and then click on the web api perspective.
  2. Click add new provider.
  3. Change the provider type to azure App Insights and type in a suitable name, e.g. SalesApp.
  4. In the application id box enter the App Insights Application ID you noted down in section D above.
  5. In the azure active directory id box enter the Azure Active Directory Tenant ID you noted down in section A above.
  6. In the active directory application id box enter the Azure Active Directory Application ID you noted down at the beginning of section C above.
  7. In the application key box enter the application API access key you noted down at the end of section C above.
  8. Click add provider.

Add ReplyUrl to Azure AD Application and authorise provider

Once the provider is created, the final step is to authorise it within Azure AD. These credentials are sent to Azure AD and are not stored anywhere within Squared Up.

  1. Note down the reply url listed under the newly created provider.
  2. In the Azure Portal, click on the Azure Active Directory resource and under the App registrations page, find your Squared Up app, and click on it to open it's details page.
  3. Click on Reply URLs.
  4. Add the URL from step 1 to the list of URLs and click Save.
  5. Wait a few minutes for the Azure AD to process the update, then back in Squared Up click perform authorization under the newly created provider.

If you do not want to repeatedly add a reply URL to the application for each new provider, you can specify a wildcard when configuring the reply URL using a * (e.g. https://squaredup.local/*).

Walkthrough: Create tiles to query data

Now that you have an authorised provider, you can start to create App Insights tiles to perform our queries. It's useful to use the Azure portal to prepare and test your queries first, see the links at the bottom of this article for further information. For this walkthrough, you are going to query response time performance information aggregated into hourly values.

Sample: Query request performance information

  1. Add an Azure App Insights (grid) tile to a dashboard and under provider select the provider you created in the previous section.

  2. On the Query panel, enter the following App Insights Query:

    requests
    | summarize percentiles(duration, 50, 90, 95) by bin(timestamp, 1h)
  3. Leave the timeframe on 24 hours. For other queries, be careful with extending the timeframe beyond 7 days, as this may pull many thousands of log entries and significantly impact browser performance.

  4. Configure the desired columns on the grid columns panel. As a best practise, once you know which columns you want to display, modify the query to only return those columns (via project or project away), as it will improve performance when loading and displaying the tile.

  5. You can customise the appearance of columns by clicking the edit link next to it's name in the grid columns panel and then specifying a custom template. For example, locate the timestamp column and set the template to {{timeago(value)}} to show a friendly time in the form Last x minutes rather than the specific time. For more information see How to use the Grid designer when configuring tile.

  6. Click done.

The App Insights query language (AIQL) is very rich and offers features such as sorting, projection and calculated values, which you can use to control the display of data in your dashboard.

Restricting data to a specific timeframe

By default the tile will not return any entries older than 24 hours. You can use the timeframe panel to control this behaviour and select various values. If you attempt to load a large timeframe that may contain many thousands of records, this may cause significant browser delays. You can also include further timeframe restrictions in your query (such as where timestamp >= ago(2h)) if you need more granularity, but be aware events must satisfy both where clauses and the timeframe settings).

Querying multiple (cross-resource) applications

The Azure App Insights API allows you to send a query to multiple apps simultaneously using implicit and explicit cross-resource unions. The App Insights tile supports both mechanisms, with implicit being easier but explicit offering more control over how data is returned. Regardless of which mechanism you use, you may only query across 10 apps with a single cross-resource query (and therefore a single tile), and the provider's configured app is always used.

Identifying resources

In order to specify another application, you will need to specify one of the below identifiers (all are supported):

  • Resource name: The human readable name of the resource. If used this must be unique to all Azure subscriptions the provider has access to or the query will fail as ambiguous.
  • Qualified name: The "full name" of the application, in the format <subscriptionName>/<resourceGroup>/<applicationName>. This may still be ambiguous as subscription names are not unique, but it is extremely unlikely.
  • Application ID: This is a GUID (e.g. b438b4f6-912a-46d5-9cb1-b44069212ab4) and is completely unique and unambiguous.
  • Azure Resource ID: This is a string in the form /subscriptions/<subscriptionId>/resourcegroups/<resourceGroup>/providers/microsoft.operationalinsights/applications/<applicationName>, which whilst unambiguous is extremely long and difficult to work with.

Implicit Unions

When making use of implicit unions, you provide a query to the tile and specify up to 9 other additional app identifiers. The query is automatically sent to the provider's configured app and any others you specify, and the output joined together in a single result for further processing. To configure an implicit cross-resource query:

  1. In the query panel in the Azure App Insights tile click add under additional applications.
  2. Enter an identifier for your second app (using any of the formats discussed above) and press enter or deselect the text box.
  3. Either repeat the process by clicking add again and adding additional apps, or click next and continue to configure the tile.

Explicit Unions

In contrast to implicit unions, explicit unions are specified directly within your query using the Union statement, and allow you to pull in a specific subset of the data in the other apps. The example below shows results from the provider's app, along with only GET request exceptions from another named contosoretail:

  union exceptions, (app("contosoretail").exceptions | where operation_Name contains "GET" )
    | summarize count() by problemId

For further information check out this Azure blog post on Querying across resources.

Troubleshooting

Attempts to authorise the provider fail

Ensure that you have added the Reply URL to the Azure AD application, and that you have given Azure enough time to replicate the configuration (often takes several minutes).

Azure App Insights Query Language

An Overview of Squared Up Licensing

How to use the Grid designer when configuring tile

Querying across resources

Squared Up Ltd. (c) 2018Report an issue with this article