App Service auto-instrumentation vs the SDK: which one to run

“Codeless”, “agent-based” and “auto-instrumentation” all mean the same thing in Microsoft’s docs: the platform loads monitoring into your process at startup, configured by app settings rather than by code you ship. It’s the quickest way to get the Performance and Failures views and Application Map working, and the right answer for many apps. Its limits show up the first time you want something the platform doesn’t expose.

Where auto-instrumentation exists

Microsoft’s support matrix, checked for this guide:

Windows containers on App Service are a preview for .NET Framework, .NET, Java and Node.js. Container deployments are single-container only; multi-container and sidecar apps need code-based instrumentation. Azure Container Apps is different again: its managed OpenTelemetry agent forwards what your app emits, so you still add an OpenTelemetry SDK, and the Application Insights destination accepts logs and traces but not metrics. Container Apps describes that agent as a preview.

App Service: what the switch does

In the portal, open the app, select Application Insights > Enable, pick a resource and select Apply monitoring settings. App Service restarts the app. For templates and pipelines, the same thing is four app settings.

App settings that turn on auto-instrumentation for an ASP.NET Core app on Linux (use ~2 on Windows):

"appSettings": [
  { "name": "APPLICATIONINSIGHTS_CONNECTION_STRING", "value": "<connection string>" },
  { "name": "ApplicationInsightsAgent_EXTENSION_VERSION", "value": "~3" },
  { "name": "XDT_MicrosoftApplicationInsights_Mode", "value": "recommended" },
  { "name": "XDT_MicrosoftApplicationInsights_PreemptSdk", "value": "1" }
]

What you get depends on the stack:

• ASP.NET Core. Recommended collects requests, dependencies, exceptions and browser monitoring (the JavaScript snippet, on by default; set APPINSIGHTS_JAVASCRIPT_ENABLED to false to stop it). Microsoft is explicit that App Service offers no extra settings here: changing sampling, enrichment or custom telemetry means code-based instrumentation. Trimmed self-contained deployments aren’t supported.
• ASP.NET on .NET Framework. Basic or Recommended; only Recommended adds CPU, memory and I/O trends and correlation across request and dependency boundaries. Adaptive sampling is tuned with app settings such as MicrosoftAppInsights_AdaptiveSamplingTelemetryProcessor_MaxTelemetryItemsPerSecond, and setting ..._MinSamplingPercentage to 100 turns it off. SQL command text needs InstrumentationEngine_EXTENSION_VERSION=~1 plus XDT_MicrosoftApplicationInsights_BaseExtensions=~1, and both can lengthen cold starts.
• Java. App Service attaches the Java 3.x agent, which collects requests, dependencies, logs (Log4j, Logback, JBoss Logging, java.util.logging), Micrometer metrics and heartbeats. Configure it with APPLICATIONINSIGHTS_CONFIGURATION_CONTENT (inline JSON) or APPLICATIONINSIGHTS_CONFIGURATION_FILE. On Windows, also set XDT_MicrosoftApplicationInsights_Java=1.
• Node.js. Requests, dependencies, exceptions, traces and heartbeats. Microsoft lists Node.js auto-instrumentation as a public preview; on Windows it also needs XDT_MicrosoftApplicationInsights_NodeJS=1.
• Python. Linux, deployed as code, Python 3.9 through 3.13. It instruments Django, FastAPI, Flask, psycopg2, requests, urllib and urllib3 plus the root logger, and takes standard OTEL_* settings (OTEL_SERVICE_NAME, OTEL_TRACES_SAMPLER_ARG, OTEL_PYTHON_DISABLED_INSTRUMENTATIONS). Live Metrics isn’t available.

Classic SDK 2.x

Auto-instrumentation on Windows servers started with Status Monitor. Its replacement is the Application Insights Agent, the PowerShell module Az.ApplicationMonitor. The newest version on the PowerShell Gallery is 2.0.0, last published on February 10, 2023, and 2.0.0 is the release that added ASP.NET Core apps hosted in IIS. It supports ASP.NET and ASP.NET Core on IIS only; Java and Node.js need an SDK.

Enable-ApplicationInsightsMonitoring edits IIS’s applicationHost.config, writes an applicationinsights.ikey.config, and registers a module that loads the Application Insights SDK into each app as it starts. On Azure VMs and scale sets, the same agent ships as the Application Insights Agent VM extension. Its documentation lives in Microsoft’s archived Classic API 2.x pages, which carry the notice that the .NET 2.x SDK retires on March 31, 2027; Microsoft doesn’t state a separate date for the agent.

Enable the agent on an IIS server with one connection string for every site (run as administrator):

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force
Install-Module -Name Az.ApplicationMonitor -AllowPrerelease -AcceptLicense
Enable-ApplicationInsightsMonitoring -ConnectionString 'InstrumentationKey=...;IngestionEndpoint=https://...'
# Restart IIS, then confirm which sites are instrumented:
Get-ApplicationInsightsMonitoringStatus

The status output answers the “both at once” question for IIS. A site whose process already loads Application Insights assemblies shows AppAlreadyInstrumented : true: the agent assumed the app was instrumented by hand and backed off. That makes the IIS agent safe to roll out across a farm where some apps already reference the SDK.

For Azure Cloud Services, Microsoft’s dependency-tracking table still lists a startup task that installs Status Monitor, with the SDK added to the app at build time.

Today: SDK 3.x and the Microsoft OpenTelemetry Distro

Code-based instrumentation is what Microsoft points you to as soon as the defaults aren’t enough. For a new .NET app that’s the Microsoft OpenTelemetry Distro; for an app on the 2.x SDK it’s an upgrade to SDK 3.x (AddApplicationInsightsTelemetry() keeps working). The SDK vs Distro guide compares them. Both read APPLICATIONINSIGHTS_CONNECTION_STRING, so the app setting App Service already created keeps doing its job.

Program.cs for an ASP.NET Core app moving from auto-instrumentation to the Distro:

using Microsoft.OpenTelemetry;

var builder = WebApplication.CreateBuilder(args);

// Reads APPLICATIONINSIGHTS_CONNECTION_STRING from the App Service app settings.
builder.UseMicrosoftOpenTelemetry(options =>
{
    options.Exporters = ExportTarget.AzureMonitor;
});

var app = builder.Build();
app.Run();

Then set XDT_MicrosoftApplicationInsights_Mode to disabled (or choose Disabled in the portal) so the platform agent stops collecting. On App Service, Microsoft’s page names PreemptSdk as required for ASP.NET Core auto-instrumentation but doesn’t document which collector wins when an app also carries its own SDK or Distro, so don’t rely on either winning. AKS does document it: the injected instrumentation coexists with manual instrumentation and prevents duplicates, with manual instrumentation taking precedence for Node.js and auto-instrumentation taking precedence for Java.

Azure Functions

Functions is auto-instrumented as soon as APPLICATIONINSIGHTS_CONNECTION_STRING is set; the older APPINSIGHTS_INSTRUMENTATIONKEY setting is deprecated. The host samples by default, at up to 20 telemetry items per second, applied separately on each host that runs the app; the settings live in host.json.

host.json that keeps every execution and exception while sampling the rest:

{
  "version": "2.0",
  "logging": {
    "applicationInsights": {
      "samplingSettings": {
        "isEnabled": true,
        "maxTelemetryItemsPerSecond": 20,
        "excludedTypes": "Request;Exception"
      }
    }
  }
}

If your function code also uses the Application Insights SDK, Microsoft warns of unusual behaviour when its sampling differs from the host’s: keep them the same. Function executions are logged under the Host.Results category at Information, so a log level of Warning or higher for that category also removes rows from requests.

To move a function app to OpenTelemetry, add "telemetryMode": "OpenTelemetry" at the root of host.json and configure the worker in code. Once you do, the logging.applicationInsights section (sampling included) no longer applies, and log streaming in the portal isn’t supported.

Program.cs in a .NET isolated function app that exports OpenTelemetry to Application Insights:

builder.Services.AddOpenTelemetry()
    .UseFunctionsWorkerDefaults()
    .UseAzureMonitorExporter();

Check how many collectors you have

Two collectors on one app usually show up as two SDK version strings for the same role in the same hour. The sdkVersion column (SDKVersion in AppRequests) records which library sent each row:

requests
| where timestamp > ago(1h)
| summarize requests = sum(itemCount) by cloud_RoleName, sdkVersion
| order by cloud_RoleName asc

Duplicated request counts in the latency by operation query are the other giveaway. The sampling guide explains why the itemCount weighting matters here.

Troubleshooting