Application Monitoring for Azure App Service and ASP.NET

Enabling monitoring on your ASP.NET based web applications running on Azure App Services is now easier than ever. Whereas previously you needed to manually instrument your app, the latest extension/agent is now built into the App Service image by default. This article will walk you through enabling Azure Monitor Application Insights monitoring as well as provide preliminary guidance for automating the process for large-scale deployments.

Note

Manually adding an Application Insights site extension via Development Tools > Extensions is deprecated. This method of extension installation was dependent on manual updates for each new version. The latest stable release of the extension is now preinstalled as part of the App Service image. The files are located in d:\Program Files (x86)\SiteExtensions\ApplicationInsightsAgent and are automatically updated with each stable release. If you follow the auto-instrumentation instructions to enable monitoring below, it will automatically remove the deprecated extension for you.

Note

If both auto-instrumentation monitoring and manual SDK-based instrumentation are detected, only the manual instrumentation settings will be honored. This is to prevent duplicate data from being sent. To learn more about this, check out the troubleshooting section below.

Note

On March 31, 2025, support for instrumentation key ingestion will end. Instrumentation key ingestion will continue to work, but we'll no longer provide updates or support for the feature. Transition to connection strings to take advantage of new capabilities.

Enable auto-instrumentation monitoring

For a complete list of supported auto-instrumentation scenarios, see Supported environments, languages, and resource providers.

Note

The combination of APPINSIGHTS_JAVASCRIPT_ENABLED and urlCompression is not supported. For more info see the explanation in the troubleshooting section.

  1. Select Application Insights in the Azure control panel for your app service, then select Enable.

    Screenshot of Application Insights tab with enable selected.

  2. Choose to create a new resource, or select an existing Application Insights resource for this application.

    Note

    When you click OK to create the new resource you will be prompted to Apply monitoring settings. Selecting Continue will link your new Application Insights resource to your app service, doing so will also trigger a restart of your app service.

    Screenshot of Change your resource dropdown.

  3. After specifying which resource to use, you can choose how you want application insights to collect data per platform for your application. ASP.NET app monitoring is on-by-default with two different levels of collection.

    Screenshot shows the Application Insights site extensions page with Create new resource selected.

    Below is a summary of data collected for each route:

    Data ASP.NET Basic Collection ASP.NET Recommended collection
    Adds CPU, memory, and I/O usage trends No Yes
    Collects usage trends, and enables correlation from availability results to transactions Yes Yes
    Collects exceptions unhandled by the host process Yes Yes
    Improves APM metrics accuracy under load, when sampling is used Yes Yes
    Correlates micro-services across request/dependency boundaries No (single-instance APM capabilities only) Yes
  4. To configure sampling, which you could previously control via the applicationinsights.config file you can now interact with it via Application settings with the corresponding prefix MicrosoftAppInsights_AdaptiveSamplingTelemetryProcessor.

    • For example, to change the initial sampling percentage, you can create an Application setting of: MicrosoftAppInsights_AdaptiveSamplingTelemetryProcessor_InitialSamplingPercentage and a value of 100.

    • To disable sampling, set MicrosoftAppInsights_AdaptiveSamplingTelemetryProcessor_MinSamplingPercentage to a value of 100.

    • Supported settings include:

      • MicrosoftAppInsights_AdaptiveSamplingTelemetryProcessor_InitialSamplingPercentage
      • MicrosoftAppInsights_AdaptiveSamplingTelemetryProcessor_MinSamplingPercentage
      • MicrosoftAppInsights_AdaptiveSamplingTelemetryProcessor_EvaluationInterval
      • MicrosoftAppInsights_AdaptiveSamplingTelemetryProcessor_MaxTelemetryItemsPerSecond
    • For the list of supported adaptive sampling telemetry processor settings and definitions, you can consult the code and sampling documentation.

Enable client-side monitoring

Client-side monitoring is opt-in for ASP.NET. To enable client-side monitoring:

  • Settings > Configuration
    • Under Application settings, create a new application setting:

      Name: APPINSIGHTS_JAVASCRIPT_ENABLED

      Value: true

    • Save the settings and Restart your app.

To disable client-side monitoring either remove the associated key value pair from the Application settings, or set the value to false.

Automate monitoring

In order to enable telemetry collection with Application Insights, only the Application settings need to be set:

Screenshot of App Service Application Settings with Application Insights settings.

Application settings definitions

App setting name Definition Value
ApplicationInsightsAgent_EXTENSION_VERSION Main extension, which controls runtime monitoring. ~2
XDT_MicrosoftApplicationInsights_Mode In default mode, only essential features are enabled in order to ensure optimal performance. default or recommended.
InstrumentationEngine_EXTENSION_VERSION Controls if the binary-rewrite engine InstrumentationEngine will be turned on. This setting has performance implications and impacts cold start/startup time. ~1
XDT_MicrosoftApplicationInsights_BaseExtensions Controls if SQL & Azure table text will be captured along with the dependency calls. Performance warning: application cold startup time will be affected. This setting requires the InstrumentationEngine. ~1

App Service application settings with Azure Resource Manager

Application settings for Azure App Service can be managed and configured with Azure Resource Manager templates. You can use this method when you deploy new App Service resources with Resource Manager automation or modify the settings of existing resources.

The basic structure of the application settings JSON for an app service:

      "resources": [
        {
          "name": "appsettings",
          "type": "config",
          "apiVersion": "2015-08-01",
          "dependsOn": [
            "[resourceId('Microsoft.Web/sites', variables('webSiteName'))]"
          ],
          "tags": {
            "displayName": "Application Insights Settings"
          },
          "properties": {
            "key1": "value1",
            "key2": "value2"
          }
        }
      ]

For an example of a Resource Manager template with application settings configured for Application Insights, see this template can be helpful. Specifically, see the section that starts on line 238.

To create a Resource Manager template with all the default Application Insights settings configured, begin the process as if you were going to create a new web app with Application Insights enabled.

  1. Create a new App Service resource with your desired web app information. Enable Application Insights on the Monitoring tab.

  2. Select Review + create. Then select Download a template for automation.

    Screenshot that shows the App Service web app creation menu.

    This option generates the latest Resource Manager template with all required settings configured.

    Screenshot that shows an App Service web app template.

In the following sample, replace all instances of AppMonitoredSite with your site name:

{
    "resources": [
        {
            "name": "[parameters('name')]",
            "type": "Microsoft.Web/sites",
            "properties": {
                "siteConfig": {
                    "appSettings": [
                        {
                            "name": "APPINSIGHTS_INSTRUMENTATIONKEY",
                            "value": "[reference('microsoft.insights/components/AppMonitoredSite', '2015-05-01').InstrumentationKey]"
                        },
                        {
                            "name": "APPLICATIONINSIGHTS_CONNECTION_STRING",
                            "value": "[reference('microsoft.insights/components/AppMonitoredSite', '2015-05-01').ConnectionString]"
                        },
                        {
                            "name": "ApplicationInsightsAgent_EXTENSION_VERSION",
                            "value": "~2"
                        }
                    ]
                },
                "name": "[parameters('name')]",
                "serverFarmId": "[concat('/subscriptions/', parameters('subscriptionId'),'/resourcegroups/', parameters('serverFarmResourceGroup'), '/providers/Microsoft.Web/serverfarms/', parameters('hostingPlanName'))]",
                "hostingEnvironment": "[parameters('hostingEnvironment')]"
            },
            "dependsOn": [
                "[concat('Microsoft.Web/serverfarms/', parameters('hostingPlanName'))]",
                "microsoft.insights/components/AppMonitoredSite"
            ],
            "apiVersion": "2016-03-01",
            "location": "[parameters('location')]"
        },
        {
            "apiVersion": "2016-09-01",
            "name": "[parameters('hostingPlanName')]",
            "type": "Microsoft.Web/serverfarms",
            "location": "[parameters('location')]",
            "properties": {
                "name": "[parameters('hostingPlanName')]",
                "workerSizeId": "[parameters('workerSize')]",
                "numberOfWorkers": "1",
                "hostingEnvironment": "[parameters('hostingEnvironment')]"
            },
            "sku": {
                "Tier": "[parameters('sku')]",
                "Name": "[parameters('skuCode')]"
            }
        },
        {
            "apiVersion": "2015-05-01",
            "name": "AppMonitoredSite",
            "type": "microsoft.insights/components",
            "location": "West US 2",
            "properties": {
                "ApplicationId": "[parameters('name')]",
                "Request_Source": "IbizaWebAppExtensionCreate"
            }
        }
    ],
    "parameters": {
        "name": {
            "type": "string"
        },
        "hostingPlanName": {
            "type": "string"
        },
        "hostingEnvironment": {
            "type": "string"
        },
        "location": {
            "type": "string"
        },
        "sku": {
            "type": "string"
        },
        "skuCode": {
            "type": "string"
        },
        "workerSize": {
            "type": "string"
        },
        "serverFarmResourceGroup": {
            "type": "string"
        },
        "subscriptionId": {
            "type": "string"
        }
    },
    "$schema": "https://schema.management.azure.com/schemas/2014-04-01-preview/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0"
}

Enable through PowerShell

To enable the application monitoring through PowerShell, only the underlying application settings must be changed. The following sample enables application monitoring for a website called AppMonitoredSite in the resource group AppMonitoredRG. It configures data to be sent to the 012345678-abcd-ef01-2345-6789abcd instrumentation key.

Note

We recommend that you use the Azure Az PowerShell module to interact with Azure. See Install Azure PowerShell to get started. To learn how to migrate to the Az PowerShell module, see Migrate Azure PowerShell from AzureRM to Az.

$app = Get-AzWebApp -ResourceGroupName "AppMonitoredRG" -Name "AppMonitoredSite" -ErrorAction Stop
$newAppSettings = @{} # case-insensitive hash map
$app.SiteConfig.AppSettings | %{$newAppSettings[$_.Name] = $_.Value} # preserve non Application Insights application settings.
$newAppSettings["APPINSIGHTS_INSTRUMENTATIONKEY"] = "012345678-abcd-ef01-2345-6789abcd"; # set the Application Insights instrumentation key
$newAppSettings["APPLICATIONINSIGHTS_CONNECTION_STRING"] = "InstrumentationKey=012345678-abcd-ef01-2345-6789abcd"; # set the Application Insights connection string
$newAppSettings["ApplicationInsightsAgent_EXTENSION_VERSION"] = "~2"; # enable the ApplicationInsightsAgent
$app = Set-AzWebApp -AppSettings $newAppSettings -ResourceGroupName $app.ResourceGroup -Name $app.Name -ErrorAction Stop

Upgrade monitoring extension/agent - .NET

Upgrade from versions 2.8.9 and up

Upgrading from version 2.8.9 happens automatically, without any extra actions. The new monitoring bits are delivered in the background to the target app service, and on application restart they'll be picked up.

To check which version of the extension you're running, go to https://yoursitename.scm.azurewebsites.net/ApplicationInsights.

Screenshot of the URL path to check the version of the extension you're running.

Upgrade from versions 1.0.0 - 2.6.5

Starting with version 2.8.9 the pre-installed site extension is used. If you're an earlier version, you can update via one of two ways:

  • Upgrade by enabling via the portal. (Even if you have the Application Insights extension for Azure App Service installed, the UI shows only Enable button. Behind the scenes, the old private site extension will be removed.)

  • Upgrade through PowerShell:

    1. Set the application settings to enable the pre-installed site extension ApplicationInsightsAgent. See Enable through PowerShell.
    2. Manually remove the private site extension named Application Insights extension for Azure App Service.

If the upgrade is done from a version prior to 2.5.1, check that the ApplicationInsigths dlls are removed from the application bin folder see troubleshooting steps.

Troubleshooting

Note

When you create a web app with the ASP.NET runtimes in Azure App Services it deploys a single static HTML page as a starter website. It is not recommended to troubleshoot an issue with default template. Deploy an application before troubleshooting an issue.

Below is our step-by-step troubleshooting guide for extension/agent based monitoring for ASP.NET based applications running on Azure App Services.

  1. Check that ApplicationInsightsAgent_EXTENSION_VERSION app setting is set to a value of "~2".

  2. Browse to https://yoursitename.scm.azurewebsites.net/ApplicationInsights.

    Screenshot of the link above results page.

    • Confirm that the Application Insights Extension Status is Pre-Installed Site Extension, version 2.8.x.xxxx, is running.

      If it isn't running, follow the enable Application Insights monitoring instructions.

    • Confirm that the status source exists and looks like: Status source D:\home\LogFiles\ApplicationInsights\status\status_RD0003FF0317B6_4248_1.json

      If a similar value isn't present, it means the application isn't currently running or isn't supported. To ensure that the application is running, try manually visiting the application url/application endpoints, which will allow the runtime information to become available.

    • Confirm that IKeyExists is true If not, add APPINSIGHTS_INSTRUMENTATIONKEY and APPLICATIONINSIGHTS_CONNECTION_STRING with your ikey guid to your application settings.

    • Confirm that there are no entries for AppAlreadyInstrumented, AppContainsDiagnosticSourceAssembly, and AppContainsAspNetTelemetryCorrelationAssembly.

      If any of these entries exist, remove the following packages from your application: Microsoft.ApplicationInsights, System.Diagnostics.DiagnosticSource, and Microsoft.AspNet.TelemetryCorrelation.

Default website deployed with web apps does not support automatic client-side monitoring

When you create a web app with the ASP.NET runtimes in Azure App Services it deploys a single static HTML page as a starter website. The static webpage also loads a ASP.NET managed web part in IIS. This allows for testing codeless server-side monitoring, but doesn't support automatic client-side monitoring.

If you wish to test out codeless server and client-side monitoring for ASP.NET in an Azure App Services web app, we recommend following the official guides for creating an ASP.NET Framework web app and then use the instructions in the current article to enable monitoring.

APPINSIGHTS_JAVASCRIPT_ENABLED and urlCompression isn't supported

If you use APPINSIGHTS_JAVASCRIPT_ENABLED=true in cases where content is encoded, you might get errors like:

  • 500 URL rewrite error
  • 500.53 URL rewrite module error with message Outbound rewrite rules can't be applied when the content of the HTTP response is encoded ('gzip').

This is due to the APPINSIGHTS_JAVASCRIPT_ENABLED application setting being set to true and content-encoding being present at the same time. This scenario isn't supported yet. The workaround is to remove APPINSIGHTS_JAVASCRIPT_ENABLED from your application settings. Unfortunately this means that if client/browser-side JavaScript instrumentation is still required, manual SDK references are needed for your webpages. Follow the instructions for manual instrumentation with the JavaScript SDK.

For the latest information on the Application Insights agent/extension, check out the release notes.

Connection string and instrumentation key

When codeless monitoring is being used, only the connection string is required. We still recommend that you set the instrumentation key to preserve backward compatibility with older versions of the SDK when manual instrumentation is being performed.

What's the difference between standard metrics from Application Insights vs. Azure App Service metrics?

Application Insights collects telemetry for the requests that made it to the application. If the failure occurred in WebApps/WebServer, and the request didn't reach the user application, Application Insights won't have any telemetry about it.

The duration for serverresponsetime calculated by Application Insights won't necessarily match the server response time observed by Web Apps. This behavior is because Application Insights only counts the duration when the request actually reaches the user application. If the request is stuck or queued in WebServer, the waiting time will be included in the Web Apps metrics but not in Application Insights metrics.

Test connectivity between your application host and the ingestion service

Application Insights SDKs and agents send telemetry to get ingested as REST calls to our ingestion endpoints. You can test connectivity from your web server or application host machine to the ingestion service endpoints by using raw REST clients from PowerShell or curl commands. See Troubleshoot missing application telemetry in Azure Monitor Application Insights.

PHP and WordPress are not supported

PHP and WordPress sites are not supported. There is currently no officially supported SDK/agent for server-side monitoring of these workloads. However, manually instrumenting client-side transactions on a PHP or WordPress site by adding the client-side JavaScript to your web pages can be accomplished by using the JavaScript SDK.

The table below provides a more detailed explanation of what these values mean, their underlying causes, and recommended fixes:

Problem Value Explanation Fix
AppAlreadyInstrumented:true This value indicates that the extension detected that some aspect of the SDK is already present in the Application, and will back-off. It can be due to a reference to System.Diagnostics.DiagnosticSource, Microsoft.AspNet.TelemetryCorrelation, or Microsoft.ApplicationInsights Remove the references. Some of these references are added by default from certain Visual Studio templates, and older versions of Visual Studio may add references to Microsoft.ApplicationInsights.
AppAlreadyInstrumented:true This value can also be caused by the presence of the above dlls in the app folder from a previous deployment. Clean the app folder to ensure that these dlls are removed. Check both your local app's bin directory, and the wwwroot directory on the App Service. (To check the wwwroot directory of your App Service web app: Advanced Tools (Kudu) > Debug console > CMD > home\site\wwwroot).
AppContainsAspNetTelemetryCorrelationAssembly: true This value indicates that extension detected references to Microsoft.AspNet.TelemetryCorrelation in the application, and will back-off. Remove the reference.
AppContainsDiagnosticSourceAssembly**:true This value indicates that extension detected references to System.Diagnostics.DiagnosticSource in the application, and will back-off. For ASP.NET remove the reference.
IKeyExists:false This value indicates that the instrumentation key isn't present in the AppSetting, APPINSIGHTS_INSTRUMENTATIONKEY. Possible causes: The values may have been accidentally removed, forgot to set the values in automation script, etc. Make sure the setting is present in the App Service application settings.

System.IO.FileNotFoundException after 2.8.44 upgrade

2.8.44 version of auto instrumentation upgrades Application Insights SDK to 2.20.0. Application Insights SDK has an indirect reference to System.Runtime.CompilerServices.Unsafe.dll through System.Diagnostics.DiagnosticSource.dll. If application has binding redirect for System.Runtime.CompilerServices.Unsafe.dll and if this library is not present in application folder it may throw System.IO.FileNotFoundException.

To resolve this issue, remove the binding redirect entry for System.Runtime.CompilerServices.Unsafe.dll from web.config file. If the application wanted to use System.Runtime.CompilerServices.Unsafe.dll then set the binding redirect as below.

<dependentAssembly>
	<assemblyIdentity name="System.Runtime.CompilerServices.Unsafe" publicKeyToken="b03f5f7f11d50a3a" culture="neutral" />
	<bindingRedirect oldVersion="0.0.0.0-4.0.4.1" newVersion="4.0.4.1" />
</dependentAssembly>

As a temporary workaround, you could set the app setting, ApplicationInsightsAgent_EXTENSION_VERSION to a value of 2.8.37. This will trigger App Service to use the old Application Insights extension. Please note that temporary mitigations should only be used as an interim.

Release notes

For the latest updates and bug fixes consult the release notes.

Next steps