Povratne informacije Uredi

Application Monitoring for Azure App Service and ASP.NET Core

  • Članak
  • 11 min. za čitanje

Enabling monitoring on your ASP.NET Core 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

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

Important

Only .NET Core LTS is supported for auto-instrumentation on Windows.

Note

Auto-instrumentation used to be known as "codeless attach" before October 2021.

Trim self-contained deployments is not supported. Use manual instrumentation via code instead.

See the enable monitoring section below to begin setting up Application Insights with your App Service resource.

Enable monitoring

  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 Core offers Recommended collection or Disabled.

    Screenshot of instrument your application section.

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 for some reason you would like to disable client-side monitoring:

  • Settings > Configuration

    • Under Application settings, create a new application setting:

      name: APPINSIGHTS_JAVASCRIPT_ENABLED

      Value: false

    • Save the settings and Restart your app.

Automate monitoring

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 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 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 App Services can be managed and configured with Azure Resource Manager templates. This method can be used when deploying new App Service resources with Azure Resource Manager automation, or for modifying the settings of existing resources.

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

      "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 an Azure Resource Manager template with Application settings configured for Application Insights, this template can be helpful, specifically the section starting on line 238.

To create an Azure 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. Enabled Application Insights on the Monitoring tab.

  2. Select Review +create then Download a template for automation at the bottom.

    Screenshot of App Service web app creation menu.

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

    Screenshot of App Service web app template.

Below is a 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

In order to enable the application monitoring through PowerShell, only the underlying application settings need to be changed. Below is a sample, which enables application monitoring for a website called "AppMonitoredSite" in the resource group "AppMonitoredRG", and configures data to be sent to the "012345678-abcd-ef01-2345-6789abcd" instrumentation key.

Note

This article uses the Azure Az PowerShell module, which is the recommended PowerShell module for interacting with Azure. To get started with the Az PowerShell module, see Install Azure PowerShell. 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 using 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 Core 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 Core 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 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 may not take effect and the data may not appear in Application Insights. An example would be if you've previously instrumented, or attempted to instrument, your app with the ASP.NET Core SDK. To fix the issue, in portal turn on "Interop with Application Insights SDK" and you'll start seeing the data in Application Insights.

    • Important

      This functionality is in preview

      Screenshot of interop setting enabled.

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

      Important

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

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 Azure App Services, 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 wish to test out codeless server and client-side monitoring for ASP.NET Core in an Azure App Services web app, we recommend following the official guides for creating a ASP.NET Core web app. Then use the instructions in the current article to enable monitoring.

Connection string and instrumentation key

When codeless monitoring is being used, only the connection string is required. However, we still recommend setting the instrumentation key to preserve backwards compatibility with older versions of the SDK when manual instrumentation is being performed.

Difference between Standard Metrics from Application Insights vs Azure App Service metrics?

Application Insights collects telemetry for those requests which made it to the application. If the failure occurred in WebApps/WebServer, and the request did not reach the user application, then Application Insights will not have any telemetry about it.

The duration for serverresponsetime calculated by Application Insights is not necessarily matching the server response time observed by Web Apps. This is because Application Insights only counts the duration when the request actual reaches user application. If the request is stuck/queued in WebServer, that waiting time will be included in the Web App metrics, but not in Application Insights metrics.

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. 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 Microsoft.ApplicationInsights.AspNetCore, 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 reference Microsoft.ApplicationInsights.
AppAlreadyInstrumented:true This value can also be caused by the presence of Microsoft.ApplicationsInsights dll 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).
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.

Release notes

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

Next steps