Enable application monitoring in Azure App Service for .NET, Node.js, Python, and Java applications

  • Article

Autoinstrumentation, also referred to as runtime monitoring, is the easiest way to enable Application Insights for Azure App Service without requiring any code changes or advanced configurations. Based on your specific scenario, evaluate whether you require more advanced monitoring through manual instrumentation.

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 Application Insights

Important

If both autoinstrumentation monitoring and manual SDK-based instrumentation are detected, only the manual instrumentation settings are honored. This arrangement prevents duplicate data from being sent. To learn more, see Troubleshooting.

Note

Autoinstrumentation in the Azure portal

  1. Select Application Insights in the left-hand navigation menu of your app service, then select Enable.

    Screenshot that shows the Application Insights tab with Enable selected.

  2. Create a new resource or select an existing Application Insights resource for this application.

    Note

    When you select OK to create a new resource, you're prompted to Apply monitoring settings. Selecting Continue links your new Application Insights resource to your app service. Your app service then restarts.

    Screenshot that shows the Change your resource dropdown.

  3. After you specify which resource to use, you can choose how you want Application Insights to collect data per platform for your application. ASP.NET Core collection options are Recommended or Disabled.

    Screenshot that shows instrumenting your application section.

Manually upgrade the monitoring extension/agent

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 are picked up on application restart.

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

Screenshot that shows 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 preinstalled site extension is used. If you're using an earlier version, you can update via one of two ways:

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

  • Upgrade through PowerShell:

    1. Set the application settings to enable the preinstalled site extension ApplicationInsightsAgent. For more information, 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 before 2.5.1, check that the ApplicationInsights DLLs are removed from the application bin folder. For more information, see Troubleshooting.

Configure the monitoring extension/agent

We currently don't offer options to configure the monitoring extension for ASP.NET Core.

Enable client-side monitoring

Client-side monitoring is enabled by default for ASP.NET Core apps with Recommended collection, regardless of whether the app setting APPINSIGHTS_JAVASCRIPT_ENABLED is present.

If you want to disable client-side monitoring:

  1. Select Settings > Configuration.

  2. Under Application settings, create a New application setting with the following information:

    • Name: APPINSIGHTS_JAVASCRIPT_ENABLED
    • Value: false

  3. Save the settings. Restart your app.

Automate monitoring

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

Screenshot that shows 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 for Windows or ~3 for Linux
XDT_MicrosoftApplicationInsights_Mode In default mode, only essential features are enabled to ensure optimal performance. disabled or recommended.
XDT_MicrosoftApplicationInsights_PreemptSdk For ASP.NET Core apps only. Enables Interop (interoperation) with the Application Insights SDK. Loads the extension side by side with the SDK and uses it to send telemetry. (Disables the Application Insights SDK.) 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 resource:

      "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, this template can be helpful. Specifically, see the section that starts on line 238.

To create a Resource Manager template with the default Application Insights settings, 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:

Note

If using Windows, set ApplicationInsightsAgent_EXTENSION_VERSION to ~2. If using Linux, set ApplicationInsightsAgent_EXTENSION_VERSION to ~3.

{
    "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": "China North 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. To get started, see Install Azure PowerShell. To learn how to migrate to the Az PowerShell module, see Migrate Azure PowerShell from AzureRM to Az.

Note

If using Windows, set ApplicationInsightsAgent_EXTENSION_VERSION to ~2. If using Linux, set ApplicationInsightsAgent_EXTENSION_VERSION to ~3.

$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

Frequently asked questions

This section provides answers to common questions.

What does Application Insights modify in my project?

The details depend on the type of project. The following list is an example for a web application.

  • Adds files to your project:

    • ApplicationInsights.config
    • ai.js

  • Installs NuGet packages:

    • Application Insights API: The core API
    • Application Insights API for Web Applications: Used to send telemetry from the server
    • Application Insights API for JavaScript Applications: Used to send telemetry from the client

  • Includes assemblies in packages:

    • Microsoft.ApplicationInsights
    • Microsoft.ApplicationInsights.Platform

  • Inserts items into:

    • Web.config
    • packages.config

  • Inserts snippets into the client and server code to initialize them with the Application Insights resource ID. For example, in an MVC app, code is inserted into the main page Views/Shared/_Layout.cshtml. For new projects only, you add Application Insights to an existing project manually.

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 occurs in WebApps/WebServer, and the request didn't reach the user application, Application Insights doesn't have any telemetry about it.

The duration for serverresponsetime calculated by Application Insights doesn'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 is included in the Web Apps metrics but not in Application Insights metrics.

Troubleshooting

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.

Note

When you create a web app with the ASP.NET Core runtimes in App Service, it deploys a single static HTML page as a starter website. We do not recommend that you troubleshoot an issue with the default template. Deploy an application before you troubleshoot an issue.

Missing telemetry

Windows

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

  2. Browse to https://yoursitename.scm.chinacloudsites.cn/ApplicationInsights.

    Screenshot that shows the link above the results page.

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

      If it isn't running, follow the instructions in the section Enable Application Insights monitoring.

    • 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 allows the runtime information to become available.

    • Confirm that IKeyExists is True. If it's False, add APPINSIGHTS_INSTRUMENTATIONKEY and APPLICATIONINSIGHTS_CONNECTION_STRING with your ikey GUID to your application settings.

    • If your application refers to any Application Insights packages, enabling the App Service integration might not take effect, and the data might not appear in Application Insights. An example would be if you previously instrumented, or attempted to instrument, your app with the ASP.NET Core SDK. To fix the issue, in the Azure portal, turn on Interop with Application Insights SDK.

      Important

      This functionality is in preview.

      Screenshot that shows the interop setting enabled.

      The data is sent using a codeless approach, even if the Application Insights SDK was originally used or attempted to be used.

      Important

      If the application used the Application Insights SDK to send any telemetry, the telemetry will be disabled. In other words, custom telemetry (for example, any Track*() methods) and custom settings (such as sampling) will be disabled.

Linux

  1. Check that the ApplicationInsightsAgent_EXTENSION_VERSION app setting is set to a value of ~3.

  2. Browse to https://your site name.scm.chinacloudsites.cn/ApplicationInsights.

  3. Within this site, confirm:

    • The status source exists and looks like Status source /var/log/applicationinsights/status_abcde1234567_89_0.json.
    • The value Auto-Instrumentation enabled successfully is displayed. If a similar value isn't present, it means the application isn't running or isn't supported. To ensure that the application is running, try manually visiting the application URL/application endpoints, which allows the runtime information to become available.
    • IKeyExists is True. If it's False, add APPINSIGHTS_INSTRUMENTATIONKEY and APPLICATIONINSIGHTS_CONNECTION_STRING with your ikey GUID to your application settings.

    Screenshot that shows the autoinstrumentation status webpage.

Default website deployed with web apps doesn't support automatic client-side monitoring

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

If you want to test out codeless server and client-side monitoring for ASP.NET Core in an App Service web app, we recommend following the official guides for creating an ASP.NET Core web app. Afterwards, use the instructions in the current article to enable monitoring.

PHP and WordPress aren't supported

PHP and WordPress sites aren't supported. There's currently no officially supported SDK/agent for server-side monitoring of these workloads. To track client-side transactions on a PHP or WordPress site, add the client-side JavaScript to your webpages using the JavaScript SDK.

The following table provides an 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 some aspect of the SDK already present in the application and backs off. A reference to Microsoft.ApplicationInsights.AspNetCore or Microsoft.ApplicationInsights can cause this value. Remove the references. Some of these references are added by default from certain Visual Studio templates. Older versions of Visual Studio reference Microsoft.ApplicationInsights.
AppAlreadyInstrumented:true The presence of Microsoft.ApplicationsInsights DLL in the app folder from a previous deployment can also cause this value. 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, select Advanced Tools (Kudu) > Debug console > CMD > home\site\wwwroot).
IKeyExists:false This value indicates that the instrumentation key isn't present in the app setting APPINSIGHTS_INSTRUMENTATIONKEY. Possible causes include accidentally removing the values or forgetting to set the values in automation script. Make sure the setting is present in the App Service application settings.

Release notes

This section contains the release notes for Azure App Service based on ANT release for runtime instrumentation with Application Insights.

To find which version of the extension you're currently using, go to https://<yoursitename>.scm.chinacloudsites.cn/ApplicationInsights.

2.8.44

2.8.43

  • Separate .NET/.NET Core, Java, and Node.js package into different App Service Windows Site Extension.

2.8.42

2.8.41

  • Removed out-of-support version (2.1). Supported versions are 3.1 and 5.0.

2.8.39

  • Added .NET Core 5.0 support.

2.8.38

  • Removed out-of-support versions (2.0, 2.2, 3.0). Supported versions are 2.1 and 3.1.

2.8.37

  • AppSvc Windows extension: Made .NET Core work with any version of System.Diagnostics.DiagnosticSource.dll.

2.8.36

  • AppSvc Windows extension: Enabled Inter-op with AI SDK in .NET Core.

2.8.35

  • AppSvc Windows extension: Added .NET Core 3.1 support.

2.8.33

  • .NET, .NET core, Java, and Node.js agents and the Windows Extension: Support for sovereign clouds. Connections strings can be used to send data to sovereign clouds.

2.8.31

  • The ASP.NET Core agent fixed an issue with the Application Insights SDK. If the runtime loaded the incorrect version of System.Diagnostics.DiagnosticSource.dll, the codeless extension doesn't crash the application and backs off. To fix the issue, customers should remove System.Diagnostics.DiagnosticSource.dll from the bin folder or use the older version of the extension by setting ApplicationInsightsAgent_EXTENSIONVERSION=2.8.24. If they don't, application monitoring isn't enabled.

2.8.26

  • Fixed issue related to updated Application Insights SDK. The agent doesn't try to load AiHostingStartup if the ApplicationInsights.dll is already present in the bin folder. It resolves issues related to reflection via Assembly<AiHostingStartup>.GetTypes().

  • Known issues: Exception System.IO.FileLoadException: Could not load file or assembly 'System.Diagnostics.DiagnosticSource, Version=4.0.4.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51' could be thrown if another version of DiagnosticSource dll is loaded. It could happen, for example, if System.Diagnostics.DiagnosticSource.dll is present in the publish folder. As mitigation, use the previous version of extension by setting app settings in app services: ApplicationInsightsAgent_EXTENSIONVERSION=2.8.24.

2.8.24

  • Repackaged version of 2.8.21.

2.8.23

  • Added ASP.NET Core 3.0 codeless monitoring support.

  • Updated ASP.NET Core SDK to 2.8.0 for runtime versions 2.1, 2.2 and 3.0. Apps targeting .NET Core 2.0 continue to use 2.1.1 of the SDK.

2.8.14

  • Updated ASP.NET Core SDK version from 2.3.0 to the latest (2.6.1) for apps targeting .NET Core 2.1, 2.2. Apps targeting .NET Core 2.0 continue to use 2.1.1 of the SDK.

2.8.12

  • Support for ASP.NET Core 2.2 apps.

  • Fixed a bug in ASP.NET Core extension causing injection of SDK even when the application is already instrumented with the SDK. For 2.1 and 2.2 apps, the presence of ApplicationInsights.dll in the application folder now causes the extension to back off. For 2.0 apps, the extension backs off only if ApplicationInsights is enabled with a UseApplicationInsights() call.

  • Permanent fix for incomplete HTML response for ASP.NET Core apps. This fix is now extended to work for .NET Core 2.2 apps.

  • Added support to turn off JavaScript injection for ASP.NET Core apps (APPINSIGHTS_JAVASCRIPT_ENABLED=false appsetting). For ASP.NET core, the JavaScript injection is in "Opt-Out" mode by default, unless explicitly turned off. (The default setting is done to retain current behavior.)

  • Fixed ASP.NET Core extension bug that caused injection even if ikey wasn't present.

  • Fixed a bug in the SDK version prefix logic that caused an incorrect SDK version in telemetry.

  • Added SDK version prefix for ASP.NET Core apps to identify how telemetry was collected.

  • Fixed SCM- ApplicationInsights page to correctly show the version of the preinstalled extension.

2.8.10

  • Fix for incomplete HTML response for ASP.NET Core apps.

Next steps