DiagnosticServices 3.24.0-beta3

Microsoft Diagnostic Services site extension

This Azure App Service site extension enables Microsoft Diagnostic Services for .NET web apps:

• Application Insights Profiler — captures distributed traces and CPU/latency hot paths in production.
• Snapshot Debugger — collects debug snapshots when exceptions occur, with call stack and variable values.

Enable the site extension

Applies to: Windows App Service on a Basic (B1) or higher plan. Free/Shared plans do not support site extensions.

This gallery extension runs on top of the platform preinstalled DiagnosticServices extension that Azure App Service activates when you turn on Application Insights + Profiler/Snapshot Debugger. So two things must be in place: (1) Application Insights + Profiler/Snapshot Debugger enabled (activates the preinstalled extension), and (2) this gallery extension installed on top.

Choose the approach that fits how you manage your App Service:

• Approach A — Manual (portal / Kudu): enable Application Insights + Profiler/Snapshot Debugger, and install this gallery extension.
• Approach B — ARM template (all-in-one): does both in a single deployment. Recommended for repeatable / Infrastructure-as-Code setups — no separate enablement step needed.

Approach A — Manual (portal / Kudu)

Two things need to be in place — enable Application Insights + Profiler/Snapshot Debugger and install this gallery extension. You can do them in either order; just restart the app once both are done.

Enable Application Insights, Profiler and Snapshot Debugger

1. Open your App Service in the Azure portal.
2. In the left menu, select Application Insights (under Monitoring).
3. Click Turn on Application Insights, then either Select an existing resource or create a new one. This adds the APPLICATIONINSIGHTS_CONNECTION_STRING app setting.
4. In the .NET (or .NET Core) section, set Collection Level to Recommended, and toggle Profiler and Snapshot Debugger to On.
5. Click Apply and confirm the restart.

This enables the codeless Application Insights agent and the platform preinstalled DiagnosticServices extension via app settings (ApplicationInsightsAgent_EXTENSION_VERSION, DiagnosticServices_EXTENSION_VERSION, APPINSIGHTS_PROFILERFEATURE_VERSION, APPINSIGHTS_SNAPSHOTFEATURE_VERSION). Leave these settings in place — the gallery extension layers on top of them.

Install this gallery site extension

Pick one of the ways below. After installing, always fully restart the app (Azure portal → Overview → Restart) — the SCM/Kudu "restart" only reloads the Kudu site, but the main worker must restart for the extension's applicationHost.xdt transform to apply.

Option 1 — Azure portal (easiest)

1. In your App Service, select Extensions (under Development Tools).
2. Click + Add, choose DiagnosticServices Site Extension from the list, accept the terms, and click OK.
3. Go to Overview and click Restart.

Option 2 — Kudu SCM site (no portal needed)

1. Browse to https://<your-site>.scm.azurewebsites.net/siteextensions.
2. Find DiagnosticServices Site Extension in the Gallery tab and click + Install.
3. Restart the app from the Azure portal (Overview → Restart).

Option 3 — Kudu REST API (scriptable, can pin a version)

Authenticate with the site's publishing credentials and PUT the package id:

# install the latest version
PUT https://<your-site>.scm.azurewebsites.net/api/siteextensions/DiagnosticServices

# install (or roll back to) a specific version
PUT https://<your-site>.scm.azurewebsites.net/api/siteextensions/DiagnosticServices
Body: { "id": "DiagnosticServices", "version": "3.24.0" }

Then restart the app. Related endpoints: GET /api/siteextensions (list installed), DELETE /api/siteextensions/DiagnosticServices (uninstall).

Approach B — ARM template (all-in-one)

The template does both things in one deployment, so you do not turn on the preinstalled extension separately: it sets the enablement app settings on the Web App and adds the Microsoft.Web/sites/siteextensions child resource for the gallery extension.

{
  "type": "Microsoft.Web/sites",
  "apiVersion": "2023-12-01",
  "name": "[parameters('webAppName')]",
  "location": "[parameters('location')]",
  "properties": {
    "serverFarmId": "[resourceId('Microsoft.Web/serverfarms', parameters('appServicePlanName'))]",
    "httpsOnly": true,
    "siteConfig": {
      "alwaysOn": true,
      "appSettings": [
        { "name": "APPLICATIONINSIGHTS_CONNECTION_STRING", "value": "[parameters('appInsightsConnectionString')]" },
        { "name": "ApplicationInsightsAgent_EXTENSION_VERSION", "value": "~2" },
        { "name": "DiagnosticServices_EXTENSION_VERSION", "value": "~3" },
        { "name": "APPINSIGHTS_PROFILERFEATURE_VERSION", "value": "1.0.0" },
        { "name": "APPINSIGHTS_SNAPSHOTFEATURE_VERSION", "value": "1.0.0" },
        { "name": "InstrumentationEngine_EXTENSION_VERSION", "value": "disabled" },
        { "name": "SnapshotDebugger_EXTENSION_VERSION", "value": "disabled" },
        { "name": "XDT_MicrosoftApplicationInsights_BaseExtensions", "value": "disabled" },
        { "name": "XDT_MicrosoftApplicationInsights_Mode", "value": "recommended" },
        { "name": "XDT_MicrosoftApplicationInsights_PreemptSdk", "value": "disabled" }
      ]
    }
  }
},
{
  "type": "Microsoft.Web/sites/siteextensions",
  "apiVersion": "2023-12-01",
  "name": "[format('{0}/{1}', parameters('webAppName'), 'DiagnosticServices')]",
  "dependsOn": [
    "[resourceId('Microsoft.Web/sites', parameters('webAppName'))]"
  ],
  "properties": {}
}

What the two pieces do:

• The app settings (ApplicationInsightsAgent_EXTENSION_VERSION, DiagnosticServices_EXTENSION_VERSION, APPINSIGHTS_PROFILERFEATURE_VERSION, APPINSIGHTS_SNAPSHOTFEATURE_VERSION) turn on Application Insights and the platform preinstalled DiagnosticServices extension — the IaC equivalent of the portal enablement blade. Set APPLICATIONINSIGHTS_CONNECTION_STRING to your Application Insights resource's connection string.
• The siteextensions resource installs this gallery extension on top and dependsOn the site, so it is applied after the settings.

The siteConfig above shows only the settings relevant to enabling the extension. Keep your app's existing runtime settings (for example netFrameworkVersion); this example intentionally omits them so applying it does not change your app's configured stack.

Note: ARM installs the latest available version — App Service generally ignores the version property for gallery site extensions (known limitation). To pin a version, use the Kudu REST API (Approach A, Option 3) or stage a specific .nupkg.

Deploy the full template (which typically also creates the workspace-based Application Insights and feeds its connection string into the app settings above) with the Azure CLI:

az group create --name my-rg --location westus2
az deployment group create --resource-group my-rg \
  --template-file azuredeploy.json \
  --parameters webAppName=my-unique-site

The deployment applies the app settings and installs the extension, but the main worker may not pick up the extension's applicationHost.xdt transform on the same start. After the deployment finishes, do a full site restart (Azure portal → Overview → Restart, or az webapp restart -g my-rg -n my-unique-site) so the transform takes effect.

After enabling

Once the app has restarted, verify:

• The Application Insights blade shows Profiler and Snapshot Debugger as On.
• Under Extensions, DiagnosticServices Site Extension is listed as installed.
• After some load/traffic, traces appear under Application Insights → Investigate → Performance → Profiler, and snapshots under Failures → open exception → Debug snapshot.

Profiler and Snapshot Debugger keep being configured from the Application Insights blade — the gallery extension only supplies the runtime bits.

Works alongside the platform preinstalled extension

Azure App Service ships a platform preinstalled DiagnosticServices extension that the enablement app settings activate via the codeless Application Insights agent. This gallery extension is designed to run on top of it — you do not need to disable the preinstalled one.

Just remember to do a full site restart after installing (Azure portal → Overview → Restart). This is safe: the gallery extension de-duplicates the shared DOTNET_STARTUP_HOOKS / ASPNETCORE_HOSTINGSTARTUPASSEMBLIES entries, so its hook replaces the preinstalled one instead of colliding (two identical startup hooks would otherwise abort startup with HTTP 500.30).

Learn more

• Application Insights Profiler
• Snapshot Debugger